Dokka Gradle 配置选项

Dokka 有很多配置选项, 可以自定义你和读者的体验.

下面是每个配置部分的详细说明, 以及一些示例. 你也可以找到一个使用了所有配置选项的示例.

关于在单项目和多项目构建中应用配置代码块, 详情请参见配置示例.

一般配置

下面是 Dokka Gradle plugin 一般配置的示例:

使用顶层的 dokka {} DSL 配置.
在 DGP 中, 可以在 dokkaPublications{} 代码块中声明 Dokka 的发布配置.
默认发布格式为 html 和 javadoc.
build.gradle.kts 文件的语法与通常的 .kt 文件 (例如用于 Kotlin 自定义 plugin 的文件) 不同, 因为 Gradle 的 Kotlin DSL 使用类型安全的访问器.

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

dokka {
    dokkaPublications.html {
        moduleName.set(project.name)
        moduleVersion.set(project.version.toString())
        // HTML 文档的标准输出目录
        outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
        failOnWarning.set(false)
        suppressInheritedMembers.set(false)
        suppressObviousFunctions.set(true)
        offlineMode.set(false)
        includes.from("packages.md", "extra.md")

        // 附加文件的输出目录
        // 当你想要修改输出目录, 并包含附加文件时,
        // 请使用这个代码块替代标准的配置
        outputDirectory.set(rootDir.resolve("docs/api/0.x"))

        // 使用 fileTree 添加多个文件
        includes.from(
            fileTree("docs") {
                include("**/*.md")
            }
        )
    }
}

关于处理文件, 详情请参见 Gradle 文档.

// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")

        project.extensions.configure(DokkaExtension::class.java) { dokka ->

            dokka.moduleName.set(project.name)
            dokka.moduleVersion.set(project.version.toString())

            dokka.dokkaPublications.named("html") { publication ->
                // HTML 文档的标准输出目录
                publication.outputDirectory.set(project.layout.buildDirectory.dir("dokka/html"))
                publication.failOnWarning.set(true)
                publication.suppressInheritedMembers.set(true)
                publication.offlineMode.set(false)
                publication.suppressObviousFunctions.set(true)
                publication.includes.from("packages.md", "extra.md")

                // 附加文件的输出目录
                // 当你想要修改输出目录, 并包含附加文件时,
                // 请使用这个代码块替代标准的配置
                html.outputDirectory.set(project.rootDir.resolve("docs/api/0.x"))
            }
        }
    }
}

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

dokka {
    dokkaPublications {
        html {
            // 设置模块的一般信息
            moduleName.set(project.name)
            moduleVersion.set(project.version.toString())

            // HTML 文档的标准输出目录
            outputDirectory.set(layout.buildDirectory.dir("dokka/html"))

            // Dokka 核心选项
            failOnWarning.set(false)
            suppressInheritedMembers.set(false)
            suppressObviousFunctions.set(true)
            offlineMode.set(false)
            includes.from(files("packages.md", "extra.md"))

            // 附加文件的输出目录
            // 当你想要修改输出目录, 并包含附加文件时,
            // 请使用这个代码块替代标准的配置
            outputDirectory.set(file("$rootDir/docs/api/0.x"))
        }
    }
}

moduleName

项目文档的显示名称. 这个名称会用于目录, 导航, 标题和日志消息中. 在多项目构建中, 每个子项目的 moduleName 在聚合文档中用作其章节标题.

默认值: Gradle 项目名称

moduleVersion

在生成的文档中显示的子项目版本. 在单项目构建中, 它用作项目版本. 在多项目构建中, 聚合文档时会使用每个子项目的 moduleVersion.

默认值: Gradle 项目版本

outputDirectory

生成文档的存储目录.

这个设置适用于 dokkaGenerate task 生成的所有文档格式 (HTML, Javadoc 等等).

默认值: build/dokka/html

附加文件的输出目录

你可以为单项目构建和多项目构建指定输出目录, 并包含附加文件. 对于多项目构建, 请在根项目的配置中设置输出目录, 并包含附加文件.

failOnWarning

决定 Dokka 在文档生成过程中出现警告时, 是否应该使构建失败. 进程首先会等待所有的错误和警告输出完毕.

这个设置可以与 reportUndocumented 选项配合工作.

默认值: false

suppressInheritedMembers

是否禁止输出在指定的类中继承得到的而且没有显式覆盖的成员.

注意: 这个选项可以禁止输出 equals, hashCode, toString 之类的函数, 但不能禁止输出 dataClass.componentN 和 dataClass.copy 之类合成函数. 对于合成函数, 请使用 suppressObviousFunctions 选项.

默认值: false

suppressObviousFunctions

是否禁止输出那些显而易见的函数.

满足以下条件的函数, 会被认为是显而易见的函数:

继承自 kotlin.Any, Kotlin.Enum, java.lang.Object 或 java.lang.Enum, 例如 equals, hashCode, toString.
合成(由编译器生成的)函数, 而且没有任何文档, 例如 dataClass.componentN 或 dataClass.copy.

默认值: true

offlineMode

是否通过你的网络来解析远程的文件和链接.

包括用来生成外部文档链接的包列表. 例如, 可以让来自标准库的类成为文档中可以点击的链接.

将这个设置为 true, 某些情况下可以显著提高构建速度, 但也会降低用户体验. 例如, 可能无法解析来自你的依赖项的类和成员的链接, 包括标准库.

注意: 你可以将已取得的文件缓存到本地, 并通过本地路径提供给 Dokka. 请参见 externalDocumentationLinks 部分.

默认值: false

includes

包含子项目和包文档的 Markdown 文件列表. 这些 Markdown 文件必须符合需要的格式.

指定的文件的内容会被解析, 并嵌入到文档内, 作为子项目和包的描述文档.

请参见 Dokka Gradle 示例, 了解它的样子以及使用方法.

源代码集配置

Dokka 可以为 Kotlin 源代码集配置一些选项:

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    // ...
    // 一般配置部分
    // ...

    // 源代码集配置
    dokkaSourceSets {
        // 示例: 专用于 'linux' 源代码集的配置
        named("linux") {
            dependentSourceSets{named("native")}
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(VisibilityModifier.Public)) // 或者 documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                // 源代码链接部分
            }
            perPackageOption {
                // 包选项部分
            }
            externalDocumentationLinks {
                // 外部文档链接部分
            }
        }
    }
}

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    // ...
    // 一般配置部分
    // ...

    // 源代码集配置
    dokkaSourceSets {
        // 示例: 专用于 'linux' 源代码集的配置
        named("linux") {
            dependentSourceSets { named("native") }
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([VisibilityModifier.Public] as Set) // 或者 documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                // 源代码链接部分
            }
            perPackageOption {
                // 包选项部分
            }
            externalDocumentationLinks {
                // 外部文档链接部分
            }
        }
    }
}

suppress

生成文档时, 是否应该跳过这个源代码集.

默认值: false

displayName

用来引用这个源代码集的显示名称.

这个名称在外部用途使用(例如, 源代码集名称会显示给文档读者), 也在内部使用(例如, 用于 reportUndocumented 的日志信息).

默认情况下, 这个值根据 Kotlin Gradle plugin 提供的信息推断得到.

documentedVisibilities

定义 Dokka 应该在生成的文档中包含哪些可见度修饰符.

如果你想要对 protected, internal 和 private 声明生成文档, 以及如果你想要排除 public 声明, 只为 internal API 生成文档, 请使用这个选项.

此外, 你还可以使用 Dokka 的 documentedVisibilities() 函数来添加需要生成文档的可见度.

这个选项可以为每个单独的包配置.

默认值: VisibilityModifier.Public

reportUndocumented

是否对可见的, 无文档的声明输出警告, 这是指经过 documentedVisibilities 和其他过滤器过滤之后, 需要输出文档, 但没有 KDocs 的声明.

这个设置可以与 failOnWarning 选项配合工作.

这个选项可以为每个单独的包配置.

默认值: false

skipEmptyPackages

是否跳过经各种过滤器过滤之后不包含可见声明的包.

例如, 如果 skipDeprecated 设置为 true, 而且你的包中只包含已废弃的声明, 那么这个包会被认为是空的.

默认值: true

skipDeprecated

是否对标注了 @Deprecated 注解的声明生成文档.

这个选项可以为每个单独的包配置.

默认值: false

suppressGeneratedFiles

是否对生成的文件生成文档.

生成的文件预期存在于 {project}/{buildDir}/generated 目录下.

如果设置为 true, 效果等于将这个目录中的所有文件添加到 suppressedFiles 选项中, 然后你可以手动配置它.

默认值: true

suppressAnnotatedWith

注解的完全限定名称 (Fully Qualified Name, FQN) 列表, 用来压制带有这些注解的声明.

对于带有这些注解之一的任何声明, 都不会生成文档.

jdkVersion

在为 Java 类型生成外部文档链接时使用的 JDK 版本.

例如, 如果你在某些 public 声明的签名中使用了 java.util.UUID, 而且这个选项设置为 8, Dokka 会为它生成一个指向 JDK 8 Javadocs 的外部文档链接.

默认值: `8`

languageVersion

设置代码分析和 @sample 环境时使用的 Kotlin 语言版本.

默认情况下, 会使用 Dokka 的内嵌编译器所能够使用的最新的语言版本.

apiVersion

设置代码分析和 @sample 环境时使用的 Kotlin API 版本.

默认情况下, 从 languageVersion 推断得到.

sourceRoots

需要分析并生成文档的源代码根目录. 允许的输入是目录和单独的 .kt 和 .java 文件.

默认情况下, 源代码根目录根据 Kotlin Gradle plugin 提供的信息推断得到.

classpath

用于代码分析和交互式示例的类路径.

如果来自依赖项的某些类型无法自动的解析/查找, 这个选项会很有用.

这个选项可以接受 .jar 和 .klib 文件.

默认情况下, 类路径根据 Kotlin Gradle plugin 提供的信息推断得到.

samples

目录或文件的列表, 其中包含通过 @sample KDoc 标签引用的示例函数.

源代码链接配置

配置源代码链接, 帮助读者在远程仓库中找到每个声明的源代码. 请使用 dokkaSourceSets.main {} 代码块进行这个配置.

sourceLinks {} 配置代码块可以为每个签名添加一个 source 链接, 指向带有特定行号的 remoteUrl. 行号可以通过设置 remoteLineSuffix 来配置.

相关的示例请参见 kotlinx.coroutines 中 count() 函数的文档.

build.gradle.kts 文件的语法与通常的 .kt 文件 (例如用于自定义 Gradle plugin 的文件) 不同, 因为 Gradle 的 Kotlin DSL 使用类型安全的访问器:

// build.gradle.kts

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

// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")
        project.extensions.configure(DokkaExtension::class.java) { dokka ->
            dokka.dokkaSourceSets.named("main") { dss ->
                dss.includes.from("README.md")
                dss.sourceLink {
                    it.localDirectory.set(project.file("src/main/kotlin"))
                    it.remoteUrl("https://example.com/src")
                    it.remoteLineSuffix.set("#L")
                }
            }
        }
    }
}

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

localDirectory

本地源代码目录的路径. 必须是从当前项目根目录开始的相对路径.

remoteUrl

可以由文档读者访问的源代码托管服务 URL, 例如 GitHub, GitLab, Bitbucket, 或任何为源文件提供稳定 URL 的托管服务. 这个 URL 用来生成声明的源代码链接.

remoteLineSuffix

向 URL 添加的源代码行数后缀. 这样可以帮助读者, 不仅能够导航到文件, 而且是声明所在的确定的行数.

行数本身会添加到后缀之后. 例如, 如果这个选项设置为 #L, 行数是 10, 那么最后的的 URL 后缀会是#L10.

各种常用的源代码托管服务的行数后缀是:

GitHub: #L
GitLab: #L
Bitbucket: #lines-

默认值: #L

包选项

perPackageOption 配置代码块, 可以对指定的包设置一些选项, 包通过 matchingRegex 来匹配:

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    dokkaPublications.html {
        dokkaSourceSets.configureEach {
            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(setOf(VisibilityModifier.Public)) // 或者 documentedVisibilities(VisibilityModifier.Public)
            }
        }
    }
}

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    dokkaPublications {
        html {
            dokkaSourceSets.configureEach {
                perPackageOption {
                    matchingRegex.set(".*api.*")
                    suppress.set(false)
                    skipDeprecated.set(false)
                    reportUndocumented.set(false)
                    documentedVisibilities.set([VisibilityModifier.Public] as Set)
                }
            }
        }
    }
}

matchingRegex

用来匹配包的正规表达式.

默认值: .*

suppress

在生成文档时, 是否应该跳过这个包.

默认值: false

skipDeprecated

是否对标注了 @Deprecated 注解的声明生成文档.

这个选项可以在源代码集级配置.

默认值: false

reportUndocumented

是否对可见的, 无文档的声明输出警告, 这是指经过 documentedVisibilities 和其他过滤器过滤之后, 需要输出文档, 但没有 KDocs 的声明.

这个设置与 failOnWarning 选项配合工作.

这个选项可以在源代码集级配置.

默认值: false

documentedVisibilities

定义 Dokka 应该在生成的文档中包含哪些可见度修饰符.

如果你想要对这个包内的 protected, internal 和 private 声明生成文档, 以及如果你想要排除 public 声明, 只为 internal API 生成文档, 请使用这个选项.

此外, 你还可以使用 Dokka 的 documentedVisibilities() 函数来添加需要生成文档的可见度.

这个选项可以在源代码集级配置.

默认值: VisibilityModifier.Public

外部文档链接配置

externalDocumentationLinks {} 代码块可以创建链接, 指向你的依赖项的外部文档.

例如, 如果你使用来自 kotlinx.serialization 的类型, 默认情况下它们在你的文档中是不可点击的, 就像未解析的一样. 但是, 由于 kotlinx.serialization 的 API 参考文档是由 Dokka 构建的, 并且发布在 kotlinlang.org 上, 因此你可以为它配置外部文档链接. 这样, Dokka 可以为来自这个库的类型生成链接, 使它们能够成功解析, 并且可以点击.

默认情况下, 已配置了对 Kotlin 标准库, JDK, Android SDK, 以及 AndroidX 的外部文档链接.

请使用 register() 方法, 注册外部文档链接, 来定义每个链接. externalDocumentationLinks API 使用这个方法, 与 Gradle DSL 规范保持一致:

dokka {
    dokkaSourceSets.configureEach {
        externalDocumentationLinks.register("example-docs") {
            url("https://example.com/docs/")
            packageListUrl("https://example.com/docs/package-list")
        }
    }
}

dokka {
    dokkaSourceSets.configureEach {
        externalDocumentationLinks.register("example-docs") {
            url.set(new URI("https://example.com/docs/"))
            packageListUrl.set(new URI("https://example.com/docs/package-list"))
        }
    }
}

url

链接到的文档的根 URL. 末尾必须包含斜线.

Dokka 会尽量对给定的 URL 自动寻找 package-list, 并将声明链接到一起.

如果自动解析失败, 或者如果你想要使用本地缓存的文件, 请考虑设置 packageListUrl 选项.

packageListUrl

package-list 的确切位置. 这是对 Dokka 自动解析的一个替代手段.

包列表包含关于文档和项目自身的信息, 例如子项目和包的名称.

也可以使用本地缓存的文件, 以避免发生网络访问.

完整的配置

下面是同时使用了所有配置选项的示例:

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

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

dokka {
    dokkaPublications.html {
        moduleName.set(project.name)
        moduleVersion.set(project.version.toString())
        outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
        failOnWarning.set(false)
        suppressInheritedMembers.set(false)
        suppressObviousFunctions.set(true)
        offlineMode.set(false)
        includes.from("packages.md", "extra.md")
   }

    dokkaSourceSets {
        // 示例: 专用于 'linux' 源代码集的配置
        named("linux") {
            dependentSourceSets{named("native")}
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(VisibilityModifier.Public)) // 或者 documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl("https://example.com/src")
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLinks {
                url = URL("https://example.com/docs/")
                packageListUrl = File("/path/to/package-list").toURI().toURL()
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(
                    setOf(
                        VisibilityModifier.Public,
                        VisibilityModifier.Private,
                        VisibilityModifier.Protected,
                        VisibilityModifier.Internal,
                        VisibilityModifier.Package
                    )
                )
            }
        }
    }
}

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

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

dokka {
    dokkaPublications {
        html {
            moduleName.set(project.name)
            moduleVersion.set(project.version.toString())
            outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
            failOnWarning.set(false)
            suppressInheritedMembers.set(false)
            suppressObviousFunctions.set(true)
            offlineMode.set(false)
            includes.from("packages.md", "extra.md")
        }
    }

    dokkaSourceSets {
        // 示例: 专用于 'linux' 源代码集的配置
        named("linux") {
            dependentSourceSets { named("native") }
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([VisibilityModifier.Public] as Set)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://example.com/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLinks {
                url.set(new URI("https://example.com/docs/"))
                packageListUrl.set(new File("/path/to/package-list").toURI().toURL())
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set([
                        VisibilityModifier.Public,
                        VisibilityModifier.Private,
                        VisibilityModifier.Protected,
                        VisibilityModifier.Internal,
                        VisibilityModifier.Package
                ] as Set)
            }
        }
    }
}

2026/08/12