From d10d20302e4bf41c147926d8a96303e56a7c3959 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=BE=AE=E8=8E=B9=C2=B7=E7=BA=A4=E7=BB=AB?= Date: Sat, 4 Dec 2021 23:43:09 +0800 Subject: [PATCH] Dokka (#1708) * dokka * test * Fix classpath * Fix deploy * Fix deploy * Fix deploy * GitHub workflows --- .github/workflows/build.yml | 5 +- .github/workflows/doc.yml | 72 +++++----------- build.gradle.kts | 85 ++++++++++++------- buildSrc/src/main/kotlin/Versions.kt | 2 +- .../src/commonMain/kotlin/contact/Group.kt | 1 - mirai-dokka/.gitignore | 1 + mirai-dokka/build.gradle.kts | 41 +++++++++ mirai-dokka/frontend/ext.js | 37 ++++++++ mirai-dokka/src/BuildVersionList.kt | 28 ++++++ mirai-dokka/src/DeployToGitHub.kt | 33 +++++++ mirai-dokka/src/Prepare.kt | 17 ++++ mirai-dokka/src/system.kt | 52 ++++++++++++ settings.gradle.kts | 1 + 13 files changed, 290 insertions(+), 85 deletions(-) create mode 100644 mirai-dokka/.gitignore create mode 100644 mirai-dokka/build.gradle.kts create mode 100644 mirai-dokka/frontend/ext.js create mode 100644 mirai-dokka/src/BuildVersionList.kt create mode 100644 mirai-dokka/src/DeployToGitHub.kt create mode 100644 mirai-dokka/src/Prepare.kt create mode 100644 mirai-dokka/src/system.kt diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index decd5f546..fddf7f476 100644 --- a/.github/workflows/build.yml +++ b/.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 \ No newline at end of file + -Dmirai.network.show.packet.details=true + + - name: Ensure KDoc valid + run: ./gradlew dokkaHtmlMultiModule diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index c1b30efb5..3e319c8ad 100644 --- a/.github/workflows/doc.yml +++ b/.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 }} diff --git a/build.gradle.kts b/build.gradle.kts index 8949d30b0..0cb695b25 100644 --- a/build.gradle.kts +++ b/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().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().configureEach { + pluginConfiguration { + this.footerMessage = """Copyright 2019-${ + LocalDateTime.now().year + } Mamoe Technologies and contributors. + Source code: + GitHub + """.trimIndent() + + this.customAssets = listOf( + rootProject.projectDir.resolve("mirai-dokka/frontend/ext.js"), + ) + } + } + + tasks.withType().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("dokkaHtmlMultiModule").configure { + outputDirectory.set( + rootProject.projectDir.resolve("mirai-dokka/pages/snapshot") + ) + } + } } fun Project.configureMppShadow() { diff --git a/buildSrc/src/main/kotlin/Versions.kt b/buildSrc/src/main/kotlin/Versions.kt index 9db29bdc6..f9eb6396d 100644 --- a/buildSrc/src/main/kotlin/Versions.kt +++ b/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" diff --git a/mirai-core-api/src/commonMain/kotlin/contact/Group.kt b/mirai-core-api/src/commonMain/kotlin/contact/Group.kt index 4f6119cc5..5e621963a 100644 --- a/mirai-core-api/src/commonMain/kotlin/contact/Group.kt +++ b/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 { diff --git a/mirai-dokka/.gitignore b/mirai-dokka/.gitignore new file mode 100644 index 000000000..63fe86724 --- /dev/null +++ b/mirai-dokka/.gitignore @@ -0,0 +1 @@ +/pages diff --git a/mirai-dokka/build.gradle.kts b/mirai-dokka/build.gradle.kts new file mode 100644 index 000000000..18edf9608 --- /dev/null +++ b/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") { +} + + diff --git a/mirai-dokka/frontend/ext.js b/mirai-dokka/frontend/ext.js new file mode 100644 index 000000000..306165d4b --- /dev/null +++ b/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); + }) +})() diff --git a/mirai-dokka/src/BuildVersionList.kt b/mirai-dokka/src/BuildVersionList.kt new file mode 100644 index 000000000..119810bf8 --- /dev/null +++ b/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)) +} diff --git a/mirai-dokka/src/DeployToGitHub.kt b/mirai-dokka/src/DeployToGitHub.kt new file mode 100644 index 000000000..579f47a5b --- /dev/null +++ b/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") +} diff --git a/mirai-dokka/src/Prepare.kt b/mirai-dokka/src/Prepare.kt new file mode 100644 index 000000000..02deec44a --- /dev/null +++ b/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) +} diff --git a/mirai-dokka/src/system.kt b/mirai-dokka/src/system.kt new file mode 100644 index 000000000..9891e4ee6 --- /dev/null +++ b/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(" ")}") +} diff --git a/settings.gradle.kts b/settings.gradle.kts index 28a38a2f7..afbd75689 100644 --- a/settings.gradle.kts +++ b/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")