From 7f3a2208779af439dd5d64e5bc31c1297a6d9673 Mon Sep 17 00:00:00 2001 From: Yuri Schimke Date: Sun, 25 Jan 2026 12:37:13 +0000 Subject: [PATCH] Switch to Dokka v2 (#9263) * Update Dokka to v2 update configuration to use experimental V2 plugin mode and adjust documentation generation scripts. --- .github/workflows/build.yml | 7 +- .vscode/settings.json | 3 - build.gradle.kts | 83 +++++++++++++++------ gradle.properties | 3 + gradle/libs.versions.toml | 2 +- mockwebserver-deprecated/build.gradle.kts | 1 - mockwebserver-junit4/build.gradle.kts | 1 - mockwebserver-junit5/build.gradle.kts | 1 - mockwebserver/build.gradle.kts | 2 - module-tests/build.gradle.kts | 12 ++- okcurl/build.gradle.kts | 1 - okhttp-brotli/build.gradle.kts | 1 - okhttp-coroutines/build.gradle.kts | 1 - okhttp-dnsoverhttps/build.gradle.kts | 1 - okhttp-java-net-cookiejar/build.gradle.kts | 1 - okhttp-logging-interceptor/build.gradle.kts | 1 - okhttp-sse/build.gradle.kts | 1 - okhttp-tls/build.gradle.kts | 1 - okhttp-urlconnection/build.gradle.kts | 1 - okhttp-zstd/build.gradle.kts | 1 - okhttp/build.gradle.kts | 3 +- settings.gradle.kts | 5 +- test_docs.sh | 6 +- 23 files changed, 86 insertions(+), 53 deletions(-) delete mode 100644 .vscode/settings.json diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 0e1f70bf3..8a7b46e4b 100644 --- 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: Run with Jlink - run: ./gradlew module-tests:imageRun + - name: Test module-tests + run: ./gradlew module-tests:test -PokhttpModuleTests=true + + - name: Run with Jlink + run: ./gradlew module-tests:imageRun -PokhttpModuleTests=true diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 849f79e6b..000000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "java.compile.nullAnalysis.mode": "automatic" -} diff --git a/build.gradle.kts b/build.gradle.kts index 498e84679..feb40531c 100644 --- 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 { @@ -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().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 { + 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 { 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 index 439ab99d0..2212f875d 100644 --- 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 index 6042c3878..b129e75b3 100644 --- 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 index 5b2e1601c..62a961018 100644 --- 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 index 42c260db6..2a841f3d7 100644 --- 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 index e99b14b18..82e22e7e0 100644 --- 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 index ed25fc7ad..b61329d86 100644 --- 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 index abc3d2f30..164b76ec4 100644 --- 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 { diff --git a/okcurl/build.gradle.kts b/okcurl/build.gradle.kts index a2e879421..8cf9d523d 100644 --- 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 index a0cf017c5..16b0d3f47 100644 --- 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 index c6ed8a804..efc1f3162 100644 --- 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 index f691598de..83735fbb9 100644 --- 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 index 55ac31516..472c9fd0a 100644 --- 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 index 6c3cfbb8c..2c017fd9f 100644 --- 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 index 4e1a201d8..88052cc88 100644 --- 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 index 312283164..3f8fa2e96 100644 --- 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 index 569cbb925..cf9abeae6 100644 --- 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 index 8250b4741..9db5f5fcd 100644 --- 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 index b9b6e6861..ba9e1bdcd 100644 --- 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 index f78afa259..4cdce719b 100644 --- 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 index ba482f0bf..477d00c9b 100755 --- 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