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 也可以带有它们自己的配置选项. 要查看有哪些选项可以使用, 请参考你使用的 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, 可能对你有用:
如果你是 Dokka plugin 的开发者, 希望将你的 plugin 添加到这个列表, 请通过 Slack 或 GitHub 联系维护者.
最终更新: 2024/10/17