From fc3e3c3b2bfb804d08935136f51a93dd8608c92f Mon Sep 17 00:00:00 2001 From: Stephen Edwards Date: Thu, 24 Jul 2025 15:24:19 -0400 Subject: [PATCH] Use Dokka Plugin v2 Fixes #1319 --- .buildscript/deploy_snapshot.sh | 26 ------ artifacts.json | 9 -- build-logic/build.gradle.kts | 4 + .../workflow1/buildsrc/DokkaConfigPlugin.kt | 45 ++++++++++ .../buildsrc/PublishingConventionPlugin.kt | 9 +- build.gradle.kts | 83 ++++++------------- dependencies/classpath.txt | 1 + gradle.properties | 3 + internal-testing-utils/build.gradle.kts | 1 - workflow-runtime/build.gradle.kts | 2 + .../internal-testing-android/build.gradle.kts | 1 - .../internal-testing-compose/build.gradle.kts | 1 - 12 files changed, 85 insertions(+), 100 deletions(-) delete mode 100755 .buildscript/deploy_snapshot.sh create mode 100644 build-logic/src/main/java/com/squareup/workflow1/buildsrc/DokkaConfigPlugin.kt diff --git a/.buildscript/deploy_snapshot.sh b/.buildscript/deploy_snapshot.sh deleted file mode 100755 index 1b542870f8..0000000000 --- a/.buildscript/deploy_snapshot.sh +++ /dev/null @@ -1,26 +0,0 @@ -#!/bin/bash -# -# Deploy a jar, source jar, and javadoc jar to Sonatype's snapshot repo. -# -# Adapted from https://coderwall.com/p/9b_lfq and -# https://benlimmer.com/2013/12/26/automatically-publish-javadoc-to-gh-pages-with-travis-ci/ - -SLUG="square/workflow" -JDK="oraclejdk8" -BRANCH="main" - -set -e - -if [ "$TRAVIS_REPO_SLUG" != "$SLUG" ]; then - echo "Skipping snapshot deployment: wrong repository. Expected '$SLUG' but was '$TRAVIS_REPO_SLUG'." -elif [ "$TRAVIS_JDK_VERSION" != "$JDK" ]; then - echo "Skipping snapshot deployment: wrong JDK. Expected '$JDK' but was '$TRAVIS_JDK_VERSION'." -elif [ "$TRAVIS_PULL_REQUEST" != "false" ]; then - echo "Skipping snapshot deployment: was pull request." -elif [ "$TRAVIS_BRANCH" != "$BRANCH" ]; then - echo "Skipping snapshot deployment: wrong branch. Expected '$BRANCH' but was '$TRAVIS_BRANCH'." -else - echo "Deploying snapshot..." - ./gradlew clean uploadArchives - echo "Snapshot deployed!" -fi diff --git a/artifacts.json b/artifacts.json index 21b078b895..438a6826a5 100644 --- a/artifacts.json +++ b/artifacts.json @@ -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", diff --git a/build-logic/build.gradle.kts b/build-logic/build.gradle.kts index e9b187b701..132fb57136 100644 --- a/build-logic/build.gradle.kts +++ b/build-logic/build.gradle.kts @@ -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" diff --git a/build-logic/src/main/java/com/squareup/workflow1/buildsrc/DokkaConfigPlugin.kt b/build-logic/src/main/java/com/squareup/workflow1/buildsrc/DokkaConfigPlugin.kt new file mode 100644 index 0000000000..616637e1be --- /dev/null +++ b/build-logic/src/main/java/com/squareup/workflow1/buildsrc/DokkaConfigPlugin.kt @@ -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 { + 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) + } + } + } + } +} diff --git a/build-logic/src/main/java/com/squareup/workflow1/buildsrc/PublishingConventionPlugin.kt b/build-logic/src/main/java/com/squareup/workflow1/buildsrc/PublishingConventionPlugin.kt index 60d4637061..9e952cea28 100644 --- a/build-logic/src/main/java/com/squareup/workflow1/buildsrc/PublishingConventionPlugin.kt +++ b/build-logic/src/main/java/com/squareup/workflow1/buildsrc/PublishingConventionPlugin.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 { 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,7 +67,7 @@ class PublishingConventionPlugin : Plugin { target.pluginManager.withPlugin("org.jetbrains.kotlin.jvm") { basePluginExtension.configure( KotlinJvm( - javadocJar = JavadocJar.Dokka(taskName = "dokkaGfm"), + javadocJar = JavadocJar.Dokka(taskName = "dokkaGeneratePublicationHtml"), sourcesJar = true ) ) @@ -72,7 +75,7 @@ class PublishingConventionPlugin : Plugin { } 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) diff --git a/build.gradle.kts b/build.gradle.kts index 63ecf3ea71..31d47a210a 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -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 { - - // 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("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")) } diff --git a/dependencies/classpath.txt b/dependencies/classpath.txt index 258a9cbe8b..e3a47bd6af 100644 --- a/dependencies/classpath.txt +++ b/dependencies/classpath.txt @@ -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 diff --git a/gradle.properties b/gradle.properties index b64c809464..d3245c2b4f 100644 --- a/gradle.properties +++ b/gradle.properties @@ -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 diff --git a/internal-testing-utils/build.gradle.kts b/internal-testing-utils/build.gradle.kts index 04af0d7434..8d67eb9d60 100644 --- a/internal-testing-utils/build.gradle.kts +++ b/internal-testing-utils/build.gradle.kts @@ -1,6 +1,5 @@ plugins { id("kotlin-jvm") - id("published") } dependencies { diff --git a/workflow-runtime/build.gradle.kts b/workflow-runtime/build.gradle.kts index 10993c7abf..f9140c464b 100644 --- a/workflow-runtime/build.gradle.kts +++ b/workflow-runtime/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") } diff --git a/workflow-ui/internal-testing-android/build.gradle.kts b/workflow-ui/internal-testing-android/build.gradle.kts index c61f8dfe7a..730b00dc2e 100644 --- a/workflow-ui/internal-testing-android/build.gradle.kts +++ b/workflow-ui/internal-testing-android/build.gradle.kts @@ -2,7 +2,6 @@ plugins { id("com.android.library") id("kotlin-android") id("android-defaults") - id("org.jetbrains.dokka") } // This module is not published, since it's just internal testing utilities. diff --git a/workflow-ui/internal-testing-compose/build.gradle.kts b/workflow-ui/internal-testing-compose/build.gradle.kts index a6fc9a7522..a2303a1b11 100644 --- a/workflow-ui/internal-testing-compose/build.gradle.kts +++ b/workflow-ui/internal-testing-compose/build.gradle.kts @@ -2,7 +2,6 @@ plugins { id("com.android.library") id("kotlin-android") id("android-defaults") - id("org.jetbrains.dokka") } // This module is not published, since it's just internal testing utilities.