From adc64d5cbcd4286dd4c766269004347768c96afb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Deleuze?= Date: Wed, 16 Jul 2025 15:56:41 +0200 Subject: [PATCH] Upgrade to Dokka 2.0.0 See https://kotlinlang.org/docs/dokka-migration.html Closes gh-35211 --- build.gradle | 2 +- buildSrc/build.gradle | 1 + .../build/KotlinConventions.java | 44 ++++++++++++++++++- framework-api/framework-api.gradle | 19 ++++---- gradle.properties | 3 ++ gradle/docs-dokka.gradle | 32 -------------- gradle/spring-module.gradle | 5 --- 7 files changed, 55 insertions(+), 51 deletions(-) delete mode 100644 gradle/docs-dokka.gradle diff --git a/build.gradle b/build.gradle index 39bffc99e6..6fafc96e97 100644 --- a/build.gradle +++ b/build.gradle @@ -2,7 +2,7 @@ plugins { id 'io.freefair.aspectj' version '8.13.1' apply false // kotlinVersion is managed in gradle.properties id 'org.jetbrains.kotlin.plugin.serialization' version "${kotlinVersion}" apply false - id 'org.jetbrains.dokka' version '1.9.20' + id 'org.jetbrains.dokka' id 'com.github.bjornvester.xjc' version '1.8.2' apply false id 'io.github.goooler.shadow' version '8.1.8' apply false id 'me.champeau.jmh' version '0.7.2' apply false diff --git a/buildSrc/build.gradle b/buildSrc/build.gradle index 7d0027111b..ed471b72ea 100644 --- a/buildSrc/build.gradle +++ b/buildSrc/build.gradle @@ -20,6 +20,7 @@ ext { dependencies { checkstyle "io.spring.javaformat:spring-javaformat-checkstyle:${javaFormatVersion}" implementation "org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlinVersion}" + implementation "org.jetbrains.dokka:dokka-gradle-plugin:2.0.0" implementation "com.tngtech.archunit:archunit:1.4.0" implementation "org.gradle:test-retry-gradle-plugin:1.6.2" implementation "io.spring.javaformat:spring-javaformat-gradle-plugin:${javaFormatVersion}" diff --git a/buildSrc/src/main/java/org/springframework/build/KotlinConventions.java b/buildSrc/src/main/java/org/springframework/build/KotlinConventions.java index 59b2a3f401..3163f143fc 100644 --- a/buildSrc/src/main/java/org/springframework/build/KotlinConventions.java +++ b/buildSrc/src/main/java/org/springframework/build/KotlinConventions.java @@ -17,6 +17,10 @@ package org.springframework.build; import org.gradle.api.Project; +import org.gradle.api.tasks.SourceSet; +import org.gradle.api.tasks.SourceSetContainer; +import org.jetbrains.dokka.gradle.DokkaExtension; +import org.jetbrains.dokka.gradle.DokkaPlugin; import org.jetbrains.kotlin.gradle.dsl.JvmTarget; import org.jetbrains.kotlin.gradle.dsl.KotlinVersion; import org.jetbrains.kotlin.gradle.tasks.KotlinCompile; @@ -28,8 +32,14 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile; public class KotlinConventions { void apply(Project project) { - project.getPlugins().withId("org.jetbrains.kotlin.jvm", - (plugin) -> project.getTasks().withType(KotlinCompile.class, this::configure)); + project.getPlugins().withId("org.jetbrains.kotlin.jvm", _ -> { + project.getTasks().withType(KotlinCompile.class, this::configure); + if (project.getLayout().getProjectDirectory().dir("src/main/kotlin").getAsFile().exists()) { + project.getPlugins().apply(DokkaPlugin.class); + project.getExtensions().configure(DokkaExtension.class, dokka -> configure(project, dokka)); + project.project(":framework-api").getDependencies().add("dokka", project); + } + }); } private void configure(KotlinCompile compile) { @@ -49,4 +59,34 @@ public class KotlinConventions { }); } + private void configure(Project project, DokkaExtension dokka) { + dokka.getDokkaSourceSets().forEach(sourceSet -> { + sourceSet.getSourceRoots().setFrom(project.file("src/main/kotlin")); + sourceSet.getClasspath() + .from(project.getExtensions() + .getByType(SourceSetContainer.class) + .getByName(SourceSet.MAIN_SOURCE_SET_NAME) + .getOutput()); + var externalDocumentationLinks = sourceSet.getExternalDocumentationLinks(); + externalDocumentationLinks.register("spring-framework", spec -> { + spec.url("https://docs.spring.io/spring-framework/docs/current/javadoc-api/"); + spec.packageListUrl("https://docs.spring.io/spring-framework/docs/current/javadoc-api/element-list"); + }); + externalDocumentationLinks.register("reactor-core", spec -> + spec.url("https://projectreactor.io/docs/core/release/api/")); + externalDocumentationLinks.register("reactive-streams", spec -> + spec.url("https://www.reactive-streams.org/reactive-streams-1.0.3-javadoc/")); + externalDocumentationLinks.register("kotlinx-coroutines", spec -> + spec.url("https://kotlinlang.org/api/kotlinx.coroutines/")); + externalDocumentationLinks.register("hamcrest", spec -> + spec.url("https://javadoc.io/doc/org.hamcrest/hamcrest/2.1/")); + externalDocumentationLinks.register("jakarta-servlet", spec -> { + spec.url("https://javadoc.io/doc/jakarta.servlet/jakarta.servlet-api/latest/"); + spec.packageListUrl("https://javadoc.io/doc/jakarta.servlet/jakarta.servlet-api/latest/element-list"); + }); + externalDocumentationLinks.register("rsocket-core", spec -> + spec.url("https://javadoc.io/static/io.rsocket/rsocket-core/1.1.1/")); + }); + } + } diff --git a/framework-api/framework-api.gradle b/framework-api/framework-api.gradle index f9da96bcd0..fc3ecb8637 100644 --- a/framework-api/framework-api.gradle +++ b/framework-api/framework-api.gradle @@ -1,6 +1,7 @@ plugins { id 'java-platform' id 'io.freefair.aggregate-javadoc' version '8.13.1' + id 'org.jetbrains.dokka' } description = "Spring Framework API Docs" @@ -54,23 +55,19 @@ javadoc { } } -/** - * Produce KDoc for all Spring Framework modules in "build/docs/kdoc" - */ -rootProject.tasks.dokkaHtmlMultiModule.configure { - dependsOn { - tasks.named("javadoc") +dokka { + moduleName = "spring-framework" + dokkaPublications.html { + outputDirectory = project.java.docsDir.dir("kdoc-api") + includes.from("$rootProject.rootDir/framework-docs/src/docs/api/dokka-overview.md") } - moduleName.set("spring-framework") - outputDirectory.set(project.java.docsDir.dir("kdoc-api").get().asFile) - includes.from("$rootProject.rootDir/framework-docs/src/docs/api/dokka-overview.md") } /** * Zip all Java docs (javadoc & kdoc) into a single archive */ tasks.register('docsZip', Zip) { - dependsOn = ['javadoc', rootProject.tasks.dokkaHtmlMultiModule] + dependsOn = ['javadoc', 'dokkaGenerate'] group = "distribution" description = "Builds -${archiveClassifier} archive containing api and reference " + "for deployment at https://docs.spring.io/spring-framework/docs/." @@ -83,7 +80,7 @@ tasks.register('docsZip', Zip) { from(javadoc) { into "javadoc-api" } - from(rootProject.tasks.dokkaHtmlMultiModule.outputDirectory) { + from(project.java.docsDir.dir("kdoc-api")) { into "kdoc-api" } } diff --git a/gradle.properties b/gradle.properties index 8c6ebdd9ea..8d3de9c131 100644 --- a/gradle.properties +++ b/gradle.properties @@ -9,3 +9,6 @@ byteBuddyVersion=1.17.6 kotlin.jvm.target.validation.mode=ignore kotlin.stdlib.default.dependency=false + +org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true +org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled \ No newline at end of file diff --git a/gradle/docs-dokka.gradle b/gradle/docs-dokka.gradle deleted file mode 100644 index 7d593bf49d..0000000000 --- a/gradle/docs-dokka.gradle +++ /dev/null @@ -1,32 +0,0 @@ -tasks.findByName("dokkaHtmlPartial")?.configure { - outputDirectory.set(new File(buildDir, "docs/kdoc")) - dokkaSourceSets { - configureEach { - sourceRoots.setFrom(file("src/main/kotlin")) - classpath.from(sourceSets["main"].runtimeClasspath) - externalDocumentationLink { - url.set(new URL("https://docs.spring.io/spring-framework/docs/current/javadoc-api/")) - packageListUrl.set(new URL("https://docs.spring.io/spring-framework/docs/current/javadoc-api/element-list")) - } - externalDocumentationLink { - url.set(new URL("https://projectreactor.io/docs/core/release/api/")) - } - externalDocumentationLink { - url.set(new URL("https://www.reactive-streams.org/reactive-streams-1.0.3-javadoc/")) - } - externalDocumentationLink { - url.set(new URL("https://kotlin.github.io/kotlinx.coroutines/")) - } - externalDocumentationLink { - url.set(new URL("https://javadoc.io/doc/org.hamcrest/hamcrest/2.1/")) - } - externalDocumentationLink { - url.set(new URL("https://javadoc.io/doc/jakarta.servlet/jakarta.servlet-api/latest/")) - packageListUrl.set(new URL("https://javadoc.io/doc/jakarta.servlet/jakarta.servlet-api/latest/element-list")) - } - externalDocumentationLink { - url.set(new URL("https://javadoc.io/static/io.rsocket/rsocket-core/1.1.1/")) - } - } - } -} diff --git a/gradle/spring-module.gradle b/gradle/spring-module.gradle index 076a67b192..a899900abf 100644 --- a/gradle/spring-module.gradle +++ b/gradle/spring-module.gradle @@ -15,11 +15,6 @@ dependencies { jmh 'net.sf.jopt-simple:jopt-simple' } -pluginManager.withPlugin("kotlin") { - apply plugin: "org.jetbrains.dokka" - apply from: "${rootDir}/gradle/docs-dokka.gradle" -} - jmh { duplicateClassesStrategy = DuplicatesStrategy.EXCLUDE }