Setup mirai-doc publishing

.github/workflows/doc.yml

+# This is a basic workflow to help you get started with Actions
+
+name: mirai-doc Publish
+
+# Controls when the action will run. Triggers the workflow on push or pull request 
+# events but only for the master branch
+on:
+  release:
+    types:
+      - created
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up JDK 1.8
+        uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+      - name: Gradle clean
+        run: ./gradlew clean
+      - name: Gradle build
+        run: ./gradlew build # if test's failed, don't publish
+      - name: Gradle :mirai-core:dokkaGitHubUpload
+        run: ./gradlew :mirai-core:dokkaGitHubUpload -Dgithub_token=${{ secrets.MAMOE_TOKEN }} -Pgithub_token=${{ secrets.MAMOE_TOKEN }}
+      - name: Gradle :mirai-core-qqandroid:dokkaGitHubUpload
+        run: ./gradlew :mirai-core-qqandroid:dokkaGitHubUpload -Dgithub_token=${{ secrets.MAMOE_TOKEN }} -Pgithub_token=${{ secrets.MAMOE_TOKEN }}
+
+
+#      - name: Upload artifact
+#        uses: actions/upload-artifact@v1.0.0
+#        with:
+#          # Artifact name
+#          name: mirai-core
+#          # Directory containing files to upload
+#          path: "mirai-core/build/libs/mirai-core-*-all.jar"
+#      - name: Upload artifact
+#        uses: actions/upload-artifact@v1.0.0
+#        with:
+#          # Artifact name
+#          name: mirai-core-qqandroid-all
+#          # Directory containing files to upload
+#          path: "mirai-core-qqandroid/build/libs/mirai-core-qqandroid-*-all.jar"

build.gradle.kts

@@ -99,14 +99,16 @@ subprojects {
 
             doFirst {
                 timeout.set(Duration.ofHours(3))
-                findLatestFile()?.let { (_, file) ->
+                findLatestFile().let { (_, file) ->
                     val filename = file.name
                     println("Uploading file $filename")
                     runCatching {
                         upload.GitHub.upload(
                             file,
                             "https://api.github.com/repos/mamoe/mirai-repo/contents/shadow/${project.name}/$filename",
-                            project
+                            project,
+                            "mirai-repo",
+                            "shadow/"
                         )
                     }.exceptionOrNull()?.let {
                         System.err.println("GitHub Upload failed")
@@ -117,13 +119,63 @@ subprojects {
             }
         }
 
+        apply(plugin = "org.jetbrains.dokka")
+        this.tasks {
+            val dokka by getting(org.jetbrains.dokka.gradle.DokkaTask::class) {
+                outputFormat = "html"
+                outputDirectory = "$buildDir/dokka"
+            }
+            val dokkaMarkdown by creating(org.jetbrains.dokka.gradle.DokkaTask::class) {
+                outputFormat = "markdown"
+                outputDirectory = "$buildDir/dokka-markdown"
+            }
+            val dokkaGfm by creating(org.jetbrains.dokka.gradle.DokkaTask::class) {
+                outputFormat = "gfm"
+                outputDirectory = "$buildDir/dokka-gfm"
+            }
+        }
+
+        val dokkaGitHubUpload by tasks.creating {
+            group = "mirai"
+
+            dependsOn(tasks.getByName("dokkaMarkdown"))
+            doFirst {
+                val baseDir = file("./build/dokka-markdown")
+
+                timeout.set(Duration.ofHours(6))
+                file("build/dokka-markdown/").walk()
+                    .filter { it.isFile }
+                    .map { old ->
+                        if (old.name == "index.md") File(old.parentFile, "README.md").also { new -> old.renameTo(new) }
+                        else old
+                    }
+                    .forEach { file ->
+                        val filename = file.toRelativeString(baseDir)
+                        println("Uploading file $filename")
+                        runCatching {
+                            upload.GitHub.upload(
+                                file,
+                                "https://api.github.com/repos/mamoe/mirai-doc/contents/${project.name}/$filename",
+                                project,
+                                "mirai-doc",
+                                ""
+                            )
+                        }.exceptionOrNull()?.let {
+                            System.err.println("GitHub Upload failed")
+                            it.printStackTrace() // force show stacktrace
+                            throw it
+                        }
+                    }
+            }
+        }
+
         val cuiCloudUpload by tasks.creating {
             group = "mirai"
             dependsOn(shadowJvmJar)
 
             doFirst {
                 timeout.set(Duration.ofHours(3))
-                findLatestFile()?.let { (_, file) ->
+                findLatestFile().let { (_, file) ->
                     val filename = file.name
                     println("Uploading file $filename")
                     runCatching {
@@ -142,6 +194,46 @@ subprojects {
         }
     }
 
+    afterEvaluate {
+        tasks.filterIsInstance<org.jetbrains.dokka.gradle.DokkaTask>().forEach { task ->
+            with(task) {
+                configuration {
+                    perPackageOption {
+                        prefix = "net.mamoe.mirai"
+                        skipDeprecated = true
+                    }
+                    perPackageOption {
+                        prefix = "net.mamoe.mirai.internal"
+                        suppress = true
+                    }
+                    perPackageOption {
+                        prefix = "net.mamoe.mirai.event.internal"
+                        suppress = true
+                    }
+                    perPackageOption {
+                        prefix = "net.mamoe.mirai.utils.internal"
+                        suppress = true
+                    }
+                    perPackageOption {
+                        prefix = "net.mamoe.mirai.qqandroid.utils"
+                        suppress = true
+                    }
+                    perPackageOption {
+                        prefix = "net.mamoe.mirai.qqandroid.contact"
+                        suppress = true
+                    }
+                    perPackageOption {
+                        prefix = "net.mamoe.mirai.qqandroid.message"
+                        suppress = true
+                    }
+                    perPackageOption {
+                        prefix = "net.mamoe.mirai.qqandroid.network"
+                        suppress = true
+                    }
+                }
+            }
+        }
+    }
 }
 
 
@@ -153,7 +245,7 @@ fun Project.findLatestFile(): Map.Entry<String, File> {
         .onEach { println("matched file: ${it.name}") }
         .associateBy { it.nameWithoutExtension.substringAfterLast('-') }
         .onEach { println("versions: $it") }
-        .maxBy { (version, file) ->
+        .maxBy { (version, _) ->
             version.split('.').let {
                 if (it.size == 2) it + "0"
                 else it

buildSrc/src/main/kotlin/upload/GitHub.kt

@@ -70,23 +70,25 @@ object GitHub {
         )
     }
 
-    fun upload(file: File, url: String, project: Project) = runBlocking {
+    fun upload(file: File, url: String, project: Project, repo: String, baseFilePath: String) = runBlocking {
         val token = getGithubToken(project)
         println("token.length=${token.length}")
-        Http.put<String>("$url?access_token=$token") {
-            val sha = getGithubSha("mirai-repo", "shadow/${project.name}/${file.name}", "master", project)
-            println("sha=$sha")
-            val content = String(Base64.getEncoder().encode(file.readBytes()))
-            body = """
+        retryCatching(1000) {
+            Http.put<String>("$url?access_token=$token") {
+                val sha = getGithubSha(repo, "$baseFilePath${project.name}/${file.name}", "master", project)
+                println("sha=$sha")
+                val content = String(Base64.getEncoder().encode(file.readBytes()))
+                body = """
                     {
                       "message": "automatically upload on release",
                       "content": "$content"
                       ${if (sha == null) "" else """, "sha": "$sha" """}
                     }
                 """.trimIndent()
-        }.let {
-            println("Upload response: $it")
-        }
+            }.let {
+                println("Upload response: $it")
+            }
+        }.getOrThrow()
     }
 
 

docs/mirai.md

@@ -61,6 +61,7 @@ mirai 全部使用 Kotlin, 若你无法理解部分 API, 可先简略阅读 Kotl
 Kotlin 编译后生成 Java 方法 `public Object sendMessage(Message msg, Continuation<Unit> cont)`  
 Mirai 通过某种方式同时生成了桥梁方法 `public void sendMessage(Message msg)` 使得 Java 使用者可无缝接入。
 
+建议在 IDE 内打开本文件 (位置 /docs/mirai.md), 可以进行源码内跳转.
 
 ### 开始
 
@@ -81,7 +82,7 @@ Mirai 通过某种方式同时生成了桥梁方法 `public void sendMessage(Mes
 3. '消息'
    1. [消息对象 Message](../mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/Message.kt)  
       特别注意, `Message` 分为 单个消息(`SingleMessage`) 和 多个消息, 即消息链(`MessageChain` ).  
-      // TODO 此处还有更详细的扩展 API 解释, 待更新
+      - 
    2. [消息链 MessageChain](../mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/MessageChain.kt)  
       // TODO 此处还有更详细的扩展 API 解释, 待更新
    3. 接下来可按需阅读各类型消息 [各类型消息](../mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/data/). 一个文件包含一种消息.
@@ -96,7 +97,7 @@ Mirai 通过某种方式同时生成了桥梁方法 `public void sendMessage(Mes
    4. 内建事件列表 [README](../mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/events/README.md).  
       **注意**: mirai 将接收到的消息事件独立放置在 `net.mamoe.mirai.message` 下, 并命名为 `MessageEvent`. 并为他们实现了一些扩展. 详见 [MessageEvent.kt](../mirai-core/src/commonMain/kotlin/net.mamoe.mirai/message/MessageEvent.kt)
    5. 事件工具类和工具函数 (仅 Kotlin) (可以跳过本节):  
-      标注 (*) 的几种处理方式可能需要比较好的 Kotlin 技能才能理解并正确使用. 建议在不熟悉时不要使用它们.  
+      标注 (*) 代表需要比较好的 Kotlin 技能才能理解.
       - 挂起当前协程, 直到返回下一个事件实例: [nextEvent](../mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/nextEvent.kt)
       - 挂起当前协程, 并从一个事件中同步一个值: [syncFromEvent](../mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/linear.kt)
       - (*) 消息事件监听 DSL: [subscribeMessages](../mirai-core/src/commonMain/kotlin/net.mamoe.mirai/event/subscribeMessages.kt)

mirai-core/build.gradle.kts

@@ -4,7 +4,6 @@ plugins {
     kotlin("multiplatform")
     id("kotlinx-atomicfu")
     kotlin("plugin.serialization")
-    id("org.jetbrains.dokka")
     id("signing")
     `maven-publish`
     id("com.jfrog.bintray") version Versions.Publishing.bintray
@@ -132,19 +131,4 @@ kotlin {
     }
 }
 
-tasks {
-    val dokka by getting(org.jetbrains.dokka.gradle.DokkaTask::class) {
-        outputFormat = "html"
-        outputDirectory = "$buildDir/dokka"
-    }
-    val dokkaMarkdown by creating(org.jetbrains.dokka.gradle.DokkaTask::class) {
-        outputFormat = "markdown"
-        outputDirectory = "$buildDir/dokka-markdown"
-    }
-    val dokkaGfm by creating(org.jetbrains.dokka.gradle.DokkaTask::class) {
-        outputFormat = "gfm"
-        outputDirectory = "$buildDir/dokka-gfm"
-    }
-}
-
 apply(from = rootProject.file("gradle/publish.gradle"))