Migrate to Dokka Gradle plugin v2

The Dokka Gradle plugin (DGP) is a tool for generating comprehensive API documentation for Kotlin projects built with Gradle.

DGP seamlessly processes both Kotlin's KDoc comments and Java's Javadoc comments to extract information and create structured documentation in HTML or Javadoc format.

Starting with Dokka 2.0.0-Beta, you can try the Dokka Gradle plugin v2, the new version of DGP. With Dokka 2.0.0-Beta, you can use the Dokka Gradle plugin either in v1 or v2 modes.

DGP v2 introduces significant improvements to DGP, aligning more closely with Gradle best practices:

Adopts Gradle types, which leads to better performance.
Uses an intuitive top-level DSL configuration instead of a low-level task-based setup, which simplifies the build scripts and their readability.
Takes a more declarative approach to documentation aggregation, which makes multi-project documentation easier to manage.
Uses a type-safe plugin configuration, which improves the reliability and maintainability of your build scripts.
Fully supports Gradle configuration cache and build cache, which improves performance and simplifies build work.

Before you start

Before starting the migration, complete the following steps.

Verify supported versions

Ensure that your project meets the minimum version requirements:

Tool	Version
Gradle	7.6 or higher
Android Gradle plugin	7.0 or higher
Kotlin Gradle plugin	1.9 or higher

Enable the new Dokka Gradle plugin

Update the Dokka version to 2.0.0-Beta in the plugins {} block of your project’s build.gradle.kts file:
plugins { kotlin("jvm") version "1.9.25" id("org.jetbrains.dokka") version "2.0.0-Beta" }
Alternatively, you can use version catalog to enable the Dokka Gradle plugin v2.
In the project's gradle.properties file, set the following opt-in flag with helpers to activate the new plugin version:
org.jetbrains.dokka.experimental.gradle.pluginMode=V2EnabledWithHelpers
This flag activates the DGP v2 plugin with migration helpers, which prevent compilation errors when build scripts reference tasks from DGP v1 that are no longer available in DGP v2. You have to disable the migration helpers after completing your migration.
If your project does not have a gradle.properties file, create one in the root directory of your project.
Sync your project with Gradle to ensure the new plugin is properly applied:
- If you use IntelliJ IDEA, click the Reload All Gradle Projects button from the Gradle tool window.
- If you use Android Studio, select File | Sync Project with Gradle Files.

Migrate your project

After updating the Dokka Gradle plugin to v2, follow the migration steps applicable to your project.

Adjust configuration options

DGP v2 introduces some changes in the Gradle configuration options. In the build.gradle.kts file, adjust the configuration options according to your project setup:

New top-level DSL configuration: Replace the old configuration syntax with the new top-level dokka {} DSL configuration. For example:
Previous configuration:
tasks.withType<DokkaTask>().configureEach { dokkaSourceSets { named("main") { moduleName.set("Project Name") includes.from("README.md") sourceLink { localDirectory.set(file("src/main/kotlin")) remoteUrl.set(URL("https://example.com/src")) remoteLineSuffix.set("#L") } } } } tasks.dokkaHtml { pluginConfiguration<DokkaBase, DokkaBaseConfiguration> { customStyleSheets.set(listOf("styles.css")) customAssets.set(listOf("logo.png")) footerMessage.set("(c) Your Company") } }
New configuration:
dokka { moduleName.set("Project Name") dokkaSourceSets.main { includes.from("README.md") sourceLink { localDirectory.set(file("src/main/kotlin")) remoteUrl.set(URL("https://example.com/src")) remoteLineSuffix.set("#L") } } pluginsConfiguration.html { customStyleSheets.from("styles.css") customAssets.from("logo.png") footerMessage.set("(c) Your Company") } }
Visibility settings: The documentedVisibilities property has changed from Visibility.PUBLIC to VisibilityModifier.Public.
Previous configuration:
import org.jetbrains.dokka.DokkaConfiguration.Visibility // ... documentedVisibilities.set( setOf(Visibility.PUBLIC) )
New configuration:
import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier // ... documentedVisibilities.set( setOf(VisibilityModifier.Public) )
External documentation link: The source link configuration has changed. The remote URL is now specified using the URI class instead of the URL class.
Previous configuration:
remoteUrl.set(URL("https://github.com/your-repo"))
New configuration:
remoteUrl.set(URI("https://github.com/your-repo"))
Custom assets: The customAssets property now uses collections of files (FileCollection) instead of lists (var List<File>).
Previous configuration:
customAssets = listOf(file("example.png"), file("example2.png"))
New configuration:
customAssets.from("example.png", "example2.png")
Output directory: Use the dokka {} block to specify a single output directory for all Dokka-generated documentation.
Previous configuration:
tasks.dokkaHtml{ dokkaSourceSets { configureEach { outputDirectory.set(layout.buildDirectory.dir("dokkaDir")) } } }
New configuration:
dokka { dokkaPublicationDirectory.set(layout.buildDirectory.dir("dokkaDir")) }

DPG v2 moves away from using subprojects {} or allprojects {} to share configuration across modules. In future Gradle versions, using these approaches will lead to errors.

Follow the steps below to properly share Dokka configuration in multi-module projects with existing convention plugins or without convention plugins.

After sharing the Dokka configuration, you can aggregate the documentation from multiple modules into a single output. For more information, see Update documentation aggregation in multi-module projects.

Multi-module projects without convention plugins

To share the Dokka configuration in multi-module projects without convention plugins, you need to set up the buildSrc directory, set up the convention plugin, and then apply the plugin to your modules (subprojects).

Set up the buildSrc directory

In your project root, create a buildSrc directory containing two files:
- settings.gradle.kts
- build.gradle.kts
In the buildSrc/settings.gradle.kts file, add the following snippet:
rootProject.name = "buildSrc"
In the buildSrc/build.gradle.kts file, add the following snippet:
plugins { `kotlin-dsl` } repositories { mavenCentral() gradlePluginPortal() } dependencies { implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.0.0-Beta") }

Set up the Dokka convention plugin

After setting up the buildSrc directory:

Create a buildSrc/src/main/kotlin/dokka-convention.gradle.kts file to host the convention plugin.
In the dokka-convention.gradle.kts file, add the following snippet:
plugins { id("org.jetbrains.dokka") } dokka { // The shared configuration goes here }
You need to add the shared Dokka configuration common to all subprojects within the dokka {} block. Also, you don't need to specify a Dokka version. The version is already set in the buildSrc/build.gradle.kts file.

Apply the convention plugin to your modules

Apply the Dokka convention plugin across your modules (subprojects) by adding it to each subproject's build.gradle.kts file:

plugins { 
    id("dokka-convention")
}

Multi-module projects with convention plugins

If you already have convention plugins, create a dedicated Dokka convention plugin following Gradle's documentation.

Then, follow the steps to set up the Dokka convention plugin and apply it across your modules.

Update documentation aggregation in multi-module projects

Dokka can aggregate the documentation from multiple modules (subprojects) into a single output or publication.

As explained, you must apply the Dokka plugin to all documentable subprojects before aggregating the documentation.

Aggregation in DGP v2 now uses the dependencies {} block instead of tasks, and can be added in any build.gradle.kts file.

In DGP v1, aggregation was implicitly created in the root project. To replicate this behavior in DGP v2, add the dependencies {} block in the build.gradle.kts file of the root project.

Previous aggregation:

tasks.dokkaHtmlMultiModule {
  // ...
}

New aggregation:

dependencies {
    dokka(project(":some-subproject:"))
    dokka(project(":another-subproject:"))
}

Generate documentation with the updated task

DGP v2 has renamed the Gradle tasks that generate the API documentation.

Previous task:

./gradlew dokkaHtml
    
// OR

./gradlew dokkaHtmlMultiModule

New task:

./gradlew :dokkaGenerate

The dokkaGenerate task generates the API documentation in the build/dokka/ directory.

In the new version, the dokkaGenerate task name works for both single and multi-module projects. You can use different tasks to generate output in HTML, Javadoc or both HTML and Javadoc. For more information, see the next section.

Select documentation output format

The default output format for DGP v2 is HTML. However, you can choose to generate the API documentation in HTML, Javadoc, or both formats at the same time:

Place the corresponding plugin id in the plugins{} block of your project's build.gradle.kts file:
plugins { // Generates HTML documentation id("org.jetbrains.dokka") version "2.0.0-Beta" // Generates Javadoc documentation id("org.jetbrains.dokka-javadoc") version "2.0.0-Beta" // Keeping both plugin IDs generates both formats }
Run the corresponding Gradle task.

Here's a list of the plugin id and Gradle task that correspond to each format:

	HTML	Javadoc	Both
Plugin `id`	`id("org.jetbrains.dokka")`	`id("org.jetbrains.dokka-javadoc")`	Use both HTML and Javadoc plugins
Gradle task	`./gradlew :dokkaGenerateHtml`	`./gradlew :dokkaGenerateJavadoc`	`./gradlew :dokkaGenerate`

Address deprecations and removals

Output format support: Dokka 2.0.0-Beta only supports HTML and Javadoc output. Experimental formats like Markdown and Jekyll are no longer supported.
Collector task: DokkaCollectorTask has been removed. Now, you need to generate the documentation separately for each subproject and then aggregate the documentation if necessary.

Finish up your migration

After you've migrated your project, perform these steps to wrap up and improve performance.

Set the opt-in flag

After successful migration, set the following opt-in flag without helpers in the project's gradle.properties file:

org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled

If you removed references to Gradle tasks from DGP v1 that are no longer available in DGP v2, you shouldn't see compilation errors related to it.

Enable build cache and configuration cache

DGP v2 now supports Gradle build cache and configuration cache, improving build performance.

To enable build cache, follow instructions in the Gradle build cache documentation.
To enable configuration cache, follow instructions in the Gradle configuration cache documentation.

What's next

最终更新: 2024/11/17