Gradle

本指南适用于 Dokka Gradle 插件 (DGP) v2 模式。之前的 DGP v1 模式已不再受支持。如果您正从 v1 模式升级到 v2 模式，请参阅迁移指南。

要为基于 Gradle 的项目生成文档，您可以使用 Dokka Gradle 插件。

Dokka Gradle 插件 (DGP) 为您的项目提供基本的自动配置，包含用于生成文档的 Gradle 任务，并提供配置选项来自定义输出。

您可以在我们的 Gradle 示例项目中尝试使用 Dokka 并探索如何为各种项目进行配置。

支持的版本

确保您的项目符合最低版本要求：

工具	版本
Gradle	7.6 或更高版本
Android Gradle 插件	7.0 或更高版本
Kotlin Gradle 插件	1.9 或更高版本

应用 Dokka

推荐应用 Dokka Gradle 插件的方式是使用 plugins 块。将其添加到项目 build.gradle.kts 文件的 plugins {} 块中：

Gradle Kotlin DSLGradle Groovy DSL

kotlin

plugins {
    id("org.jetbrains.dokka") version "2.1.0"
}

groovy

plugins {
    id 'org.jetbrains.dokka' version '2.1.0'
}

在为多项目构建编写文档时，您需要将该插件显式应用到每个想要生成文档的子项目。您可以直接在每个子项目中配置 Dokka，也可以使用约定插件在子项目之间共享 Dokka 配置。有关更多信息，请参阅如何配置单项目和多项目构建。

在底层，Dokka 使用 Kotlin Gradle 插件来自动配置为其生成文档的源集。请确保应用了 Kotlin Gradle 插件或手动配置源集。
如果您在预编译脚本插件中使用 Dokka，请将 Kotlin Gradle 插件添加为依赖项以确保其正常工作。

启用构建缓存和配置缓存

DGP 支持 Gradle 构建缓存和配置缓存，可提高构建性能。

要启用构建缓存，请按照 Gradle 构建缓存文档中的说明进行操作。
要启用配置缓存，请按照 Gradle 配置缓存文档中的说明进行操作。

生成文档

Dokka Gradle 插件内置了 HTML 和 Javadoc 输出格式。

使用以下 Gradle 任务生成文档：

shell

./gradlew :dokkaGenerate

dokkaGenerate Gradle 任务的关键行为是：

此任务为单项目和多项目构建生成文档。
默认情况下，文档输出格式为 HTML。您还可以通过添加相应的插件来生成 Javadoc 格式，或者同时生成 HTML 和 Javadoc 格式。
对于单项目和多项目构建，生成的文档都会自动放置在 build/dokka/html 目录中。您可以更改位置 (outputDirectory)。

配置文档输出格式

Javadoc 输出格式处于 Alpha 阶段。在使用时，您可能会遇到错误和迁移问题。不保证能够成功集成到接受 Javadoc 作为输入的工具中。风险自担。

您可以选择以 HTML、Javadoc 或同时以这两种格式生成 API 文档：

将相应的插件 id 放入项目 build.gradle.kts 文件的 plugins {} 块中：

kotlin

plugins {
    // 生成 HTML 文档
    id("org.jetbrains.dokka") version "2.1.0"

    // 生成 Javadoc 文档
    id("org.jetbrains.dokka-javadoc") version "2.1.0"

    // 同时保留两个插件 ID 会生成两种格式
}

运行相应的 Gradle 任务。

以下是每种格式对应的插件 id 和 Gradle 任务列表：

	HTML	Javadoc	两者
插件 `id`	`id("org.jetbrains.dokka")`	`id("org.jetbrains.dokka-javadoc")`	同时使用 HTML 和 Javadoc 插件
Gradle 任务	`./gradlew :dokkaGeneratePublicationHtml`	`./gradlew :dokkaGeneratePublicationJavadoc`	`./gradlew :dokkaGenerate`

dokkaGenerate 任务会根据应用的插件生成所有可用格式的文档。如果同时应用了 HTML 和 Javadoc 插件，您可以选择仅通过运行 dokkaGeneratePublicationHtml 任务生成 HTML，或仅通过运行 dokkaGeneratePublicationJavadoc 任务生成 Javadoc。

如果您使用的是 IntelliJ IDEA，您可能会看到 dokkaGenerateHtml Gradle 任务。此任务只是 dokkaGeneratePublicationHtml 的别名。两个任务执行的操作完全相同。

在多项目构建中聚合文档输出

Dokka 可以将来自多个子项目的文档聚合到一个输出或发布中。

在聚合文档之前，您必须将 Dokka 插件应用到所有可生成文档的子项目。

要聚合来自多个子项目的文档，请在根项目的 build.gradle.kts 文件中添加 dependencies {} 块：

kotlin

dependencies {
    dokka(project(":childProjectA:"))
    dokka(project(":childProjectB:"))
}

给定具有以下结构的项目：

text

.
└── parentProject/
    ├── childProjectA/
    │   └── demo/
    │       └── ChildProjectAClass.kt
    └── childProjectB/
        └── demo/
            └── ChildProjectBClass.kt

生成的文档按如下方式聚合：

dokkaHtmlMultiModule 任务输出的屏幕截图

有关更多详细信息，请参阅我们的多项目示例。

聚合文档的目录

当 DGP 聚合子项目时，每个子项目在聚合文档中都有自己的子目录。DGP 通过保留完整的项目结构来确保每个子项目都有一个唯一的目录。

例如，给定一个在 :turbo-lib 中进行聚合且包含嵌套子项目 :turbo-lib:maths 的项目，生成的文档将放置在：

text

turbo-lib/build/dokka/html/turbo-lib/maths/

您可以通过手动指定子项目目录来还原此行为。将以下配置添加到每个子项目的 build.gradle.kts 文件中：

kotlin

// /turbo-lib/maths/build.gradle.kts

plugins {
    id("org.jetbrains.dokka")
}

dokka {
    // 覆盖子项目目录
    modulePath.set("maths")
}

此配置将 :turbo-lib:maths 模块生成的文档更改为生成到 turbo-lib/build/dokka/html/maths/ 中。

构建 javadoc.jar

如果您想将库发布到仓库，您可能需要提供一个包含库 API 参考文档的 javadoc.jar 文件。

例如，如果您想发布到 Maven Central，您必须在项目旁边提供一个 javadoc.jar。但是，并非所有仓库都有该规则。

Dokka Gradle 插件没有提供任何开箱即用的方法来实现这一点，但可以通过自定义 Gradle 任务来实现。一个用于生成 HTML 格式的文档，另一个用于生成 Javadoc 格式：

Gradle Kotlin DSLGradle Groovy DSL

kotlin

// 生成 HTML 格式的文档
val dokkaHtmlJar by tasks.registering(Jar::class) {
    description = "A HTML Documentation JAR containing Dokka HTML"
    from(tasks.dokkaGeneratePublicationHtml.flatMap { it.outputDirectory })
    archiveClassifier.set("html-doc")
}

// 生成 Javadoc 格式的文档
val dokkaJavadocJar by tasks.registering(Jar::class) {
    description = "A Javadoc JAR containing Dokka Javadoc"
    from(tasks.dokkaGeneratePublicationJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}

groovy

// 生成 HTML 格式的文档
tasks.register('dokkaHtmlJar', Jar) {
    description = 'A HTML Documentation JAR containing Dokka HTML'
    from(tasks.named('dokkaGeneratePublicationHtml').flatMap { it.outputDirectory })
    archiveClassifier.set('html-doc')
}

// 生成 Javadoc 格式的文档
tasks.register('dokkaJavadocJar', Jar) {
    description = 'A Javadoc JAR containing Dokka Javadoc'
    from(tasks.named('dokkaGeneratePublicationJavadoc').flatMap { it.outputDirectory })
    archiveClassifier.set('javadoc')
}

如果您将库发布到 Maven Central，您可以使用 javadoc.io 等服务免费且无需任何设置地托管您的库 API 文档。它直接从 javadoc.jar 中获取文档页面。如此示例所示，它与 HTML 格式配合良好。

配置示例

根据您拥有的项目类型，应用和配置 Dokka 的方式略有不同。但是，无论项目类型如何，配置选项本身都是相同的。

对于在项目根目录中只有一个 build.gradle.kts 或 build.gradle 文件的简单扁平化项目，请参阅单项目配置。

对于具有子项目和多个嵌套 build.gradle.kts 或 build.gradle 文件的更复杂构建，请参阅多项目配置。

单项目配置

单项目构建通常在项目根目录中只有一个 build.gradle.kts 或 build.gradle 文件。它们可以是单平台或多平台的，通常具有以下结构：

KotlinGroovy

单平台：

text

.
├── build.gradle.kts
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

多平台：

text

.
├── build.gradle.kts
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

单平台：

text

.
├── build.gradle
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

多平台：

text

.
├── build.gradle
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

在根 build.gradle.kts 文件中应用 Dokka Gradle 插件，并使用顶级 dokka {} DSL 对其进行配置：

Gradle Kotlin DSLGradle Groovy DSL

kotlin

plugins {
    id("org.jetbrains.dokka") version "2.1.0"
}

dokka {
    dokkaPublications.html {
        moduleName.set("MyProject")
        outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
        includes.from("README.md")
   }

    dokkaSourceSets.main {
        sourceLink {
            localDirectory.set(file("src/main/kotlin"))
            remoteUrl.set(URI("https://github.com/your-repo"))
            remoteLineSuffix.set("#L")
        }
    }
}

在 ./build.gradle 内部：

groovy

plugins {
    id 'org.jetbrains.dokka' version '2.1.0'
}

dokka {
    dokkaPublications {
        html {
            moduleName.set("MyProject")
            outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
            includes.from("README.md")
        }
    }

    dokkaSourceSets {
        named("main") {
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://github.com/your-repo"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

此配置将 Dokka 应用于您的项目，设置文档输出目录，并定义主源集。您可以通过在同一个 dokka {} 块中添加自定义资源、可见性过滤器或插件配置来进一步扩展它。有关更多信息，请参阅配置选项。

多项目配置

多项目构建通常包含几个嵌套的 build.gradle.kts 文件，其结构类似于以下形式：

KotlinGroovy

text

.
├── build.gradle.kts
├── settings.gradle.kts
├── subproject-A/
│   ├── build.gradle.kts
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle.kts
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

text

.
├── build.gradle
├── settings.gradle
├── subproject-A/
│   ├── build.gradle
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

单项目和多项目文档共享相同的使用顶级 dokka {} DSL 的配置模型。

在多项目构建中配置 Dokka 有两种方式：

通过约定插件共享配置 (首选)：定义一个约定插件并将其应用到所有子项目。这会集中您的 Dokka 设置。
手动配置：应用 Dokka 插件并在每个子项目中重复相同的 dokka {} 块。您不需要约定插件。

配置完子项目后，您可以将来自多个子项目的文档聚合到一个输出中。有关更多信息，请参阅在多项目构建中聚合文档输出。

有关多项目示例，请参阅 Dokka GitHub 仓库。

通过约定插件共享配置

按照以下步骤设置约定插件并将其应用到您的子项目。

设置 buildSrc 目录

在项目根目录中，创建一个包含两个文件的 buildSrc 目录：
- settings.gradle.kts
- build.gradle.kts
在 buildSrc/settings.gradle.kts 文件中，添加以下代码段：
kotlin
```
rootProject.name = "buildSrc"
```

在 buildSrc/build.gradle.kts 文件中，添加以下代码段：

kotlin

plugins {
    `kotlin-dsl`
}

repositories {
    mavenCentral()
    gradlePluginPortal()
}

dependencies {
    implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.1.0")
}

设置 Dokka 约定插件

设置好 buildSrc 目录后，设置 Dokka 约定插件：

创建一个 buildSrc/src/main/kotlin/dokka-convention.gradle.kts 文件来托管约定插件。
在 dokka-convention.gradle.kts 文件中，添加以下代码段：
kotlin
```
plugins {
    id("org.jetbrains.dokka") 
}

dokka {
    // 共享配置放在这里
}
```
您需要在 dokka {} 块中添加所有子项目共有的共享 Dokka 配置。此外，您无需指定 Dokka 版本。版本已在 buildSrc/build.gradle.kts 文件中设置。

将约定插件应用到您的子项目

通过将 Dokka 约定插件添加到每个子项目的 build.gradle.kts 文件中，将其应用到您的子项目：

kotlin

plugins {
    id("dokka-convention")
}

手动配置

如果您的项目不使用约定插件，您可以通过手动将相同的 dokka {} 块复制到每个子项目中来重复使用相同的 Dokka 配置模式：

在每个子项目的 build.gradle.kts 文件中应用 Dokka 插件：
kotlin
```
plugins {
    id("org.jetbrains.dokka") version "2.1.0"
}
```
在每个子项目的 dokka {} 块中声明共享配置。由于没有集中配置的约定插件，您需要在各个子项目中重复所需的任何配置。有关更多信息，请参阅配置选项。

父项目配置

在多项目构建中，您可以在根项目中配置适用于整个文档的设置。这可以包括定义输出格式、输出目录、文档子项目名称、从所有子项目聚合文档以及其他配置选项：

kotlin

plugins {
    id("org.jetbrains.dokka") version "2.1.0"
}

dokka {
    // 为整个项目设置属性
    dokkaPublications.html {
        moduleName.set("My Project")
        outputDirectory.set(layout.buildDirectory.dir("docs/html"))
        includes.from("README.md")
    }

    dokkaSourceSets.configureEach {
        documentedVisibilities.set(setOf(VisibilityModifier.Public)) // 或者 documentedVisibilities(VisibilityModifier.Public)    
    }
}

// 聚合子项目文档
dependencies {
    dokka(project(":childProjectA"))
    dokka(project(":childProjectB"))
}

此外，如果每个子项目需要自定义配置，它们可以拥有自己的 dokka {} 块。在以下示例中，子项目应用了 Dokka 插件，设置了自定义子项目名称，并包含了来自其 README.md 文件的附加文档：

kotlin

// subproject/build.gradle.kts
plugins {
    id("org.jetbrains.dokka")
}

dokka {
    dokkaPublications.html {
        moduleName.set("Child Project A")
        includes.from("README.md")
    }
}

运行 Dokka

输出格式

检索

操作与操作符

Gradle ​

支持的版本 ​

应用 Dokka ​

启用构建缓存和配置缓存 ​

生成文档 ​

配置文档输出格式 ​

在多项目构建中聚合文档输出 ​

聚合文档的目录 ​

构建 javadoc.jar ​

配置示例 ​

单项目配置 ​

多项目配置 ​

通过约定插件共享配置 ​

设置 buildSrc 目录 ​

设置 Dokka 约定插件 ​

将约定插件应用到您的子项目 ​

手动配置 ​

父项目配置 ​

Gradle

支持的版本

应用 Dokka

启用构建缓存和配置缓存

生成文档

配置文档输出格式

在多项目构建中聚合文档输出

聚合文档的目录

构建 javadoc.jar

配置示例

单项目配置

多项目配置

通过约定插件共享配置

设置 buildSrc 目录

设置 Dokka 约定插件

将约定插件应用到您的子项目

手动配置

父项目配置