Gradle

应用 Dokka

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

要对多项目构建生成文档, 你还需要对子项目应用 Gradle plugin for Dokka. 你可以使用 Gradle 配置 allprojects {} 或 subprojects {} 来做到这一点:

subprojects {
    apply(plugin = "org.jetbrains.dokka")
}

生成文档

单项目构建

Task	描述
`dokkaHtml`	使用 HTML 格式生成文档.

实验性的格式

Task	描述
`dokkaGfm`	使用 GitHub 风格的 Markdown 格式生成文档.
`dokkaJavadoc`	使用 Javadoc 格式生成文档.
`dokkaJekyll`	使用 Jekyll 兼容的 Markdown 格式生成文档.

默认情况下, 生成的文档会输出到你的项目的 build/dokka/{format} 目录中. 输出位置, 以及其他很多设置, 都可以进行配置.

多项目构建

MultiModule task

MultiModule task 通过 Partial task 对每个子项目分别生成文档, 收集并处理所有的输出, 然后使用共同的目录和解析后的跨项目引用, 处理完整的文档.

Task	描述
`dokkaHtmlMultiModule`	使用 HTML 输出格式生成多模块文档.

实验性的格式 (MultiModule)

Task	描述
`dokkaGfmMultiModule`	使用 GitHub 风格的 Markdown 输出格式生成多模块文档.
`dokkaJekyllMultiModule`	使用 Jekyll 兼容的 Markdown 输出格式生成多模块文档.

默认情况下, 你可以在 {parentProject}/build/dokka/{format}MultiModule 目录中找到直接可用的文档.

MultiModule task 的输出结果

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

运行 dokkaHtmlMultiModule 后生成的文档如下:

Collector task 的输出结果

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

运行 dokkaHtmlCollector 之后会生成这样的页面:

构建 javadoc.jar

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

例如, 如果你想要发布到 Maven Central, 你必须和你的项目一起提供一个 javadoc.jar. 但是, 并不是所有的仓库都有这样的规则.

tasks.register<Jar>("dokkaHtmlJar") {
    dependsOn(tasks.dokkaHtml)
    from(tasks.dokkaHtml.flatMap { it.outputDirectory })
    archiveClassifier.set("html-docs")
}

tasks.register<Jar>("dokkaJavadocJar") {
    dependsOn(tasks.dokkaJavadoc)
    from(tasks.dokkaJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}

配置示例

对于简单的项目, 在项目的根目录下包含单个 build.gradle.kts 或 build.gradle 文件, 请参见单项目配置.

对更加复杂的构建, 包含子项目, 以及多个下级的 build.gradle.kts 或 build.gradle 文件, 请参见多项目配置.

单项目配置

单项目构建, 通常只在项目的根目录下存在单个 build.gradle.kts 或 build.gradle 文件, 其结构通常如下:

单平台项目:

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

跨平台项目:

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

在这样的项目中, 你需要在根目录的 build.gradle.kts 或 build.gradle 文件中应用 Dokka 及其配置.

在 ./build.gradle.kts 中:

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

tasks.dokkaHtml {
    outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
}

tasks.dokkaGfm {
    outputDirectory.set(layout.buildDirectory.dir("documentation/markdown"))
}

在 ./build.gradle.kts 中:

import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import org.jetbrains.dokka.DokkaConfiguration.Visibility

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

// 同时配置所有的单项目 Dokka task,
// 例如 dokkaHtml, dokkaJavadoc 和 dokkaGfm.
tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets.configureEach {
        documentedVisibilities.set(
            setOf(
                Visibility.PUBLIC,
                Visibility.PROTECTED,
            )
        )

        perPackageOption {
            matchingRegex.set(".*internal.*")
            suppress.set(true)
        }
    }
}

多项目配置

Gradle 的多项目构建的结构和配置都更加复杂. 这样的项目通常包含多个下级的 build.gradle.kts 或 build.gradle 文件, 其结构通常如下:

.
├── 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

子项目配置

你可以在根目录的 build.gradle.kts 或 build.gradle 文件中, 使用 Gradle 的 allprojects {} 或 subprojects {} 配置代码块, 同时配置所有的子项目:

在根目录的 ./build.gradle.kts 中:

import org.jetbrains.dokka.gradle.DokkaTaskPartial

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

subprojects {
    apply(plugin = "org.jetbrains.dokka")

    // 只配置 HTML task
    tasks.dokkaHtmlPartial {
        outputDirectory.set(layout.buildDirectory.dir("docs/partial"))
    }

    // 配置所有格式
    tasks.withType<DokkaTaskPartial>().configureEach {
        dokkaSourceSets.configureEach {
            includes.from("README.md")
        }
    }
}

例如, 为了只对 subproject-A 子项目进行特定的设置, 你需要在 ./subproject-A/build.gradle.kts 中使用以下代码:

在 ./subproject-A/build.gradle.kts 中:

apply(plugin = "org.jetbrains.dokka")

// 只配置 subproject-A.
tasks.dokkaHtmlPartial {
    outputDirectory.set(layout.buildDirectory.dir("docs/partial"))
}

父项目配置

例如, 如果你想要修改 HTML 文档标题中的项目名称, 你需要在根目录的 build.gradle.kts 或 build.gradle 文件中使用以下代码:

在根目录的 ./build.gradle.kts 文件中:

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

tasks.dokkaHtmlMultiModule {
    moduleName.set("在标题中使用的项目名称")
}

配置选项

一般配置

import org.jetbrains.dokka.gradle.DokkaTask

// 注意: 要配置多项目构建, 你需要配置子项目的 Partial task.
//      参见本文档的 "配置示例" 小节.
tasks.withType<DokkaTask>().configureEach {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(layout.buildDirectory.dir("dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    // ...
    // 参见本文档的 "源代码集配置" 小节
    // ...
}

源代码集配置

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// 注意: 要配置多项目构建, 你需要配置子项目的 Partial task.
//      参见本文档的 "配置示例" 小节.
tasks.withType<DokkaTask>().configureEach {
    // ...
    // 参见本文档的 "一般配置" 小节
    // ...

    dokkaSourceSets {
        // 专属于 'linux' 源代码集的配置
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(Visibility.PUBLIC))
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                // 参见本文档的 "源代码链接配置" 小节
            }
            externalDocumentationLink {
                // 参见本文档的 "外部文档链接配置" 小节
            }
            perPackageOption {
                // 参见本文档的 "包选项" 小节
            }
        }
    }
}

源代码链接配置

sourceLinks 配置块可以用来为每个签名添加 source 链接, 链接地址是带有特定代码行的 remoteUrl. (代码行可以通过 remoteLineSuffix 进行配置).

例如, 请参见 kotlinx.coroutines 中 count() 函数的文档.

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// 注意: 要配置多项目构建, 你需要配置子项目的 Partial task.
//      参见本文档的 "配置示例" 小节.
tasks.withType<DokkaTask>().configureEach {
    // ...
    // 参见本文档的 "一般配置" 小节
    // ...

    dokkaSourceSets.configureEach {
        // ...
        // 参见本文档的 "源代码集配置" 小节
        // ...

        sourceLink {
            localDirectory.set(projectDir.resolve("src"))
            remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src"))
            remoteLineSuffix.set("#L")
        }
    }
}

包选项

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

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask

// 注意: 要配置多项目构建, 你需要配置子项目的 Partial task.
//      参见本文档的 "配置示例" 小节.
tasks.withType<DokkaTask>().configureEach {
    // ...
    // 参见本文档的 "一般配置" 小节
    // ...

    dokkaSourceSets.configureEach {
        // ...
        // 参见本文档的 "源代码集配置" 小节
        // ...

        perPackageOption {
            matchingRegex.set(".*api.*")
            suppress.set(false)
            skipDeprecated.set(false)
            reportUndocumented.set(false)
            documentedVisibilities.set(setOf(Visibility.PUBLIC))
        }
    }
}

外部文档链接配置

externalDocumentationLink 配置块可以创建链接, 指向你的依赖项的外部文档.

例如, 如果你使用来自 kotlinx.serialization 的类型, 默认情况下, 在你的文档中这些类型不是可点击的链接, 因为无法解析这些类型. 但是, 由于 kotlinx.serialization 的 API 参考文档是使用 Dokka 构建的, 而且发布到了 kotlinlang.org, 因此你可以对它配置外部文档链接. 然后就可以让 Dokka 对来自这个库的类型生成链接, 让它们成功的解析, 并在文档中成为可点击的链接.

import org.jetbrains.dokka.gradle.DokkaTask
import java.net.URL

// 注意: 要配置多项目构建, 你需要配置子项目的 Partial task.
//      参见本文档的 "配置示例" 小节.
tasks.withType<DokkaTask>().configureEach {
    // ...
    // 参见本文档的 "一般配置" 小节
    // ...

    dokkaSourceSets.configureEach {
        // ...
        // 参见本文档的 "源代码集配置" 小节
        // ...

        externalDocumentationLink {
            url.set(URL("https://kotlinlang.org/api/kotlinx.serialization/"))
            packageListUrl.set(
                rootProject.projectDir.resolve("serialization.package.list").toURL()
            )
        }
    }
}

完整的配置

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// 注意: 要配置多项目构建, 你需要配置子项目的 Partial task.
//      参见本文档的 "配置示例" 小节.
tasks.withType<DokkaTask>().configureEach {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(layout.buildDirectory.dir("dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    dokkaSourceSets {
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(Visibility.PUBLIC))
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(projectDir.resolve("src"))
                remoteUrl.set(URL("https://github.com/kotlin/dokka/tree/master/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLink {
                url.set(URL("https://kotlinlang.org/api/core/kotlin-stdlib/"))
                packageListUrl.set(
                    rootProject.projectDir.resolve("stdlib.package.list").toURL()
                )
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(
                    setOf(
                        Visibility.PUBLIC,
                        Visibility.PRIVATE,
                        Visibility.PROTECTED,
                        Visibility.INTERNAL,
                        Visibility.PACKAGE
                    )
                )
            }
        }
    }
}

import org.jetbrains.dokka.DokkaConfiguration.Visibility
import org.jetbrains.dokka.gradle.DokkaTask
import org.jetbrains.dokka.Platform
import java.net.URL

// 注意: 要配置多项目构建, 你需要配置子项目的 Partial task.
//      参见本文档的 "配置示例" 小节.
tasks.withType(DokkaTask.class) {
    moduleName.set(project.name)
    moduleVersion.set(project.version.toString())
    outputDirectory.set(file("build/dokka/$name"))
    failOnWarning.set(false)
    suppressObviousFunctions.set(true)
    suppressInheritedMembers.set(false)
    offlineMode.set(false)

    dokkaSourceSets {
        named("linux") {
            dependsOn("native")
            sourceRoots.from(file("linux/src"))
        }
        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([Visibility.PUBLIC])
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            noStdlibLink.set(false)
            noJdkLink.set(false)
            noAndroidSdkLink.set(false)
            includes.from(project.files(), "packages.md", "extra.md")
            platform.set(Platform.DEFAULT)
            sourceRoots.from(file("src"))
            classpath.from(project.files(), file("libs/dependency.jar"))
            samples.from(project.files(), "samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src"))
                remoteUrl.set(new URL("https://github.com/kotlin/dokka/tree/master/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLink {
                url.set(new URL("https://kotlinlang.org/api/core/kotlin-stdlib/"))
                packageListUrl.set(
                        file("stdlib.package.list").toURL()
                )
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set([Visibility.PUBLIC])
            }
        }
    }
}

Gradle﻿

应用 Dokka﻿

note

note

生成文档﻿

单项目构建﻿

实验性的格式﻿

多项目构建﻿

MultiModule task﻿

实验性的格式 (MultiModule)﻿

note

MultiModule task 的输出结果﻿

Collector task﻿

tip

Collector task 的输出结果﻿

Partial task﻿

warning

note

构建 javadoc.jar﻿

tip

配置示例﻿

单项目配置﻿

多项目配置﻿

子项目配置﻿

父项目配置﻿

配置选项﻿

一般配置﻿

源代码集配置﻿

源代码链接配置﻿

包选项﻿

外部文档链接配置﻿

完整的配置﻿

Gradle

应用 Dokka

生成文档

单项目构建

实验性的格式

多项目构建

MultiModule task

实验性的格式 (MultiModule)

MultiModule task 的输出结果

Collector task

Collector task 的输出结果

Partial task

构建 javadoc.jar

配置示例

单项目配置

多项目配置

子项目配置

父项目配置

配置选项

一般配置

源代码集配置

源代码链接配置

包选项

外部文档链接配置

完整的配置