Dokka (#1708)

* dokka

* test

* Fix classpath

* Fix deploy

* Fix deploy

* Fix deploy

* GitHub workflows

.github/workflows/build.yml

@@ -58,4 +58,7 @@ jobs:
           ./gradlew check --scan
           -Dmirai.network.show.all.components=true
           -Dkotlinx.coroutines.debug=on
-          -Dmirai.network.show.packet.details=true
+          -Dmirai.network.show.packet.details=true
+
+      - name: Ensure KDoc valid
+        run: ./gradlew dokkaHtmlMultiModule

.github/workflows/doc.yml

@@ -1,48 +1,17 @@
-# 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
+  push:
+    tags:
+      - 'v*' # 正式版本
+
 
-# 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"
-  mirai-core-docs:
+  mirai-docs:
     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: chmod -R 777 *
-        run: chmod -R 777 *
-      - name: Gradle build
-        run: ./gradlew clean build # if test's failed, don't publish
-      - name: Dokka
-        run: ./gradlew :mirai-core-api:dokkaHtml
-      - name: GitHub Pages Deploy
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          personal_token: ${{ secrets.MAMOE_TOKEN }}
-          publish_dir: ./mirai-core-api/build/dokka
-          external_repository: project-mirai/mirai-doc
-          publish_branch: master
-          user_name: 'mamoebot'
-          user_email: 'mamoebot@users.noreply.github.com'
-          keep_files: true
-
-  # This workflow contains a single job called "build"
-  mirai-console-docs:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
+      - name: Checkout repository
+        uses: actions/checkout@v2
 
       - name: Checkout submodules
         run: git submodule update --init --recursive
@@ -54,18 +23,17 @@ jobs:
 
       - name: chmod -R 777 *
         run: chmod -R 777 *
-      - name: Gradle build
-        run: ./gradlew clean build # if test's failed, don't publish
-      - name: Dokka
-        run: ./gradlew :mirai-console:dokkaHtml
-      - name: GitHub Pages Deploy
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          personal_token: ${{ secrets.MAMOE_TOKEN }}
-          publish_dir: ./mirai-console/build/dokka
-          external_repository: project-mirai/mirai-doc
-          publish_branch: master
-          user_name: 'mamoebot'
-          user_email: 'mamoebot@users.noreply.github.com'
-          keep_files: true
 
+      - name: Prepare environment
+        run: ./gradlew :mirai-dokka:prepare
+
+      - name: Dokka
+        run: ./gradlew dokkaHtmlMultiModule
+
+      - name: Update version number
+        run: ./gradlew :mirai-dokka:update-vers
+
+      - name: Deploy
+        run: ./gradlew :mirai-dokka:deployPages
+        env:
+          gh_token: ${{ secrets.MAMOE_TOKEN }}

build.gradle.kts

@@ -12,6 +12,9 @@
 import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
 import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
 import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+import java.time.LocalDateTime
 
 buildscript {
     repositories {
@@ -28,12 +31,14 @@ buildscript {
         classpath("com.android.tools.build:gradle:${Versions.androidGradlePlugin}")
         classpath("org.jetbrains.kotlinx:atomicfu-gradle-plugin:${Versions.atomicFU}")
         classpath("org.jetbrains.kotlinx:binary-compatibility-validator:${Versions.binaryValidator}")
+        classpath("org.jetbrains.dokka:dokka-base:${Versions.dokka}")
     }
 }
 
 plugins {
     kotlin("jvm") // version Versions.kotlinCompiler
     kotlin("plugin.serialization") version Versions.kotlinCompiler
+    id("org.jetbrains.dokka") version Versions.dokka
 //    id("org.jetbrains.dokka") version Versions.dokka
     id("net.mamoe.kotlin-jvm-blocking-bridge") version Versions.blockingBridge
     id("com.gradle.plugin-publish") version "0.12.0" apply false
@@ -114,6 +119,7 @@ subprojects {
         if (project.name == "mirai-console") configureDokka()
     }
 }
+rootProject.configureDokka()
 
 tasks.register("cleanExceptIntellij") {
     group = "build"
@@ -140,36 +146,55 @@ fun Project.useIr() {
 }
 
 fun Project.configureDokka() {
-//    apply(plugin = "org.jetbrains.dokka")
-//    tasks {
-//        val dokkaHtml by getting(org.jetbrains.dokka.gradle.DokkaTask::class) {
-//            outputDirectory.set(buildDir.resolve("dokka"))
-//        }
-//        val dokkaGfm by getting(org.jetbrains.dokka.gradle.DokkaTask::class) {
-//            outputDirectory.set(buildDir.resolve("dokka-gfm"))
-//        }
-//    }
-//    tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
-//        dokkaSourceSets.configureEach {
-//            perPackageOption {
-//                matchingRegex.set("net\\.mamoe\\.mirai\\.*")
-//                skipDeprecated.set(true)
-//            }
-//
-//            for (suppressedPackage in arrayOf(
-//                """net.mamoe.mirai.internal""",
-//                """net.mamoe.mirai.internal.message""",
-//                """net.mamoe.mirai.internal.network""",
-//                """net.mamoe.mirai.console.internal""",
-//                """net.mamoe.mirai.console.compiler.common"""
-//            )) {
-//                perPackageOption {
-//                    matchingRegex.set(suppressedPackage.replace(".", "\\."))
-//                    suppress.set(true)
-//                }
-//            }
-//        }
-//    }
+    val isRoot = this@configureDokka == rootProject
+    if (!isRoot) {
+        apply(plugin = "org.jetbrains.dokka")
+    }
+
+    tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaTask>().configureEach {
+        pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+            this.footerMessage = """Copyright 2019-${
+                LocalDateTime.now().year
+            } <a href="https://github.com/mamoe">Mamoe Technologies</a> and contributors.
+            Source code:
+            <a href="https://github.com/mamoe/mirai">GitHub</a>
+            """.trimIndent()
+
+            this.customAssets = listOf(
+                rootProject.projectDir.resolve("mirai-dokka/frontend/ext.js"),
+            )
+        }
+    }
+
+    tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>().configureEach {
+        dokkaSourceSets.configureEach {
+            perPackageOption {
+                matchingRegex.set("net\\.mamoe\\.mirai\\.*")
+                skipDeprecated.set(true)
+            }
+
+            for (suppressedPackage in arrayOf(
+                """net.mamoe.mirai.internal""",
+                """net.mamoe.mirai.internal.message""",
+                """net.mamoe.mirai.internal.network""",
+                """net.mamoe.mirai.console.internal""",
+                """net.mamoe.mirai.console.compiler.common"""
+            )) {
+                perPackageOption {
+                    matchingRegex.set(suppressedPackage.replace(".", "\\."))
+                    suppress.set(true)
+                }
+            }
+        }
+    }
+
+    if (isRoot) {
+        tasks.named<org.jetbrains.dokka.gradle.AbstractDokkaTask>("dokkaHtmlMultiModule").configure {
+            outputDirectory.set(
+                rootProject.projectDir.resolve("mirai-dokka/pages/snapshot")
+            )
+        }
+    }
 }
 
 fun Project.configureMppShadow() {

buildSrc/src/main/kotlin/Versions.kt

@@ -22,7 +22,7 @@ object Versions {
 
     const val kotlinCompiler = "1.5.30"
     const val kotlinStdlib = "1.5.30"
-    const val dokka = "1.4.32"
+    const val dokka = "1.6.0"
 
     const val coroutines = "1.5.1"
     const val atomicFU = "0.16.3"

mirai-core-api/src/commonMain/kotlin/contact/Group.kt

@@ -50,7 +50,6 @@ import net.mamoe.mirai.utils.NotStableForInheritance
  *
  * 可通过 [Group.announcements] 获取公告支持. 可在 [Announcements] 查看详细文档.
  *
- * ##
  */
 @NotStableForInheritance
 public interface Group : Contact, CoroutineScope, FileSupported, AudioSupported {

mirai-dokka/.gitignore

@@ -0,0 +1 @@
+/pages

mirai-dokka/build.gradle.kts

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019-2021 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+plugins {
+    kotlin("jvm")
+    kotlin("plugin.serialization")
+    id("java")
+    `maven-publish`
+}
+
+dependencies {
+    implementation(`kotlinx-serialization-core-jvm`)
+    implementation(`kotlinx-serialization-json-jvm`)
+}
+
+fun Project.newExec(name: String, type: String, conf: JavaExec.() -> Unit) {
+    tasks.create(name, JavaExec::class.java) {
+        this.classpath = sourceSets["main"].runtimeClasspath
+        this.mainClass.set("net.mamoe.mirai.dokka.${type}Kt")
+        this.workingDir(rootProject.projectDir)
+        this.environment("mirai_ver", rootProject.version.toString())
+        conf()
+    }
+}
+
+newExec("prepare", "Prepare") {
+}
+
+newExec("deployPages", "DeployToGitHub") {
+}
+
+newExec("update-vers", "BuildVersionList") {
+}
+
+

mirai-dokka/frontend/ext.js

@@ -0,0 +1,37 @@
+// noinspection ES6ConvertVarToLetConst,JSUnresolvedVariable
+
+/*
+ * Copyright 2019-2021 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+
+
+(function () {
+    fetch(window.pathToRoot + "../versions.json").then(function (it) {
+        return it.json()
+    }).then(function (rsp) {
+        console.log(rsp);
+        var dir = document.getElementById("searchBar").parentElement;
+        var select = document.createElement("select");
+        dir.insertBefore(select, dir.firstElementChild);
+        select.appendChild(document.createElement("option")).textContent = "other version";
+        var toLatest = select.appendChild(document.createElement("option"));
+        toLatest.textContent = "latest";
+        toLatest.value = "";
+        for (var v of rsp) {
+            var c = select.appendChild(document.createElement("option"));
+            c.textContent = v;
+            c.value = v;
+        }
+        select.addEventListener("change", function (event) {
+            location.href = window.pathToRoot + "../" + c.value
+        })
+    }).catch(function (error) {
+        console.log(error);
+    })
+})()

mirai-dokka/src/BuildVersionList.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2019-2021 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+package net.mamoe.mirai.dokka
+
+import kotlinx.serialization.builtins.ListSerializer
+import kotlinx.serialization.builtins.serializer
+
+
+fun main() {
+    val currentVersion = System.getenv("mirai_ver") ?: error("version not found")
+
+    val versions = pages.resolve("versions.json")
+
+    json.decodeFromString(ListSerializer(String.serializer()), versions.readText()).toMutableList().let { list ->
+        if (currentVersion in list) return@let
+        list.add(currentVersion)
+        versions.writeText(json.encodeToString(ListSerializer(String.serializer()), list))
+    }
+
+    pages.resolve("snapshot").renameTo(pages.resolve(currentVersion))
+}

mirai-dokka/src/DeployToGitHub.kt

@@ -0,0 +1,33 @@
+/*
+ * Copyright 2019-2021 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+package net.mamoe.mirai.dokka
+
+fun main() {
+    val token = System.getenv("gh_token") ?: error("Token not found")
+    val currentVersion = System.getenv("mirai_ver") ?: error("version not found")
+
+    repoexec("git", "config", "--local", "http.https://github.com/.extraheader", "")
+    runCatching {
+        repoexec("git", "remote", "remove", "token")
+    }
+    repoexec(
+        "git", "remote", "add", "token",
+        "https://x-access-token:$token@github.com/project-mirai/mirai-doc.git"
+    )
+
+    repoexec("git", "config", "--local", "user.email", "mamoebot@users.noreply.github.com")
+    repoexec("git", "config", "--local", "user.name", "mamoebot")
+    repoexec("git", "add", "-A")
+    repoexec(
+        "git", "commit", "-m", currentVersion,
+        nooutput = true,
+    )
+    repoexec("git", "push", "token", "HEAD:master")
+}

mirai-dokka/src/Prepare.kt

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2019-2021 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+package net.mamoe.mirai.dokka
+
+fun main() {
+    if (pages.resolve(".git").isDirectory) {
+        return
+    }
+    exec("git", "clone", "https://github.com/project-mirai/mirai-doc.git", pages.absolutePath)
+}

mirai-dokka/src/system.kt

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2019-2021 Mamoe Technologies and contributors.
+ *
+ * 此源代码的使用受 GNU AFFERO GENERAL PUBLIC LICENSE version 3 许可证的约束, 可以在以下链接找到该许可证.
+ * Use of this source code is governed by the GNU AGPLv3 license that can be found through the following link.
+ *
+ * https://github.com/mamoe/mirai/blob/dev/LICENSE
+ */
+
+package net.mamoe.mirai.dokka
+
+import kotlinx.serialization.json.Json
+import java.io.File
+
+val pages = File("mirai-dokka/pages")
+val json = Json {
+    prettyPrint = true
+    prettyPrintIndent = "  "
+}
+
+private val FileDevNull = File(
+    if (System.getProperty("os.name")
+            .startsWith("Windows")
+    ) "NUL" else "/dev/null"
+)
+
+fun system(cmd: String) {
+    val rsp = ProcessBuilder(cmd).inheritIO().start().waitFor()
+    if (rsp != 0) error("Exec return $rsp, $cmd")
+}
+
+fun exec(vararg cmd: String) {
+    val rsp = ProcessBuilder(*cmd).inheritIO().start().waitFor()
+    if (rsp != 0) error("Exec return $rsp, ${cmd.joinToString(" ")}")
+}
+
+fun repoexec(
+    vararg cmd: String,
+    nooutput: Boolean = false,
+) {
+    val rsp = ProcessBuilder(*cmd)
+        .inheritIO()
+        .directory(pages)
+        .also { builder ->
+            if (nooutput) {
+                builder.redirectOutput(ProcessBuilder.Redirect.to(FileDevNull))
+            }
+        }
+        .start()
+        .waitFor()
+    if (rsp != 0) error("Exec return $rsp, ${cmd.joinToString(" ")}")
+}

settings.gradle.kts

@@ -31,6 +31,7 @@ include(":mirai-core-api")
 include(":mirai-core")
 include(":mirai-core-all")
 include(":mirai-bom")
+include(":mirai-dokka")
 
 include(":binary-compatibility-validator")
 include(":binary-compatibility-validator-android")