Skip to content

Commit

Permalink
add support for Dokka 2 (#849)
Browse files Browse the repository at this point in the history
* add support for Dokka 2

* ktlint

* config cache

* detect v2 mode based on extension
  • Loading branch information
gabrielittner authored Oct 4, 2024
1 parent 441932f commit dd9aa18
Show file tree
Hide file tree
Showing 5 changed files with 69 additions and 10 deletions.
7 changes: 6 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

## 0.30.0 **UNRELEASED**

- Add support for Dokka 2.0.0-Beta
- Supports `org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled`
- Supports both `org.jetbrains.dokka` and `org.jetbrains.dokka-javadoc`
- If both are applied the javadoc output is published
- Removed support for the old `org.jetbrains.dokka-android` plugin
- Remove usages of deprecated Gradle API that is scheduled to be removed in Gradle 9.0
- Raised minimum supported Gradle version

Expand All @@ -23,7 +28,7 @@

Configuration cache is generally supported, except for:
- Publishing releases to Maven Central (snapshots are fine), blocked by [Gradle issue #22779](https://github.com/gradle/gradle/issues/22779).
- Dokka does not support configuration cache
- When using Dokka until Dokka version 2.1.0 is out


## 0.29.0 *(2024-06-20)*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -252,4 +252,46 @@ class MavenPublishPluginSpecialCaseTest {
assertThat(result).javadocJar().exists()
assertThat(result).javadocJar().containsFiles(ignoreAdditionalFiles = true, "index.html")
}

@TestParameterInjectorTest
fun dokka2() {
val kotlinVersion = KotlinVersion.entries.last()
val original = kotlinJvmProjectSpec(kotlinVersion)
val project = original.copy(
plugins = original.plugins + dokka2Plugin,
basePluginConfig = original.basePluginConfig.replace("JavadocJar.Empty()", "JavadocJar.Dokka(\"dokkaGeneratePublicationHtml\")"),
)
val result = project.run(fixtures, testProjectDir, testOptions)

assertThat(result).outcome().succeeded()
assertThat(result).artifact("jar").exists()
assertThat(result).pom().exists()
assertThat(result).pom().matchesExpectedPom(kotlinStdlibJdk(kotlinVersion))
assertThat(result).module().exists()
assertThat(result).sourcesJar().exists()
assertThat(result).sourcesJar().containsAllSourceFiles()
assertThat(result).javadocJar().exists()
assertThat(result).javadocJar().containsFiles(ignoreAdditionalFiles = true, "index.html")
}

@TestParameterInjectorTest
fun dokka2Javadoc() {
val kotlinVersion = KotlinVersion.entries.last()
val original = kotlinJvmProjectSpec(kotlinVersion)
val project = original.copy(
plugins = original.plugins + dokka2JavadocPlugin,
basePluginConfig = original.basePluginConfig.replace("JavadocJar.Empty()", "JavadocJar.Dokka(\"dokkaGeneratePublicationJavadoc\")"),
)
val result = project.run(fixtures, testProjectDir, testOptions)

assertThat(result).outcome().succeeded()
assertThat(result).artifact("jar").exists()
assertThat(result).pom().exists()
assertThat(result).pom().matchesExpectedPom(kotlinStdlibJdk(kotlinVersion))
assertThat(result).module().exists()
assertThat(result).sourcesJar().exists()
assertThat(result).sourcesJar().containsAllSourceFiles()
assertThat(result).javadocJar().exists()
assertThat(result).javadocJar().containsFiles(ignoreAdditionalFiles = true, "index.html")
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ fun ProjectSpec.run(fixtures: Path, temp: Path, options: TestOptions): ProjectRe

val task = ":publishAllPublicationsToTestFolderRepository"
val arguments = mutableListOf(task, "--stacktrace")
if (supportsConfigCaching(plugins)) {
if (supportsConfigCaching()) {
arguments.add("--configuration-cache")
}

Expand All @@ -40,9 +40,10 @@ fun ProjectSpec.run(fixtures: Path, temp: Path, options: TestOptions): ProjectRe
)
}

private fun supportsConfigCaching(plugins: List<PluginSpec>): Boolean {
// TODO https://github.com/Kotlin/dokka/issues/2231
return !plugins.any { it.id == dokkaPlugin.id }
private fun ProjectSpec.supportsConfigCaching(): Boolean {
// TODO can always return true when dropping support for dokka in v1 mode
// to simplify the test set up this assumes that version 2.x always runs in v2 mode
return plugins.none { it.id == dokkaPlugin.id && it.version!!.startsWith("1.") }
}

private fun ProjectSpec.writeBuildFile(path: Path, repo: Path, options: TestOptions) {
Expand Down Expand Up @@ -187,6 +188,8 @@ private fun ProjectSpec.writeGradleProperties(path: Path, options: TestOptions)
appendLine("org.gradle.vfs.watch=false")
appendLine("kotlin.compiler.execution.strategy=in-process")
appendLine("kotlin.mpp.androidSourceSetLayoutVersion1.nowarn=true")
appendLine("org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled")
appendLine("org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true")
appendLine()

if (options.config == TestOptions.Config.PROPERTIES) {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,8 @@ val kotlinAndroidPlugin = PluginSpec("org.jetbrains.kotlin.android")
val androidLibraryPlugin = PluginSpec("com.android.library")
val gradlePluginPublishPlugin = PluginSpec("com.gradle.plugin-publish")
val dokkaPlugin = PluginSpec("org.jetbrains.dokka", "1.8.10")
val dokka2Plugin = PluginSpec("org.jetbrains.dokka", "2.0.0-Beta")
val dokka2JavadocPlugin = PluginSpec("org.jetbrains.dokka-javadoc", "2.0.0-Beta")

val fixtures = Paths.get("src/integrationTest/fixtures2").absolute()

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -406,12 +406,19 @@ abstract class MavenPublishBaseExtension @Inject constructor(
private fun defaultJavaDocOption(javadocJar: Boolean, plainJavadocSupported: Boolean): JavadocJar {
return if (!javadocJar) {
JavadocJar.None()
} else if (project.plugins.hasPlugin("org.jetbrains.dokka") || project.plugins.hasPlugin("org.jetbrains.dokka-android")) {
val dokkaTask = project.provider {
val tasks = project.tasks.withType(DokkaTask::class.java)
tasks.singleOrNull()?.name ?: "dokkaHtml"
} else if (project.plugins.hasPlugin("org.jetbrains.dokka-javadoc")) {
JavadocJar.Dokka("dokkaGeneratePublicationJavadoc")
} else if (project.plugins.hasPlugin("org.jetbrains.dokka")) {
// only dokka v2 has an extension
if (project.extensions.findByName("dokka") != null) {
JavadocJar.Dokka("dokkaGeneratePublicationHtml")
} else {
val dokkaTask = project.provider {
val tasks = project.tasks.withType(DokkaTask::class.java)
tasks.singleOrNull()?.name ?: "dokkaHtml"
}
JavadocJar.Dokka(dokkaTask)
}
JavadocJar.Dokka(dokkaTask)
} else if (plainJavadocSupported) {
project.tasks.withType(Javadoc::class.java).configureEach {
val options = it.options as StandardJavadocDocletOptions
Expand Down

0 comments on commit dd9aa18

Please sign in to comment.