Update plugin dokka to v2 (#272)

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: Zac Sweers <[email protected]>

CHANGELOG.md

@@ -12,6 +12,7 @@ Changelog
 - Build against Gradle `8.12`.
 - Only report errors in FIR now. Removes the `validateIr` plugin option.
 - No longer support K1.
+- Raise Gradle plugin Kotlin target to `1.9`.
 
 1.11.0
 ------

build.gradle.kts

@@ -1,6 +1,7 @@
 import com.vanniktech.maven.publish.MavenPublishBaseExtension
 import kotlinx.validation.ExperimentalBCVApi
-import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.dokka.gradle.DokkaExtension
+import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 import org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompilerOptions
 import org.jetbrains.kotlin.gradle.dsl.KotlinProjectExtension
@@ -17,7 +18,7 @@ buildscript {
 
 plugins {
   alias(libs.plugins.kotlin.jvm) apply false
-  alias(libs.plugins.dokka) apply false
+  alias(libs.plugins.dokka)
   alias(libs.plugins.ksp) apply false
   alias(libs.plugins.mavenPublish) apply false
   alias(libs.plugins.spotless)
@@ -34,6 +35,13 @@ apiValidation {
   }
 }
 
+dokka {
+  dokkaPublications.html {
+    outputDirectory.set(rootDir.resolve("docs/api/1.x"))
+    includes.from(project.layout.projectDirectory.file("README.md"))
+  }
+}
+
 spotless {
   format("misc") {
     target("*.gradle", "*.md", ".gitignore")
@@ -88,9 +96,23 @@ subprojects {
   }
 
   pluginManager.withPlugin("org.jetbrains.dokka") {
-    tasks.named<DokkaTask>("dokkaHtml") {
-      outputDirectory.set(rootProject.file("docs/0.x"))
-      dokkaSourceSets.configureEach { skipDeprecated.set(true) }
+    configure<DokkaExtension> {
+      basePublicationsDirectory.set(layout.buildDirectory.dir("dokkaDir"))
+      dokkaSourceSets.configureEach {
+        skipDeprecated.set(true)
+        documentedVisibilities.add(VisibilityModifier.Public)
+
+        sourceLink {
+          localDirectory.set(layout.projectDirectory.dir("src"))
+          val relPath = rootProject.projectDir.toPath().relativize(projectDir.toPath())
+          remoteUrl(
+            providers.gradleProperty("POM_SCM_URL").map { scmUrl ->
+              "$scmUrl/tree/main/$relPath/src"
+            }
+          )
+          remoteLineSuffix.set("#L")
+        }
+      }
     }
   }
 
@@ -103,3 +125,5 @@ subprojects {
     }
   }
 }
+
+dependencies { dokka(project(":redacted-compiler-plugin-annotations")) }

gradle.properties

@@ -14,6 +14,10 @@ kotlin.compiler.suppressExperimentalICOptimizationsWarning=true
 kotlin.compiler.keepIncrementalCompilationCachesInMemory=true
 kotlin.compiler.preciseCompilationResultsBackup=true
 
+# Dokka flags
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
+org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
+
 GROUP=dev.zacsweers.redacted
 VERSION_NAME=1.12.0-SNAPSHOT
 POM_DESCRIPTION=A Kotlin compiler plugin that generates redacted toString() implementations.

gradle/libs.versions.toml

@@ -25,7 +25,8 @@ moshi = "1.15.1"
 [plugins]
 kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
 binaryCompatibilityValidator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version = "0.17.0" }
-dokka = { id = "org.jetbrains.dokka", version = "1.9.20" }
+buildConfig = { id = "com.github.gmazzo.buildconfig", version = "5.5.0" }
+dokka = { id = "org.jetbrains.dokka", version = "2.0.0" }
 ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
 mavenPublish = { id = "com.vanniktech.maven.publish", version = "0.30.0" }
 spotless = { id = "com.diffplug.spotless", version = "7.0.0.BETA4" }

publish.sh

@@ -4,12 +4,12 @@ if [[ "$1" = "--local" ]]; then local=true; fi
 
 if ! [[ ${local} ]]; then
   cd redacted-compiler-plugin-gradle || exit
-  ./gradlew publish -x dokkaHtml --no-configuration-cache
+  ./gradlew publish --no-configuration-cache
   cd ..
-  ./gradlew publish -x dokkaHtml --no-configuration-cache
+  ./gradlew publish --no-configuration-cache
 else
   cd redacted-compiler-plugin-gradle || exit
-  ./gradlew publishToMavenLocal -x dokkaHtml
+  ./gradlew publishToMavenLocal
   cd ..
-  ./gradlew publishToMavenLocal -x dokkaHtml
+  ./gradlew publishToMavenLocal
 fi

redacted-compiler-plugin-gradle/build.gradle.kts

@@ -1,5 +1,6 @@
 import com.vanniktech.maven.publish.MavenPublishBaseExtension
-import org.jetbrains.dokka.gradle.DokkaTask
+import org.gradle.kotlin.dsl.configure
+import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
@@ -10,6 +11,7 @@ plugins {
   alias(libs.plugins.dokka)
   alias(libs.plugins.mavenPublish)
   alias(libs.plugins.spotless)
+  alias(libs.plugins.buildConfig)
 }
 
 java { toolchain { languageVersion.set(libs.versions.jdk.map(JavaLanguageVersion::of)) } }
@@ -18,37 +20,25 @@ tasks.withType<JavaCompile>().configureEach {
   options.release.set(libs.versions.jvmTarget.map(String::toInt))
 }
 
-// region Version.kt template for setting the project version in the build
-sourceSets {
-  main { java.srcDir(layout.buildDirectory.dir("generated/sources/version-templates/kotlin/main")) }
-}
-
-val copyVersionTemplatesProvider =
-  tasks.register<Copy>("copyVersionTemplates") {
-    inputs.property("version", project.property("VERSION_NAME"))
-    from(project.layout.projectDirectory.dir("version-templates"))
-    into(project.layout.buildDirectory.dir("generated/sources/version-templates/kotlin/main"))
-    expand(mapOf("projectVersion" to "${project.property("VERSION_NAME")}"))
-    filteringCharset = "UTF-8"
+buildConfig {
+  buildConfigField("String", "VERSION", "\"${project.property("VERSION_NAME")}\"")
+  packageName("dev.zacsweers.redacted.gradle")
+  useKotlinOutput {
+    topLevelConstants = true
+    internalVisibility = true
   }
-
-// endregion
+}
 
 tasks.withType<KotlinCompile>().configureEach {
-  dependsOn(copyVersionTemplatesProvider)
   compilerOptions {
     jvmTarget.set(libs.versions.jvmTarget.map(JvmTarget::fromTarget))
 
     // Lower version for Gradle compat
-    languageVersion.set(KotlinVersion.KOTLIN_1_8)
-    apiVersion.set(KotlinVersion.KOTLIN_1_8)
+    languageVersion.set(KotlinVersion.KOTLIN_1_9)
+    apiVersion.set(KotlinVersion.KOTLIN_1_9)
   }
 }
 
-tasks
-  .matching { it.name == "sourcesJar" || it.name == "dokkaHtml" }
-  .configureEach { dependsOn(copyVersionTemplatesProvider) }
-
 gradlePlugin {
   plugins {
     create("redactedPlugin") {
@@ -58,9 +48,35 @@ gradlePlugin {
   }
 }
 
-tasks.named<DokkaTask>("dokkaHtml") {
-  outputDirectory.set(rootProject.file("../docs/0.x"))
-  dokkaSourceSets.configureEach { skipDeprecated.set(true) }
+dokka {
+  dokkaPublications.html {
+    outputDirectory.set(rootDir.resolve("docs/api/1.x"))
+    includes.from(project.layout.projectDirectory.file("README.md"))
+  }
+  basePublicationsDirectory.set(layout.buildDirectory.dir("dokkaDir"))
+  dokkaSourceSets.configureEach {
+    skipDeprecated.set(true)
+    documentedVisibilities.add(VisibilityModifier.Public)
+
+    externalDocumentationLinks.register("Gradle") {
+      packageListUrl("https://docs.gradle.org/${gradle.gradleVersion}/javadoc/element-list")
+      url("https://docs.gradle.org/${gradle.gradleVersion}/javadoc")
+    }
+
+    // KGP docs
+    externalDocumentationLinks.register("KGP") {
+      url("https://kotlinlang.org/api/kotlin-gradle-plugin/")
+    }
+
+    sourceLink {
+      localDirectory.set(layout.projectDirectory.dir("src"))
+      val relPath = rootProject.projectDir.toPath().relativize(projectDir.toPath())
+      remoteUrl(
+        providers.gradleProperty("POM_SCM_URL").map { scmUrl -> "$scmUrl/tree/main/$relPath/src" }
+      )
+      remoteLineSuffix.set("#L")
+    }
+  }
 }
 
 kotlin { explicitApi() }

redacted-compiler-plugin-gradle/gradle.properties

@@ -5,6 +5,10 @@ POM_PACKAGING=jar
 # Gradle imposes its own
 kotlin.stdlib.default.dependency=false
 
+# Dokka flags
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
+org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
+
 GROUP=dev.zacsweers.redacted
 VERSION_NAME=1.12.0-SNAPSHOT
 POM_DESCRIPTION=A Kotlin compiler plugin that generates redacted toString() implementations.