Skip to content

Dokka 插件 ​

本指南适用于 Dokka Gradle 插件 (DGP) v2 模式。DGP v1 模式已不再受支持。 要从 v1 升级到 v2 模式,请遵循迁移指南。

Dokka 从一开始就设计为易于扩展和高度可定制,这使得社区能够针对开箱即用未提供的缺失功能或非常特定的功能实现插件。

Dokka 插件的涵盖范围非常广泛,从支持其他编程语言源码到各种新奇的输出格式。你可以添加对自定义 KDoc 标记或注解的支持、让 Dokka 懂得如何渲染 KDoc 描述中出现的不同 DSL、在视觉上重新设计 Dokka 页面以无缝集成到公司的网站中,将其与其他工具集成,等等。

如果你想学习如何创建 Dokka 插件,请参阅开发者指南。

应用 Dokka 插件 ​

Dokka 插件作为单独的构件发布,因此要应用 Dokka 插件,你只需将其添加为依赖项即可。从这里开始,插件会自动扩展 Dokka——无需执行进一步的操作。

使用相同扩展点或以类似方式工作的插件可能会相互干扰。 这可能导致视觉错误、一般的未定义行为,甚至导致构建失败。但是,由于 Dokka 不会公开任何可变数据结构或对象,因此不会导致并发问题。

如果你发现类似问题,建议检查应用了哪些插件以及它们的作用。

我们来看看如何将 mathjax 插件应用到你的项目中:

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

dependencies {
    dokkaPlugin("org.jetbrains.dokka:mathjax-plugin")
}
  • 内置插件(如 HTML 和 Javadoc)始终会自动应用。你只需对其进行配置,无需声明对它们的依赖项。

  • 为多模块项目(多项目构建)生成文档时,你需要在子项目间共享 Dokka 配置和插件。

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

dependencies {
    dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin'
}

为多项目构建生成文档时,你需要在子项目间共享 Dokka 配置和插件。

xml
<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <dokkaPlugins>
            <plugin>
                <groupId>org.jetbrains.dokka</groupId>
                <artifactId>mathjax-plugin</artifactId>
                <version>2.2.0</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

如果使用带有命令行选项的 CLI 运行程序,Dokka 插件应作为 .jar 文件传递给 -pluginsClasspath:

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

如果使用 JSON 配置,Dokka 插件应在 pluginsClasspath 下指定。

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

配置 Dokka 插件 ​

Dokka 插件也可以拥有自己的配置选项。要查看有哪些可用选项,请查阅你正在使用的插件的文档。

我们来看看如何通过向资源中添加自定义图像(customAssets 选项)、自定义样式表(customStyleSheets 选项)以及修改后的页脚信息(footerMessage 选项)来配置内置的 HTML 插件:

要以类型安全的方式配置 Dokka 插件,请使用 dokka.pluginsConfiguration {} 块:

kotlin
dokka {
    pluginsConfiguration.html {
        customAssets.from("logo.png")
        customStyleSheets.from("styles.css")
        footerMessage.set("(c) Your Company")
    }
}

有关 Dokka 插件配置的示例,请参阅 Dokka 的版本控制插件。

Dokka 允许你通过配置自定义插件来扩展其功能并修改文档生成过程。

groovy
dokka {
    pluginsConfiguration {
        html {
            customAssets.from("logo.png")
            customStyleSheets.from("styles.css")
            footerMessage.set("(c) Your Company")
        }
    }
}
xml
<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <pluginsConfiguration>
            <!-- 完全限定插件名称 -->
            <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 选项,该选项接受形式为 fullyQualifiedPluginName=json 的 JSON 配置。

如果需要配置多个插件,可以传入以 ^^ 分隔的多个值。

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

如果你使用 JSON 配置,存在一个类似的 pluginsConfiguration 数组,它在 values 中接受 JSON 配置。

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\"}"
    }
  ]
}

值得关注的插件 ​

以下是一些你可能会觉得有用的 Dokka 插件:

名称描述
Android documentation plugin改善 Android 上的文档体验
Versioning plugin添加版本选择器,并帮助组织应用程序/库不同版本的文档
MermaidJS HTML plugin渲染在 KDoc 中找到的 MermaidJS 图表与可视化内容
Mathjax HTML plugin美化排版 KDoc 中出现的数学公式
Kotlin as Java plugin从 Java 视角渲染 Kotlin 签名
GFM plugin添加以 GitHub Flavored Markdown 格式生成文档的功能
Jekyll plugin添加以 Jekyll Flavored Markdown 格式生成文档的功能

如果你是 Dokka 插件作者,并且希望将你的插件添加到此列表中,请通过 Slack 或 GitHub 与维护者联系。