Kotlin 语言参考文档 中文版 Help

Dokka Plugin

Dokka 的设计思想是易于扩展, 而且高度可定制化, 因此对于 Dokka 缺少的, 或者没有默认提供的细节功能, 社区开发者可以实现 plugin.

Dokka plugin 的范围很广, 包括支持其他编程语言的源代码, 到支持各种输出格式. 你可以对你自己的 KDoc tag 或注解添加支持, 教会 Dokka 如何输出 KDoc 描述中出现的各种的 DSL, 对 Dokka 页面的外观重新设计, 使其无缝的集成到你的公司的网站, 将 Dokka 与其他工具集成, 等等等等.

如果你想要学习如何 创建 Dokka plugin, 请参见 开发者指南.

应用 Dokka plugin

Dokka plugin 作为单独的 artifact 发布, 因此要应用一个 Dokka plugin, 你只需要将它添加为依赖项. 之后, plugin 会自行扩展 Dokka - 不需要你再进行更多工作.

我们来看看在你的项目中如何应用 mathjax plugin:

Gradle plugin for Dokka 会创建便利的依赖项配置, 你可以对全局应用 plugin, 或只对特定的输出格式应用 plugin.

dependencies { // 对全局应用 dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:1.9.20") // 只对单模块的 dokkaHtml task 应用 dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.20") // 对多项目构建中的 HTML 格式应用 dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.9.20") }

Gradle plugin for Dokka 会创建便利的依赖项配置, 你可以对全局应用 plugin, 或只对特定的输出格式应用 plugin.

dependencies { // 对全局应用 dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin:1.9.20' // 只对单模块的 dokkaHtml task 应用 dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:1.9.20' // 对多项目构建中的 HTML 格式应用 dokkaHtmlPartialPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:1.9.20' }
<plugin> <groupId>org.jetbrains.dokka</groupId> <artifactId>dokka-maven-plugin</artifactId> ... <configuration> <dokkaPlugins> <plugin> <groupId>org.jetbrains.dokka</groupId> <artifactId>mathjax-plugin</artifactId> <version>1.9.20</version> </plugin> </dokkaPlugins> </configuration> </plugin>

如果你使用 CLI 运行器的 命令行选项 模式, Dokka plugin 应该以 .jar 文件的方式传递给 -pluginsClasspath:

java -jar dokka-cli-1.9.20.jar \ -pluginsClasspath "./dokka-base-1.9.20.jar;...;./mathjax-plugin-1.9.20.jar" \ ...

如果你使用 JSON 配置 模式, Dokka plugin 应该在 pluginsClasspath 之下指定.

{ ... "pluginsClasspath": [ "./dokka-base-1.9.20.jar", "...", "./mathjax-plugin-1.9.20.jar" ], ... }

配置 Dokka plugin

Dokka plugin 也可以带有它们自己的配置选项. 要查看有哪些选项可以使用, 请参考你使用的 plugin 的文档.

我们来看看如何配置 DokkaBase plugin, 它负责生成 HTML 文档. 我们向 assets 添加自定义的图片(使用 customAssets 选项), 添加自定义的样式表 (使用 customStyleSheets 选项), 修改页脚文字 (使用 footerMessage 选项):

Gradle 的 Kotlin DSL 可以使用类型安全的 plugin 配置. 做法是, 在 buildscript 代码段, 向 classpath 依赖项添加 plugin 的 artifact, 然后导入 plugin 和配置的类:

import org.jetbrains.dokka.base.DokkaBase import org.jetbrains.dokka.gradle.DokkaTask import org.jetbrains.dokka.base.DokkaBaseConfiguration buildscript { dependencies { classpath("org.jetbrains.dokka:dokka-base:1.9.20") } } tasks.withType<DokkaTask>().configureEach { pluginConfiguration<DokkaBase, DokkaBaseConfiguration> { customAssets = listOf(file("my-image.png")) customStyleSheets = listOf(file("my-styles.css")) footerMessage = "(c) 2022 MyOrg" } }

另一种方法是, plugin 可以通过 JSON 进行配置. 通过这种方法, 不需要添加额外的依赖项.

import org.jetbrains.dokka.gradle.DokkaTask tasks.withType<DokkaTask>().configureEach { val dokkaBaseConfiguration = """ { "customAssets": ["${file("assets/my-image.png")}"], "customStyleSheets": ["${file("assets/my-styles.css")}"], "footerMessage": "(c) 2022 MyOrg" } """ pluginsMapConfiguration.set( mapOf( // plugin 的完整限定名称, to, json 配置 "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration ) ) }
import org.jetbrains.dokka.gradle.DokkaTask tasks.withType(DokkaTask.class) { String dokkaBaseConfiguration = """ { "customAssets": ["${file("assets/my-image.png")}"], "customStyleSheets": ["${file("assets/my-styles.css")}"], "footerMessage": "(c) 2022 MyOrg" } """ pluginsMapConfiguration.set( // plugin 的完整限定名称, :, json 配置 ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] ) }
<plugin> <groupId>org.jetbrains.dokka</groupId> <artifactId>dokka-maven-plugin</artifactId> ... <configuration> <pluginsConfiguration> <!-- plugin 的完整限定名称 --> <org.jetbrains.dokka.base.DokkaBase> <!-- 选项名称 --> <customAssets> <asset>${project.basedir}/my-image.png</asset> </customAssets> <customStyleSheets> <stylesheet>${project.basedir}/my-styles.css</stylesheet> </customStyleSheets> <footerMessage>(c) MyOrg 2022 Maven</footerMessage> </org.jetbrains.dokka.base.DokkaBase> </pluginsConfiguration> </configuration> </plugin>

如果你使用 CLI 运行器的 命令行选项 模式, 请使用 -pluginsConfiguration 选项来接受 JSON 配置, 选项值的格式是 fullyQualifiedPluginName=json.

如果你需要配置多个 plugin, 你可以传递多个值, 以 ^^ 分隔.

java -jar dokka-cli-1.9.20.jar \ ... -pluginsConfiguration "org.jetbrains.dokka.base.DokkaBase={\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg CLI\"}"

如果你使用 JSON 配置, 也有类似的 pluginsConfiguration 数组, 在它的 values 中接受 JSON 配置.

{ "moduleName": "Dokka Example", "pluginsConfiguration": [ { "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", "serializationFormat": "JSON", "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\"}" } ] }

重要的 plugin

下面是一些重要的 Dokka plugin, 可能对你有用:

名称

描述

Android documentation plugin

改善 Android 上的文档体验

Versioning plugin

添加版本选择器, 帮助组织你的应用程序/库的多个不同版本的文档

MermaidJS HTML plugin

输出 KDocs 中出现的 MermaidJS 图和视觉效果

Mathjax HTML plugin

美化输出 KDocs 中出现的数学公式

Kotlin as Java plugin

以 Java 视角输出 Kotlin 签名

如果你是 Dokka plugin 的开发者, 希望将你的 plugin 添加到这个列表, 请通过 SlackGitHub 联系维护者.

最终更新: 2024/10/17