From d5515e998d19e56e0c5121836a25bc511dddd862 Mon Sep 17 00:00:00 2001 From: Adam <152864218+adam-enko@users.noreply.github.com> Date: Wed, 11 Sep 2024 14:44:32 +0200 Subject: [PATCH] Add DokkaJavadocPlugin (#3796) * Add DokkaJavadocPlugin KT-71357 --- .../api/dokka-gradle-plugin.api | 4 ++ .../dokka-gradle-plugin/build.gradle.kts | 38 +++++++++++++++---- .../main/kotlin/formats/DokkaJavadocPlugin.kt | 20 ++++++++++ .../main/kotlin/internal/v2MigrationUtils.kt | 2 +- .../testFixtures/kotlin/GradleTestKitUtils.kt | 1 + .../kotlin/projects/MultiModuleProject.kt | 3 ++ .../kotlin/DokkaPluginFunctionalTest.kt | 33 ++++++++-------- .../kotlin/MultiModuleFunctionalTest.kt | 28 +++++++++++--- 8 files changed, 101 insertions(+), 28 deletions(-) create mode 100644 dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaJavadocPlugin.kt diff --git a/dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api b/dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api index 6818408637..5ae8ca02b3 100644 --- a/dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api +++ b/dokka-runners/dokka-gradle-plugin/api/dokka-gradle-plugin.api @@ -506,6 +506,10 @@ public final class org/jetbrains/dokka/gradle/formats/DokkaHtmlPlugin$inlined$sa public final synthetic fun execute (Ljava/lang/Object;)V } +public abstract class org/jetbrains/dokka/gradle/formats/DokkaJavadocPlugin : org/jetbrains/dokka/gradle/formats/DokkaFormatPlugin { + public fun configure (Lorg/jetbrains/dokka/gradle/formats/DokkaFormatPlugin$DokkaFormatPluginContext;)V +} + public abstract class org/jetbrains/dokka/gradle/formats/DokkaPublication : java/io/Serializable, org/gradle/api/Named, org/gradle/api/plugins/ExtensionAware { public abstract fun getCacheRoot ()Lorg/gradle/api/file/DirectoryProperty; public abstract fun getEnabled ()Lorg/gradle/api/provider/Property; diff --git a/dokka-runners/dokka-gradle-plugin/build.gradle.kts b/dokka-runners/dokka-gradle-plugin/build.gradle.kts index 8fd584a40c..805b6fd28e 100644 --- a/dokka-runners/dokka-gradle-plugin/build.gradle.kts +++ b/dokka-runners/dokka-gradle-plugin/build.gradle.kts @@ -98,11 +98,7 @@ dependencies { } gradlePlugin { - plugins.register("dokka") { - id = "org.jetbrains.dokka" - displayName = "Dokka Gradle Plugin" - description = "Dokka is an API documentation engine for Kotlin" - implementationClass = "org.jetbrains.dokka.gradle.DokkaPlugin" + plugins.configureEach { tags.addAll( "dokka", "kotlin", @@ -110,10 +106,38 @@ gradlePlugin { "android", "api reference", "documentation", - "html", - "website", ) } + plugins.register("dokkaHtml") { + id = "org.jetbrains.dokka" + displayName = "Dokka Gradle Plugin" + description = """ + Dokka is the API documentation engine for Kotlin. + + This plugin generates output that looks like Javadoc websites. + See https://kotlinlang.org/docs/dokka-html.html for more information. + + HTML is Dokka's default and recommended output format. It is currently in Beta and approaching the Stable release. + """.trimIndent() + implementationClass = "org.jetbrains.dokka.gradle.DokkaPlugin" + tags.addAll("html") + } + plugins.register("dokkaJavadoc") { + id = "org.jetbrains.dokka-javadoc" + displayName = "Dokka Gradle Plugin Javadoc" + description = """ + Dokka is the API documentation engine for Kotlin. + + This plugin generates output that looks like Javadoc websites. + See https://kotlinlang.org/docs/dokka-javadoc.html for more information. + + The Javadoc output format is still in Alpha, so you may find bugs and experience migration issues when using it. + Successful integration with tools that accept Java's Javadoc HTML as input is not guaranteed. + You use it at your own risk. + """.trimIndent() + implementationClass = "org.jetbrains.dokka.gradle.formats.DokkaJavadocPlugin" + tags.addAll("javadoc") + } } testing.suites { diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaJavadocPlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaJavadocPlugin.kt new file mode 100644 index 0000000000..e97d1cdfad --- /dev/null +++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaJavadocPlugin.kt @@ -0,0 +1,20 @@ +/* + * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ +package org.jetbrains.dokka.gradle.formats + +import org.gradle.kotlin.dsl.dependencies +import org.jetbrains.dokka.gradle.internal.DokkaInternalApi + +/** + * Gradle plugin that configures Dokka Javadoc output format + */ +abstract class DokkaJavadocPlugin +@DokkaInternalApi +constructor() : DokkaFormatPlugin(formatName = "javadoc") { + override fun DokkaFormatPluginContext.configure() { + project.dependencies { + dokkaPlugin(dokka("javadoc-plugin")) + } + } +} diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt index cdb3beab69..6ca77458ed 100644 --- a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt +++ b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/v2MigrationUtils.kt @@ -28,7 +28,7 @@ internal fun addV2MigrationHelpers( project.configurations.createDokkaDefaultRuntimeConfiguration() setupDokkaTasks(project, "GFM") - setupDokkaTasks(project, "Javadoc", multiModuleTaskSupported = false) + setupDokkaTasks(project, "Javadoc", createDokkaPluginFormatConfiguration = false, multiModuleTaskSupported = false) setupDokkaTasks(project, "Jekyll") setupDokkaTasks(project, "HTML", createDokkaPluginFormatConfiguration = false) diff --git a/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleTestKitUtils.kt b/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleTestKitUtils.kt index cdb2b6d2e8..59e1beb308 100644 --- a/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleTestKitUtils.kt +++ b/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/GradleTestKitUtils.kt @@ -338,6 +338,7 @@ interface ProjectDirectoryScope { | ) | filter { | includeGroup("org.jetbrains.dokka") + | includeGroup("org.jetbrains.dokka-javadoc") | } |} """.trimMargin() diff --git a/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/projects/MultiModuleProject.kt b/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/projects/MultiModuleProject.kt index 7c0db7ca32..25c95bbbb3 100644 --- a/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/projects/MultiModuleProject.kt +++ b/dokka-runners/dokka-gradle-plugin/src/testFixtures/kotlin/projects/MultiModuleProject.kt @@ -38,6 +38,7 @@ fun TestScope.initMultiModuleProject( | // with ClassNotFound KotlinPluginExtension... very weird | kotlin("jvm") version embeddedKotlinVersion apply false | id("org.jetbrains.dokka") version "${DokkaConstants.DOKKA_VERSION}" + | id("org.jetbrains.dokka-javadoc") version "${DokkaConstants.DOKKA_VERSION}" |} | |dependencies { @@ -52,6 +53,7 @@ fun TestScope.initMultiModuleProject( |plugins { | kotlin("jvm") version embeddedKotlinVersion | id("org.jetbrains.dokka") version "${DokkaConstants.DOKKA_VERSION}" + | id("org.jetbrains.dokka-javadoc") version "${DokkaConstants.DOKKA_VERSION}" |} | """.trimMargin() @@ -79,6 +81,7 @@ fun TestScope.initMultiModuleProject( |plugins { | kotlin("jvm") version embeddedKotlinVersion | id("org.jetbrains.dokka") version "${DokkaConstants.DOKKA_VERSION}" + | id("org.jetbrains.dokka-javadoc") version "${DokkaConstants.DOKKA_VERSION}" |} | """.trimMargin() diff --git a/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/DokkaPluginFunctionalTest.kt b/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/DokkaPluginFunctionalTest.kt index 0d7fb2988b..3ee5ca6338 100644 --- a/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/DokkaPluginFunctionalTest.kt +++ b/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/DokkaPluginFunctionalTest.kt @@ -6,7 +6,6 @@ package org.jetbrains.dokka.gradle import io.kotest.assertions.asClue import io.kotest.assertions.withClue import io.kotest.core.spec.style.FunSpec -import io.kotest.matchers.collections.shouldContainExactly import io.kotest.matchers.collections.shouldContainExactlyInAnyOrder import io.kotest.matchers.shouldBe import io.kotest.matchers.string.shouldContain @@ -19,6 +18,7 @@ class DokkaPluginFunctionalTest : FunSpec({ buildGradleKts = """ |plugins { | id("org.jetbrains.dokka") version "$DOKKA_VERSION" + | id("org.jetbrains.dokka-javadoc") version "$DOKKA_VERSION" |} | |val printDeclarableConfigurations by tasks.registering { @@ -45,9 +45,11 @@ class DokkaPluginFunctionalTest : FunSpec({ dokkaTasks.shouldContainExactly( //@formatter:off - "dokkaGenerate" to "Generates Dokka publications for all formats", - "dokkaGenerateModuleHtml" to "Executes the Dokka Generator, generating a html module", - "dokkaGeneratePublicationHtml" to "Executes the Dokka Generator, generating the html publication", + "dokkaGenerate" to "Generates Dokka publications for all formats", + "dokkaGenerateModuleHtml" to "Executes the Dokka Generator, generating a html module", + "dokkaGeneratePublicationHtml" to "Executes the Dokka Generator, generating the html publication", + "dokkaGenerateModuleJavadoc" to "Executes the Dokka Generator, generating a javadoc module", + "dokkaGeneratePublicationJavadoc" to "Executes the Dokka Generator, generating the javadoc publication", //@formatter:on ) } @@ -70,13 +72,17 @@ class DokkaPluginFunctionalTest : FunSpec({ .map { it.trim() } .sorted() - declarableConfigurations.shouldContainExactly( - "dokka", - "dokkaHtmlGeneratorRuntime", - "dokkaHtmlPlugin", - "dokkaHtmlPublicationPlugin", - "dokkaHtmlPublicationPluginApiOnly~internal", - "dokkaPlugin", + declarableConfigurations.shouldContainExactlyInAnyOrder( + buildList { + add("dokka") + add("dokkaPlugin") + expectedFormats.forEach { + add("dokka${it}GeneratorRuntime") + add("dokka${it}Plugin") + add("dokka${it}PublicationPlugin") + add("dokka${it}PublicationPluginApiOnly~internal") + } + } ) } } @@ -223,10 +229,8 @@ class DokkaPluginFunctionalTest : FunSpec({ * The output formats that Dokka supports. */ private val expectedFormats = listOf( - //"Gfm", "Html", - //"Javadoc", - //"Jekyll", + "Javadoc", ) /** @@ -284,6 +288,5 @@ class DokkaPluginFunctionalTest : FunSpec({ .filterNot { it.startsWith("Consumable configurations with identical capabilities within a project") } .joinToString("\n") } - } } diff --git a/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt b/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt index cfe9230702..bf98b41589 100644 --- a/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt +++ b/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt @@ -32,6 +32,7 @@ class MultiModuleFunctionalTest : FunSpec({ project.runner .addArguments( ":dokkaGenerate", + "--stacktrace", "--rerun-tasks", ) .forwardOutput() @@ -145,7 +146,7 @@ class MultiModuleFunctionalTest : FunSpec({ test("expect build is successful") { output shouldContainAll listOf( "BUILD SUCCESSFUL", - "4 actionable tasks: 4 up-to-date", + "8 actionable tasks: 8 up-to-date", ) } @@ -189,6 +190,9 @@ class MultiModuleFunctionalTest : FunSpec({ ":dokkaGeneratePublicationHtml", ":subproject-hello:dokkaGenerateModuleHtml", ":subproject-goodbye:dokkaGenerateModuleHtml", + ":dokkaGeneratePublicationJavadoc", + ":subproject-hello:dokkaGenerateModuleJavadoc", + ":subproject-goodbye:dokkaGenerateModuleJavadoc", ) test("setup build cache") { @@ -215,6 +219,7 @@ class MultiModuleFunctionalTest : FunSpec({ .addArguments( "clean", "--build-cache", + "--stacktrace", ) .forwardOutput() .build { @@ -248,6 +253,7 @@ class MultiModuleFunctionalTest : FunSpec({ .addArguments( "clean", "--build-cache", + "--stacktrace", ) .forwardOutput() .build { @@ -445,6 +451,7 @@ class MultiModuleFunctionalTest : FunSpec({ "--no-configuration-cache", "--no-build-cache", "--quiet", + "--stacktrace", ) .forwardOutput() .build { @@ -460,6 +467,7 @@ class MultiModuleFunctionalTest : FunSpec({ "--no-configuration-cache", "--no-build-cache", "--no-parallel", + "--stacktrace", // no logging option => lifecycle log level ) .forwardOutput() @@ -480,13 +488,22 @@ class MultiModuleFunctionalTest : FunSpec({ .filter { it.startsWith("> Task :") } .shouldContainAll( "> Task :clean", - "> Task :dokkaGenerate", - "> Task :dokkaGenerateModuleHtml", - "> Task :dokkaGeneratePublicationHtml", "> Task :subproject-goodbye:clean", - "> Task :subproject-goodbye:dokkaGenerateModuleHtml", "> Task :subproject-hello:clean", + + "> Task :dokkaGenerate", + + "> Task :dokkaGeneratePublicationHtml", + "> Task :dokkaGeneratePublicationJavadoc", + + "> Task :dokkaGenerateModuleHtml", + "> Task :dokkaGenerateModuleJavadoc", + "> Task :subproject-hello:dokkaGenerateModuleHtml", + "> Task :subproject-hello:dokkaGenerateModuleJavadoc", + + "> Task :subproject-goodbye:dokkaGenerateModuleHtml", + "> Task :subproject-goodbye:dokkaGenerateModuleJavadoc", ) } } @@ -580,6 +597,7 @@ class MultiModuleFunctionalTest : FunSpec({ .addArguments( ":dokkaGeneratePublicationHtml", "--rerun-tasks", + "--stacktrace", ) .forwardOutput() .build {