Merge pull request #1012 from simple-robot/update-dokka

Update Dokka to 2.0.0

Author: ForteScarlet

.github/workflows/kdoc.yml.bk

@@ -121,9 +121,9 @@ jobs:
         uses: gradle/gradle-build-action@v3
         with:
           gradle-version: 8.3
-          arguments: | 
-            dokkaHtmlMultiModule
-            --info 
+          arguments: |
+            dokkaGenerate
+            -s
             --warning-mode all
             -x test
             --build-cache

.github/workflows/publish-release.yml

@@ -91,8 +91,8 @@ jobs:
         with:
           gradle-version: 8.3
           arguments: |
-            dokkaHtmlMultiModule
-            --info 
+            dokkaGenerate
+            -s
             --warning-mode all
             -x test
             --build-cache

.github/workflows/publish-snapshot.yml

@@ -18,7 +18,7 @@ env:
 jobs:
   deploy-doc:
     name: Deploy V4 API Doc
-    runs-on: macos-latest
+    runs-on: ubuntu-latest
     steps:
       # 检出仓库代码
       - uses: actions/checkout@v4
@@ -39,8 +39,8 @@ jobs:
         with:
           gradle-version: ${{ env.GRADLE_VERSION }}
           arguments: |
-            dokkaHtmlMultiModule
-            --info 
+            dokkaGenerate
+            -s
             --warning-mode all
             -x test
             --build-cache

.github/workflows/publish-v4-kdoc.yml

@@ -133,8 +133,8 @@ jobs:
         with:
           gradle-version: ${{ env.GRADLE_VERSION }}
           arguments: | 
-            dokkaHtmlMultiModule
-            --info 
+            dokkaGenerate
+            -s
             --warning-mode all
             -x test
             --build-cache

.github/workflows/publish-v4-release.yml

@@ -103,7 +103,7 @@ jobs:
   deploy-doc:
     name: Deploy snapshots API doc
     needs: publish-v4-snapshot
-    runs-on: macos-latest # ubuntu-latest
+    runs-on: ubuntu-latest
     steps:
       # 检出仓库代码
       - name: Check out repo
@@ -126,7 +126,7 @@ jobs:
         with:
           gradle-version: ${{ env.GRADLE_VERSION }}
           arguments: |
-            dokkaHtmlMultiModule
+            dokkaGenerate
             -s
             --warning-mode all
             -x test

.github/workflows/publish-v4-snapshot.yml

@@ -26,22 +26,27 @@ import changelog.generateChangelog
 import io.gitlab.arturbosch.detekt.Detekt
 import love.forte.plugin.suspendtrans.*
 import love.forte.plugin.suspendtrans.gradle.SuspendTransformGradleExtension
+import org.jetbrains.dokka.gradle.engine.parameters.DokkaSourceSetSpec
+import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
+import java.net.URI
+import java.time.Year
 
 plugins {
     idea
-    id("simbot.dokka-multi-module")
+    id("org.jetbrains.dokka")
+    // id("simbot.dokka-multi-module")
     id("com.github.gmazzo.buildconfig") version "5.5.1" apply false
     alias(libs.plugins.detekt)
     id("simbot.nexus-publish")
     alias(libs.plugins.suspendTransform) apply false
-    // id("love.forte.plugin.suspend-transform") version "2.1.0-0.9.4" apply false
-
 
     // https://www.jetbrains.com/help/qodana/code-coverage.html
     // https://github.com/Kotlin/kotlinx-kover
     alias(libs.plugins.kotlinxKover)
 
     alias(libs.plugins.kotlinxBinaryCompatibilityValidator)
+
+
 }
 
 setupGroup(P.Simbot)
@@ -378,9 +383,6 @@ fun Project.configureSuspendTransform() {
         includeRuntime = false
         includeAnnotation = false
 
-        // love.forte.simbot.suspendrunner.SuspendMarker
-        // targetMarker = ClassInfo("love.forte.simbot.suspendrunner", "SuspendMarker")
-
         addJvmTransformers(
             // @JvmBlocking
             SuspendTransforms.jvmBlockingTransformer,
@@ -404,3 +406,146 @@ fun Project.configureSuspendTransform() {
     }
 }
 // endregion
+
+// region Dokka
+subprojects {
+    afterEvaluate {
+        val p = this
+        if (plugins.hasPlugin(libs.plugins.dokka.get().pluginId)) {
+            dokka {
+                dokkaSourceSets.configureEach {
+                    configModuleMdInclude(p)
+                    configSourceLink(p)
+                    configExternalDocumentations()
+                }
+            }
+            rootProject.dependencies.dokka(p)
+        }
+    }
+}
+
+fun DokkaSourceSetSpec.configModuleMdInclude(project: Project) {
+    val moduleFile = project.file("Module.md")
+    if (moduleFile.exists() && moduleFile.length() > 0) {
+        includes.from("Module.md")
+    }
+}
+
+fun DokkaSourceSetSpec.configSourceLink(project: Project) {
+    sourceLink {
+        localDirectory.set(File(project.projectDir, "src"))
+        val relativeTo = project.projectDir.relativeTo(rootProject.projectDir).toString()
+            .replace('\\', '/')
+        // remoteUrl.set(URI.create("${P.HOMEPAGE}/tree/v4-dev/$relativeTo/src/").toURL())
+        remoteUrl.set(URI.create("${P.HOMEPAGE}/tree/v4-dev/$relativeTo/src"))
+        remoteLineSuffix.set("#L")
+    }
+}
+
+fun DokkaSourceSetSpec.configExternalDocumentations() {
+    fun externalDocumentation(name: String, docUrl: URI, suffix: String = "package-list") {
+        externalDocumentationLinks.register(name) {
+            url.set(docUrl)
+            packageListUrl.set(docUrl.resolve(suffix))
+        }
+    }
+
+    // kotlin-coroutines doc
+    externalDocumentation(
+        "kotlinx.coroutines",
+        URI.create("https://kotlinlang.org/api/kotlinx.coroutines/")
+    )
+
+    // kotlin-serialization doc
+    externalDocumentation(
+        "kotlinx.serialization",
+        URI.create("https://kotlinlang.org/api/kotlinx.serialization/")
+    )
+
+    // ktor
+    externalDocumentation(
+        "ktor",
+        URI.create("https://api.ktor.io/")
+    )
+
+    // SLF4J
+    externalDocumentation(
+        "slf4j",
+        URI.create("https://www.slf4j.org/apidocs/"),
+        "element-list"
+    )
+
+    // Spring Framework
+    // TODO 准确的版本号?
+    externalDocumentation(
+        "spring-framework",
+        URI.create("https://docs.spring.io/spring-framework/docs/current/javadoc-api/"),
+        "element-list"
+    )
+
+    // Spring Boot
+    externalDocumentation(
+        "spring-boot",
+        URI.create("https://docs.spring.io/spring-boot/docs/${libs.versions.spring.boot.v3.get()}/api/"),
+        "element-list"
+    )
+}
+
+dokka {
+    moduleName = "Simple Robot"
+
+    dokkaPublications.all {
+        if (isSimbotLocal()) {
+            logger.info("Is 'SIMBOT_LOCAL', offline")
+            offlineMode = true
+        }
+    }
+
+    dokkaSourceSets.configureEach {
+        skipEmptyPackages = true
+        suppressGeneratedFiles = false
+
+        documentedVisibilities(
+            VisibilityModifier.Public,
+            VisibilityModifier.Protected
+        )
+
+        tasks.withType(JavaCompile::class.java).firstOrNull()
+            ?.targetCompatibility?.toInt().also {
+                logger.info("project {} found jdkVersionValue: {}", project, it)
+            }?.also {
+                jdkVersion = it
+            }
+
+        configModuleMdInclude(project)
+
+        perPackageOption {
+            matchingRegex.set(".*internal.*") // will match all .internal packages and sub-packages
+            suppress.set(true)
+        }
+
+        configExternalDocumentations()
+    }
+
+    pluginsConfiguration.html {
+        customAssets.from(
+            rootProject.file(".simbot/dokka-assets/logo-icon.svg"),
+            rootProject.file(".simbot/dokka-assets/logo-icon-light.svg"),
+        )
+
+        customStyleSheets.from(rootProject.file(".simbot/dokka-assets/css/kdoc-style.css"))
+
+        if (!isSimbotLocal()) {
+            templatesDir = rootProject.file(".simbot/dokka-templates")
+        }
+
+        footerMessage =
+            "© 2021-${Year.now().value} <a href='https://github.com/simple-robot'>Simple Robot</a>. " +
+            "All rights reserved."
+
+        separateInheritedMembers = true
+        mergeImplicitExpectActualDeclarations = true
+        homepageLink = P.HOMEPAGE
+    }
+}
+// endregion

build.gradle.kts

@@ -1,5 +1,5 @@
 /*
- *     Copyright (c) 2024. ForteScarlet.
+ *     Copyright (c) 2024-2025. ForteScarlet.
  *
  *     Project    https://github.com/simple-robot/simpler-robot
  *     Email      [email protected]
@@ -40,7 +40,7 @@ dependencies {
     implementation(kotlin("power-assert", kotlinVersion))
     // compileOnly(kotlin("compiler", kotlinVersion))
     // compileOnly(kotlin("compiler-embeddable", kotlinVersion))
-    implementation(libs.bundles.dokka)
+    implementation(libs.dokka.plugin)
 
     // see https://github.com/gradle-nexus/publish-plugin
     implementation(libs.gradleNexusPublishPlugin)