Switch to Dokka v2 (#9263)

yschimke · web-flow · commit 7f3a2208779a · 2026-01-25T12:37:13.000Z
* Update Dokka to v2

update configuration to use experimental V2 plugin mode and adjust documentation generation scripts.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -722,6 +722,9 @@ jobs:
       - name: Setup Gradle
         uses: gradle/actions/setup-gradle@v5
 
+      - name: Test module-tests
+        run: ./gradlew module-tests:test -PokhttpModuleTests=true
+
       - name: Run with Jlink
-        run: ./gradlew module-tests:imageRun
+        run: ./gradlew module-tests:imageRun -PokhttpModuleTests=true
 
diff --git a/.vscode/settings.json b/.vscode/settings.json
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -5,7 +5,7 @@ import com.vanniktech.maven.publish.MavenPublishBaseExtension
 import java.net.URI
 import kotlinx.validation.ApiValidationExtension
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat
-import org.jetbrains.dokka.gradle.DokkaTaskPartial
+import org.jetbrains.dokka.gradle.DokkaExtension
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 import org.jetbrains.kotlin.gradle.targets.jvm.tasks.KotlinJvmTest
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
@@ -38,7 +38,14 @@ buildscript {
   }
 }
 
-apply(plugin = "org.jetbrains.dokka")
+val okhttpDokka: String by project
+val dokkaBuild = okhttpDokka.toBoolean()
+val platform = System.getProperty("okhttp.platform", "jdk9")
+val testJavaVersion = System.getProperty("test.java.version", "21").toInt()
+
+if (dokkaBuild) {
+  apply(plugin = "org.jetbrains.dokka")
+}
 apply(plugin = "com.diffplug.spotless")
 
 configure<SpotlessExtension> {
@@ -78,8 +85,7 @@ allprojects {
   }
 }
 
-val platform = System.getProperty("okhttp.platform", "jdk9")
-val testJavaVersion = System.getProperty("test.java.version", "21").toInt()
+
 
 /** Configure building for Java+Kotlin projects. */
 subprojects {
@@ -197,8 +203,7 @@ subprojects {
     }
   }
 
-  val platform = System.getProperty("okhttp.platform", "jdk9")
-  val testJavaVersion = System.getProperty("test.java.version", "21").toInt()
+
 
   if (project.name != "okhttp") {
     val testRuntimeOnly: Configuration by configurations.getting
@@ -304,26 +309,39 @@ subprojects {
 
 /** Configure publishing and signing for published Java and JavaPlatform subprojects. */
 subprojects {
-  tasks.withType<DokkaTaskPartial>().configureEach {
-    dokkaSourceSets.configureEach {
-      reportUndocumented.set(false)
-      skipDeprecated.set(true)
-      jdkVersion.set(8)
-      perPackageOption {
-        matchingRegex.set(".*\\.internal.*")
-        suppress.set(true)
-      }
-      if (project.file("Module.md").exists()) {
-        includes.from(project.file("Module.md"))
-      }
-      externalDocumentationLink {
-        url.set(URI.create("https://square.github.io/okio/3.x/okio/").toURL())
-        packageListUrl.set(URI.create("https://square.github.io/okio/3.x/okio/okio/package-list").toURL())
+  plugins.withId("com.vanniktech.maven.publish.base") {
+    if (dokkaBuild) {
+      apply(plugin = "org.jetbrains.dokka")
+
+      extensions.configure<DokkaExtension> {
+        dokkaSourceSets.configureEach {
+          reportUndocumented.set(false)
+          skipDeprecated.set(true)
+          jdkVersion.set(21)
+          perPackageOption {
+            matchingRegex.set(".*\\.internal.*")
+            suppress.set(true)
+          }
+          if (project.file("Module.md").exists()) {
+            includes.from(project.file("Module.md"))
+          }
+          externalDocumentationLinks.register("okio") {
+            url.set(URI.create("https://square.github.io/okio/3.x/okio/"))
+            packageListUrl.set(URI.create("https://square.github.io/okio/3.x/okio/okio/package-list"))
+          }
+          
+          externalDocumentationLinks.named("jdk") {
+             url.set(URI.create("https://docs.oracle.com/en/java/javase/21/docs/api/"))
+             packageListUrl.set(URI.create("https://docs.oracle.com/en/java/javase/21/docs/api/element-list"))
+          }
+          externalDocumentationLinks.register("androidRef") {
+             url.set(URI.create("https://developer.android.com/reference/"))
+             packageListUrl.set(URI.create("https://developer.android.com/reference/package-list"))
+          }
+        }
       }
     }
-  }
 
-  plugins.withId("com.vanniktech.maven.publish.base") {
     configure<MavenPublishBaseExtension> {
       publishToMavenCentral(automaticRelease = true)
       signAllPublications()
@@ -376,3 +394,22 @@ plugins.withId("org.jetbrains.kotlin.jvm") {
 tasks.wrapper {
   distributionType = Wrapper.DistributionType.ALL
 }
+
+if (dokkaBuild) {
+  dependencies {
+    add("dokka", project(":okhttp"))
+    add("dokka", project(":okhttp-brotli"))
+    add("dokka", project(":okhttp-coroutines"))
+    add("dokka", project(":okhttp-dnsoverhttps"))
+    add("dokka", project(":okhttp-java-net-cookiejar"))
+    add("dokka", project(":logging-interceptor"))
+    add("dokka", project(":okhttp-sse"))
+    add("dokka", project(":okhttp-tls"))
+    add("dokka", project(":okhttp-urlconnection"))
+    add("dokka", project(":okhttp-zstd"))
+    add("dokka", project(":mockwebserver"))
+    add("dokka", project(":mockwebserver3"))
+    add("dokka", project(":mockwebserver3-junit4"))
+    add("dokka", project(":mockwebserver3-junit5"))
+  }
+}
diff --git a/gradle.properties b/gradle.properties
@@ -8,5 +8,8 @@ androidBuild=false
 graalBuild=false
 loomBuild=false
 containerTests=false
+okhttpModuleTests=false
+okhttpDokka=false
 
 org.gradle.jvmargs='-Dfile.encoding=UTF-8'
+
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
@@ -53,7 +53,7 @@ gradlePlugin-animalsniffer = "ru.vyarus:gradle-animalsniffer-plugin:2.0.1"
 gradlePlugin-binaryCompatibilityValidator = "org.jetbrains.kotlinx.binary-compatibility-validator:org.jetbrains.kotlinx.binary-compatibility-validator.gradle.plugin:0.18.1"
 gradlePlugin-bnd = { module = "biz.aQute.bnd:biz.aQute.bnd.gradle", version.ref = "biz-aQute-bnd" }
 gradlePlugin-burst = { module = "app.cash.burst:burst-gradle-plugin", version = "2.10.2" }
-gradlePlugin-dokka = "org.jetbrains.dokka:dokka-gradle-plugin:2.0.0"
+gradlePlugin-dokka = "org.jetbrains.dokka:dokka-gradle-plugin:2.1.0"
 gradlePlugin-errorprone = "net.ltgt.gradle:gradle-errorprone-plugin:4.3.0"
 gradlePlugin-graalvmBuildTools = "org.graalvm.buildtools.native:org.graalvm.buildtools.native.gradle.plugin:0.11.3"
 gradlePlugin-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "org-jetbrains-kotlin" }
diff --git a/mockwebserver-deprecated/build.gradle.kts b/mockwebserver-deprecated/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/mockwebserver-junit4/build.gradle.kts b/mockwebserver-junit4/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/mockwebserver-junit5/build.gradle.kts b/mockwebserver-junit5/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/mockwebserver/build.gradle.kts b/mockwebserver/build.gradle.kts
@@ -1,10 +1,8 @@
 import com.vanniktech.maven.publish.JavadocJar
 import com.vanniktech.maven.publish.KotlinJvm
-import org.jetbrains.kotlin.gradle.dsl.kotlinExtension
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/module-tests/build.gradle.kts b/module-tests/build.gradle.kts
@@ -8,6 +8,9 @@ plugins {
 dependencies {
   implementation(projects.okhttp)
   implementation(projects.loggingInterceptor)
+  
+  // Force version 26.0.2-1 which is a proper JPMS module, unlike transitive 13.0
+  implementation("org.jetbrains:annotations:26.0.2-1")
 
   testImplementation(projects.okhttp)
   testImplementation(projects.loggingInterceptor)
@@ -33,9 +36,6 @@ jlinkApplication {
 }
 
 extraJavaModuleInfo {
-  module("org.jetbrains:annotations", "org.jetbrains.annotations") {
-    exportAllPackages()
-  }
   module("com.squareup.okio:okio-jvm", "okio") {
     exportAllPackages()
     requires("kotlin.stdlib")
@@ -46,6 +46,12 @@ extraJavaModuleInfo {
   }
 }
 
+// Exclude dokka from all configurations
+// to attempt to avoid https://github.com/gradlex-org/extra-java-module-info/issues/221
+configurations.all {
+  exclude(group = "org.jetbrains.dokka")
+}
+
 val testJavaVersion = System.getProperty("test.java.version", "21").toInt()
 
 tasks.withType<Test> {
diff --git a/okcurl/build.gradle.kts b/okcurl/build.gradle.kts
@@ -5,7 +5,6 @@ import ru.vyarus.gradle.plugin.animalsniffer.AnimalSnifferExtension
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("com.gradleup.shadow")
 }
diff --git a/okhttp-brotli/build.gradle.kts b/okhttp-brotli/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/okhttp-coroutines/build.gradle.kts b/okhttp-coroutines/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/okhttp-dnsoverhttps/build.gradle.kts b/okhttp-dnsoverhttps/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/okhttp-java-net-cookiejar/build.gradle.kts b/okhttp-java-net-cookiejar/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/okhttp-logging-interceptor/build.gradle.kts b/okhttp-logging-interceptor/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/okhttp-sse/build.gradle.kts b/okhttp-sse/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/okhttp-tls/build.gradle.kts b/okhttp-tls/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
   id("ru.vyarus.animalsniffer")
diff --git a/okhttp-urlconnection/build.gradle.kts b/okhttp-urlconnection/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/okhttp-zstd/build.gradle.kts b/okhttp-zstd/build.gradle.kts
@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm
 
 plugins {
   kotlin("jvm")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
 }
diff --git a/okhttp/build.gradle.kts b/okhttp/build.gradle.kts
@@ -3,16 +3,15 @@
 import com.vanniktech.maven.publish.JavadocJar
 import com.vanniktech.maven.publish.KotlinMultiplatform
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 import org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile
 import ru.vyarus.gradle.plugin.animalsniffer.AnimalSniffer
 import ru.vyarus.gradle.plugin.animalsniffer.AnimalSnifferExtension
-import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
   kotlin("multiplatform")
   id("com.android.library")
   kotlin("plugin.serialization")
-  id("org.jetbrains.dokka")
   id("com.vanniktech.maven.publish.base")
   id("binary-compatibility-validator")
   id("app.cash.burst")
diff --git a/settings.gradle.kts b/settings.gradle.kts
@@ -52,7 +52,10 @@ include(":samples:static-server")
 include(":samples:tlssurvey")
 include(":samples:unixdomainsockets")
 include(":container-tests")
-include(":module-tests")
+val okhttpModuleTests: String by settings
+if (okhttpModuleTests.toBoolean()) {
+  include(":module-tests")
+}
 
 project(":okhttp-logging-interceptor").name = "logging-interceptor"
 
diff --git a/test_docs.sh b/test_docs.sh
@@ -9,12 +9,12 @@
 set -ex
 
 # Test generating the javadoc jars
-./gradlew publishToMavenLocal -DRELEASE_SIGNING_ENABLED=false
+./gradlew publishToMavenLocal -DRELEASE_SIGNING_ENABLED=false -PokhttpDokka=true
 
 # Generate the API docs
-./gradlew dokkaHtmlMultiModule
+./gradlew dokkaGeneratePublicationHtml -PokhttpDokka=true
 
-mv ./build/dokka/htmlMultiModule docs/4.x
+mv ./build/dokka/html docs/4.x
 
 # Copy in special files that GitHub wants in the project root.
 cat README.md | grep -v 'project website' > docs/index.md

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,6 @@ import com.vanniktech.maven.publish.KotlinJvm`
`3`	`3`
`4`	`4`	`plugins {`
`5`	`5`	`kotlin("jvm")`
`6`		`- id("org.jetbrains.dokka")`
`7`	`6`	`id("com.vanniktech.maven.publish.base")`
`8`	`7`	`id("binary-compatibility-validator")`
`9`	`8`	`}`