Use Dokka Plugin v2

Fixes #1319

Author: steve-the-edwards

.buildscript/deploy_snapshot.sh

@@ -1,13 +1,4 @@
 [
-  {
-    "gradlePath": ":internal-testing-utils",
-    "group": "com.squareup.workflow1",
-    "artifactId": "workflow-internal-testing-utils",
-    "description": "Workflow internal testing utilities",
-    "packaging": "jar",
-    "javaVersion": 8,
-    "publicationName": "maven"
-  },
   {
     "gradlePath": ":trace-encoder",
     "group": "com.squareup.workflow1",

artifacts.json

@@ -37,6 +37,10 @@ gradlePlugin {
       id = "dependency-guard"
       implementationClass = "com.squareup.workflow1.buildsrc.DependencyGuardConventionPlugin"
     }
+    create("dokka") {
+      id = "dokka"
+      implementationClass = "com.squareup.workflow1.buildsrc.DokkaConfigPlugin"
+    }
     create("kotlin-android") {
       id = "kotlin-android"
       implementationClass = "com.squareup.workflow1.buildsrc.KotlinAndroidConventionPlugin"

build-logic/build.gradle.kts

@@ -0,0 +1,45 @@
+package com.squareup.workflow1.buildsrc
+
+import org.gradle.api.Plugin
+import org.gradle.api.Project
+import org.jetbrains.dokka.gradle.DokkaExtension
+
+class DokkaConfigPlugin : Plugin<Project> {
+  override fun apply(target: Project) {
+    target.plugins.apply("org.jetbrains.dokka")
+
+    target.extensions.configure(DokkaExtension::class.java) { dokka ->
+      dokka.dokkaSourceSets.configureEach { sourceSet ->
+        sourceSet.reportUndocumented.set(false)
+        sourceSet.skipDeprecated.set(true)
+
+        val sourceSetName = sourceSet.name
+
+        if (target.file("src/$sourceSetName").exists()) {
+
+          val readmeFile = target.file("${target.projectDir}/README.md")
+          // If the module has a README, add it to the module's index
+          if (readmeFile.exists()) {
+            sourceSet.includes.from(readmeFile)
+          }
+
+          sourceSet.sourceLink {
+            it.localDirectory.set(target.file("src/$sourceSetName"))
+
+            val modulePath = target.projectDir.relativeTo(target.rootDir).path
+
+            // URL showing where the source code can be accessed through the web browser
+            it.remoteUrl("https://github.com/square/workflow-kotlin/blob/main/$modulePath/src/$sourceSetName")
+            // Suffix which is used to append the line number to the URL. Use #L for GitHub
+            it.remoteLineSuffix.set("#L")
+          }
+        }
+        sourceSet.perPackageOption {
+          // Will match all .internal packages and sub-packages, regardless of module.
+          it.matchingRegex.set(""".*\.internal.*""")
+          it.suppress.set(true)
+        }
+      }
+    }
+  }
+}

build-logic/src/main/java/com/squareup/workflow1/buildsrc/DokkaConfigPlugin.kt

@@ -1,5 +1,7 @@
 package com.squareup.workflow1.buildsrc
 
+import com.rickbusarow.kgx.libsCatalog
+import com.rickbusarow.kgx.pluginId
 import com.vanniktech.maven.publish.AndroidSingleVariantLibrary
 import com.vanniktech.maven.publish.JavadocJar
 import com.vanniktech.maven.publish.KotlinJvm
@@ -14,7 +16,8 @@ import org.gradle.api.publish.maven.tasks.PublishToMavenRepository
 
 class PublishingConventionPlugin : Plugin<Project> {
   override fun apply(target: Project) {
-    target.plugins.apply("org.jetbrains.dokka")
+
+    target.plugins.apply("dokka")
     target.plugins.apply("com.vanniktech.maven.publish.base")
     // track all runtime classpath dependencies for anything we ship
     target.plugins.apply("dependency-guard")
@@ -64,15 +67,15 @@ class PublishingConventionPlugin : Plugin<Project> {
       target.pluginManager.withPlugin("org.jetbrains.kotlin.jvm") {
         basePluginExtension.configure(
           KotlinJvm(
-            javadocJar = JavadocJar.Dokka(taskName = "dokkaGfm"),
+            javadocJar = JavadocJar.Dokka(taskName = "dokkaGeneratePublicationHtml"),
             sourcesJar = true
           )
         )
         target.setPublicationProperties(pomDescription, artifactId)
       }
       target.pluginManager.withPlugin("org.jetbrains.kotlin.multiplatform") {
         basePluginExtension.configure(
-          KotlinMultiplatform(javadocJar = JavadocJar.Dokka(taskName = "dokkaGfm"))
+          KotlinMultiplatform(javadocJar = JavadocJar.Dokka(taskName = "dokkaGeneratePublicationHtml"))
         )
         // don't set the artifactId for KMP, because this is handled by the KMP plugin itself
         target.setPublicationProperties(pomDescription, artifactIdOrNull = null)

build-logic/src/main/java/com/squareup/workflow1/buildsrc/PublishingConventionPlugin.kt

@@ -1,7 +1,5 @@
 import com.squareup.workflow1.buildsrc.shardConnectedCheckTasks
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat.FULL
-import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
-import java.net.URL
 
 buildscript {
   dependencies {
@@ -27,6 +25,7 @@ plugins {
   base
   id("artifacts-check")
   id("dependency-guard")
+  alias(libs.plugins.dokka)
   alias(libs.plugins.ktlint)
   alias(libs.plugins.compose.compiler) apply false
 }
@@ -35,63 +34,29 @@ shardConnectedCheckTasks(project)
 
 apply(from = rootProject.file(".buildscript/binary-validation.gradle"))
 
-// This plugin needs to be applied to the root projects for the dokkaGfmCollector task we use to
-// generate the documentation site.
-apply(plugin = "org.jetbrains.dokka")
-
-// Configuration that applies to all dokka tasks, both those used for generating javadoc artifacts
-// and the documentation site.
-subprojects {
-  tasks.withType<AbstractDokkaLeafTask> {
-
-    // This is the displayed name for the module, like in the Html sidebar.
-    //   artifact id: workflow-internal-testing-utils
-    //          path: internal-testing-utils
-    moduleName.set(
-      provider {
-        findProperty("POM_ARTIFACT_ID") as? String
-          ?: project.path.removePrefix(":")
-      }
-    )
-
-    dokkaSourceSets.configureEach {
-
-      val dokkaSourceSet = this
-
-      reportUndocumented.set(false)
-      skipDeprecated.set(true)
-
-      if (file("src/${dokkaSourceSet.name}").exists()) {
-
-        val readmeFile = file("$projectDir/README.md")
-        // If the module has a README, add it to the module's index
-        if (readmeFile.exists()) {
-          includes.from(readmeFile)
-        }
-
-        sourceLink {
-          localDirectory.set(file("src/${dokkaSourceSet.name}"))
-
-          val modulePath = projectDir.relativeTo(rootDir).path
+dependencies {
+  dokka(project(":workflow-core"))
+  dokka(project(":workflow-runtime"))
+  dokka(project(":workflow-runtime-android"))
+  dokka(project(":workflow-rx2"))
+  dokka(project(":workflow-testing"))
+  dokka(project(":workflow-ui:compose"))
+  dokka(project(":workflow-ui:compose-tooling"))
+  dokka(project(":workflow-ui:core-android"))
+  dokka(project(":workflow-ui:core-common"))
+  dokka(project(":workflow-ui:radiography"))
+}
 
-          // URL showing where the source code can be accessed through the web browser
-          remoteUrl.set(
-            @Suppress("ktlint:standard:max-line-length")
-            URL(
-              "https://github.com/square/workflow-kotlin/blob/main/$modulePath/src/${dokkaSourceSet.name}"
-            )
-          )
-          // Suffix which is used to append the line number to the URL. Use #L for GitHub
-          remoteLineSuffix.set("#L")
-        }
-      }
-      perPackageOption {
-        // Will match all .internal packages and sub-packages, regardless of module.
-        matchingRegex.set(""".*\.internal.*""")
-        suppress.set(true)
-      }
+dokka {
+  // This is the displayed name for the module, like in the Html sidebar.
+  //   artifact id: workflow-internal-testing-utils
+  //          path: internal-testing-utils
+  moduleName.set(
+    provider {
+      findProperty("POM_ARTIFACT_ID") as? String
+        ?: project.path.removePrefix(":")
     }
-  }
+  )
 }
 
 // Publish tasks use the output of Sign tasks, but don't actually declare a dependency upon it,
@@ -118,11 +83,11 @@ subprojects {
 tasks.register<Copy>("siteDokka") {
   description = "Generate dokka Html for the documentation site."
   group = "documentation"
-  dependsOn(":dokkaHtmlMultiModule")
+  dependsOn(":dokkaGenerate")
 
   // Copy the files instead of configuring a different output directory on the dokka task itself
   // since the default output directories disambiguate between different types of outputs, and our
   // custom directory doesn't.
-  from(layout.buildDirectory.file("dokka/htmlMultiModule/workflow"))
+  from(layout.buildDirectory.file("dokka/html"))
   into(layout.buildDirectory.file("dokka/workflow"))
 }

build.gradle.kts

@@ -143,6 +143,7 @@ org.glassfish.jaxb:txw2:2.3.2
 org.jdom:jdom2:2.0.6
 org.jetbrains.dokka:dokka-core:2.0.0
 org.jetbrains.dokka:dokka-gradle-plugin:2.0.0
+org.jetbrains.dokka:org.jetbrains.dokka.gradle.plugin:2.0.0
 org.jetbrains.intellij.deps:trove4j:1.0.20200330
 org.jetbrains.kotlin.plugin.compose:org.jetbrains.kotlin.plugin.compose.gradle.plugin:2.0.21
 org.jetbrains.kotlin:compose-compiler-gradle-plugin:2.0.21

dependencies/classpath.txt

@@ -26,4 +26,7 @@ POM_DEVELOPER_NAME=Square, Inc.
 POM_DEVELOPER_URL=https://github.com/square/
 SONATYPE_STAGING_PROFILE=com.squareup
 
+org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
+org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
+
 kotlin.languageVersion=1.9

gradle.properties

@@ -1,6 +1,5 @@
 plugins {
   id("kotlin-jvm")
-  id("published")
 }
 
 dependencies {

internal-testing-utils/build.gradle.kts

@@ -1,4 +1,5 @@
 import com.squareup.workflow1.buildsrc.iosWithSimulatorArm64
+import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 
 plugins {
   id("kotlin-multiplatform")
@@ -20,6 +21,7 @@ kotlin {
 
   // Needed for expect class Lock, which is not public API, so this doesn't add any binary compat
   // risk.
+  @OptIn(ExperimentalKotlinGradlePluginApi::class)
   compilerOptions.freeCompilerArgs.add("-Xexpect-actual-classes")
 }