Update Dokka to 2.0.0-Beta

.github/workflows/docs-ci.yml

@@ -27,11 +27,11 @@ jobs:
       - name: Set up Gradle
         uses: gradle/actions/setup-gradle@v4
       - name: Build docs with Gradle
-        run: ./gradlew --stacktrace --info dokkaHtmlMultiModule
+        run: ./gradlew --stacktrace --info :dokkaGeneratePublicationHtml
       - name: Deploy docs to GitHub Pages
         uses: JamesIves/github-pages-deploy-action@v4
         with:
-          folder: build/dokka/htmlMultiModule
+          folder: build/dokka/html
           branch: gh-pages
           git-config-name: GitHub Actions
           git-config-email: [email protected]

build.gradle.kts

@@ -1,5 +1,5 @@
 plugins {
-    org.jetbrains.dokka // for dokkaHtmlMultiModule task
+    org.jetbrains.dokka // for dokkaGeneratePublicationHtml task
 }
 
 repositories {
@@ -8,3 +8,12 @@ repositories {
 
 group = Library.group
 version = libraryVersion
+
+dependencies {
+    dokka(projects.common)
+    dokka(projects.core)
+    dokka(projects.coreVoice)
+    dokka(projects.gateway)
+    dokka(projects.rest)
+    dokka(projects.voice)
+}

buildSrc/src/main/kotlin/Documentation.kt

@@ -1,12 +1,19 @@
+import org.gradle.api.Project
 import org.gradle.kotlin.dsl.assign
-import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
-import java.net.URI
+import org.gradle.kotlin.dsl.invoke
+import org.jetbrains.dokka.gradle.DokkaExtension
+import org.jetbrains.dokka.gradle.workers.ProcessIsolation
 
-fun AbstractDokkaLeafTask.applyKordDokkaOptions() {
+internal fun DokkaExtension.applyKordDokkaOptions(project: Project) {
+
+    // Dokka will run out of memory with the default maxHeapSize when ProcessIsolation is used
+    (dokkaGeneratorIsolation.get() as? ProcessIsolation)?.maxHeapSize = "1g"
 
     moduleName = "kord-${project.name}"
 
-    failOnWarning = true
+    dokkaPublications.configureEach {
+        failOnWarning = true
+    }
 
     dokkaSourceSets.configureEach {
 
@@ -16,17 +23,25 @@ fun AbstractDokkaLeafTask.applyKordDokkaOptions() {
 
         sourceLink {
             localDirectory = project.projectDir
-            remoteUrl = URI("https://github.com/kordlib/kord/blob/${project.commitHash}/${project.name}").toURL()
+            remoteUrl("https://github.com/kordlib/kord/blob/${project.commitHash}/${project.name}")
             remoteLineSuffix = "#L"
         }
 
-        externalDocumentationLink("https://kotlinlang.org/api/kotlinx.coroutines/")
-        externalDocumentationLink("https://kotlinlang.org/api/kotlinx.serialization/")
-        externalDocumentationLink(
-            url = "https://kotlinlang.org/api/kotlinx-datetime/",
-            packageListUrl = "https://kotlinlang.org/api/kotlinx-datetime/kotlinx-datetime/package-list",
-        )
-        externalDocumentationLink("https://api.ktor.io/")
+        externalDocumentationLinks {
+            register("kotlinx.coroutines") {
+                url("https://kotlinlang.org/api/kotlinx.coroutines/")
+            }
+            register("kotlinx.serialization") {
+                url("https://kotlinlang.org/api/kotlinx.serialization/")
+            }
+            register("kotlinx-datetime") {
+                url("https://kotlinlang.org/api/kotlinx-datetime/")
+                packageListUrl("https://kotlinlang.org/api/kotlinx-datetime/kotlinx-datetime/package-list")
+            }
+            register("Ktor") {
+                url("https://api.ktor.io/")
+            }
+        }
 
         // don't list `TweetNaclFast` in docs
         perPackageOption {

buildSrc/src/main/kotlin/kord-module.gradle.kts

@@ -1,5 +1,3 @@
-import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
-
 plugins {
     org.jetbrains.kotlin.jvm
     org.jetbrains.kotlin.plugin.serialization
@@ -34,15 +32,15 @@ kotlin {
     }
 }
 
+dokka {
+    applyKordDokkaOptions(project)
+}
+
 tasks {
     withType<Test>().configureEach {
         useJUnitPlatform()
     }
 
-    withType<AbstractDokkaLeafTask>().configureEach {
-        applyKordDokkaOptions()
-    }
-
     withType<JavaCompile>().configureEach {
         options.release = KORD_JVM_TARGET
     }

buildSrc/src/main/kotlin/kord-multiplatform-module.gradle.kts

@@ -1,4 +1,3 @@
-import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
 import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 import org.jetbrains.kotlin.gradle.targets.js.testing.KotlinJsTest
 
@@ -71,6 +70,10 @@ kotlin {
     }
 }
 
+dokka {
+    applyKordDokkaOptions(project)
+}
+
 tasks {
     withType<Test>().configureEach {
         useJUnitPlatform()
@@ -80,7 +83,14 @@ tasks {
         environment("PROJECT_ROOT", rootProject.projectDir.absolutePath)
     }
 
-    for (task in listOf("compileKotlinJvm", "compileKotlinJs", "jvmSourcesJar", "jsSourcesJar")) {
+    for (task in listOf(
+        "compileKotlinJvm",
+        "compileKotlinJs",
+        "jvmSourcesJar",
+        "jsSourcesJar",
+        "dokkaGenerateModuleHtml",
+        "dokkaGeneratePublicationHtml",
+    )) {
         named(task) {
             dependsOn("kspCommonMainKotlinMetadata")
         }
@@ -91,9 +101,4 @@ tasks {
             dependsOn("kspCommonMainKotlinMetadata")
         }
     }
-
-    withType<AbstractDokkaLeafTask>().configureEach {
-        applyKordDokkaOptions()
-        dependsOn("kspCommonMainKotlinMetadata")
-    }
 }

buildSrc/src/main/kotlin/kord-publishing.gradle.kts

@@ -10,7 +10,7 @@ fun MavenPublication.registerDokkaJar() =
     tasks.register<Jar>("${name}DokkaJar") {
         archiveClassifier = "javadoc"
         destinationDirectory = destinationDirectory.get().dir(name)
-        from(tasks.named("dokkaHtml"))
+        from(tasks.named("dokkaGeneratePublicationHtml"))
     }
 
 publishing {

core/build.gradle.kts

@@ -37,9 +37,3 @@ apiValidation {
     // https://github.com/Kotlin/binary-compatibility-validator/issues/88
     ignoredProjects += "live-tests"
 }
-
-tasks {
-    dokkaHtmlMultiModule {
-        enabled = false
-    }
-}

gradle.properties

@@ -1,13 +1,15 @@
 # the version that is planned to be released next, snapshot versions for the 'main' branch are based on this
 nextPlannedVersion=0.15.0
 
-#dokka will run out of memory with the default meta space
-org.gradle.jvmargs=-XX:MaxMetaspaceSize=1024m
 org.gradle.parallel=true
 org.gradle.warning.mode=all
 org.gradle.kotlin.dsl.allWarningsAsErrors=true
 kotlin.code.style=official
 
+# https://kotlinlang.org/docs/dokka-migration.html#set-the-opt-in-flag
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
+org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
+
 # https://github.com/Kotlin/kotlinx-atomicfu/issues/448
 # https://youtrack.jetbrains.com/issue/KT-64109#focus=Comments-27-10064206.0-0
 kotlin.suppressGradlePluginWarnings=IncorrectCompileOnlyDependencyWarning

gradle/libs.versions.toml

@@ -28,7 +28,7 @@ mockk = "1.13.12" # https://github.com/mockk/mockk
 kbson = "0.4.0" # https://github.com/mongodb/kbson
 
 # plugins
-dokka = "1.9.20" # https://github.com/Kotlin/dokka
+dokka = "2.0.0-Beta" # https://github.com/Kotlin/dokka
 kotlinx-atomicfu = "0.25.0" # https://github.com/Kotlin/kotlinx-atomicfu
 binary-compatibility-validator = "0.16.3" # https://github.com/Kotlin/binary-compatibility-validator
 buildconfig = "5.4.0" # https://github.com/gmazzo/gradle-buildconfig-plugin
@@ -85,7 +85,7 @@ slf4j-simple = { module = "org.slf4j:slf4j-simple", version.ref = "slf4j" }
 kbson = { module = "org.mongodb.kbson:kbson", version.ref = "kbson" }
 
 # actually plugins, not libraries, but used is 'buildSrc/build.gradle.kts' as implementation dependencies:
-# https://docs.gradle.org/current/userguide/custom_plugins.html#applying_external_plugins_in_precompiled_script_plugins
+# https://docs.gradle.org/current/userguide/implementing_gradle_plugins_precompiled.html#sec:applying_external_plugins
 kotlin-jvm-plugin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "kotlin" }
 kotlin-serialization-plugin = { module = "org.jetbrains.kotlin:kotlin-serialization", version.ref = "kotlin" }
 dokka-plugin = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "dokka" }

ksp-annotations/build.gradle.kts

@@ -1,5 +1,3 @@
-import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
-
 plugins {
     `kord-internal-multiplatform-module`
 
@@ -10,7 +8,7 @@ plugins {
     `kord-publishing`
 }
 
-tasks.withType<AbstractDokkaLeafTask>().configureEach {
+dokka {
     dokkaSourceSets.configureEach {
         suppress = true
     }