From 4c0cbb4d96bc7a72e2e12b045ee69b4a4a2b5c0c Mon Sep 17 00:00:00 2001 From: Luca Kellermann Date: Thu, 3 Oct 2024 23:09:50 +0200 Subject: [PATCH] Update Dokka to 2.0.0-Beta --- .github/workflows/docs-ci.yml | 4 +- build.gradle.kts | 11 +++++- buildSrc/src/main/kotlin/Documentation.kt | 39 +++++++++++++------ .../src/main/kotlin/kord-module.gradle.kts | 10 ++--- .../kord-multiplatform-module.gradle.kts | 19 +++++---- .../main/kotlin/kord-publishing.gradle.kts | 2 +- core/build.gradle.kts | 6 --- gradle.properties | 9 ++++- gradle/libs.versions.toml | 4 +- ksp-annotations/build.gradle.kts | 4 +- 10 files changed, 66 insertions(+), 42 deletions(-) diff --git a/.github/workflows/docs-ci.yml b/.github/workflows/docs-ci.yml index 7db9fe35624..82f8b56600d 100644 --- a/.github/workflows/docs-ci.yml +++ b/.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: actions@github.com diff --git a/build.gradle.kts b/build.gradle.kts index 0ad64bff26f..52f11df7127 100644 --- a/build.gradle.kts +++ b/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) +} diff --git a/buildSrc/src/main/kotlin/Documentation.kt b/buildSrc/src/main/kotlin/Documentation.kt index 4bf4b7f4922..6b3a1801d7e 100644 --- a/buildSrc/src/main/kotlin/Documentation.kt +++ b/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 runs 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 { diff --git a/buildSrc/src/main/kotlin/kord-module.gradle.kts b/buildSrc/src/main/kotlin/kord-module.gradle.kts index 19322086bd4..37397688ec0 100644 --- a/buildSrc/src/main/kotlin/kord-module.gradle.kts +++ b/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().configureEach { useJUnitPlatform() } - withType().configureEach { - applyKordDokkaOptions() - } - withType().configureEach { options.release = KORD_JVM_TARGET } diff --git a/buildSrc/src/main/kotlin/kord-multiplatform-module.gradle.kts b/buildSrc/src/main/kotlin/kord-multiplatform-module.gradle.kts index 5a28f04dd8c..db9f9064e8f 100644 --- a/buildSrc/src/main/kotlin/kord-multiplatform-module.gradle.kts +++ b/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().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().configureEach { - applyKordDokkaOptions() - dependsOn("kspCommonMainKotlinMetadata") - } } diff --git a/buildSrc/src/main/kotlin/kord-publishing.gradle.kts b/buildSrc/src/main/kotlin/kord-publishing.gradle.kts index 89913975c14..0d3904bd282 100644 --- a/buildSrc/src/main/kotlin/kord-publishing.gradle.kts +++ b/buildSrc/src/main/kotlin/kord-publishing.gradle.kts @@ -10,7 +10,7 @@ fun MavenPublication.registerDokkaJar() = tasks.register("${name}DokkaJar") { archiveClassifier = "javadoc" destinationDirectory = destinationDirectory.get().dir(name) - from(tasks.named("dokkaHtml")) + from(tasks.named("dokkaGeneratePublicationHtml")) } publishing { diff --git a/core/build.gradle.kts b/core/build.gradle.kts index 2d6fbe8572c..6a9478a6873 100644 --- a/core/build.gradle.kts +++ b/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 - } -} diff --git a/gradle.properties b/gradle.properties index 79197226527..80416c1d30f 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,13 +1,18 @@ # 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 +# the Kotlin daemon runs out of memory with the default maximum heap size +kotlin.daemon.jvmargs=-Xmx1g + +# 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 diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index a26d68c9293..7e0b2b54d92 100644 --- a/gradle/libs.versions.toml +++ b/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" } diff --git a/ksp-annotations/build.gradle.kts b/ksp-annotations/build.gradle.kts index ab5cd1ad016..6f3e2f7d6c7 100644 --- a/ksp-annotations/build.gradle.kts +++ b/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().configureEach { +dokka { dokkaSourceSets.configureEach { suppress = true }