Dokka 插件

Dokka 从零开始构建，旨在易于扩展且高度可定制，这使得社区能够为那些缺失或非常特定的、未直接提供的功能实现插件。

Dokka 插件的功能范围广泛，从支持其他编程语言源文件到异构输出格式。您可以为自己的 KDoc 标签或注解添加支持，教 Dokka 如何渲染 KDoc 描述中发现的不同 DSL，从视觉上重新设计 Dokka 的页面以无缝集成到您公司的网站，将其与其他工具集成等等。

如果您想了解如何创建 Dokka 插件，请参阅 开发者指南。

应用 Dokka 插件

Dokka 插件作为独立的构建产物 (artifacts) 发布，因此要应用 Dokka 插件，您只需将其添加为依赖项即可。此后，插件将自行扩展 Dokka，无需进一步操作。

NOTE

使用相同扩展点或以类似方式工作的插件可能会相互干扰。

这可能导致视觉 Bug、一般未定义行为甚至构建失败。然而，由于 Dokka 不会暴露任何可变数据结构或对象，因此不应导致并发问题。

如果您发现此类问题，最好检查已应用了哪些插件以及它们的作用。

让我们看看如何在您的项目中应用 mathjax 插件：

Kotlin

dependencies {
    // Is applied universally
    dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:2.0.0")

    // Is applied for the single-module dokkaHtml task only
    dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:2.0.0")

    // Is applied for HTML format in multi-project builds
    dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:2.0.0")
}

Groovy

dependencies {
    // Is applied universally
    dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin:2.0.0'

    // Is applied for the single-module dokkaHtml task only
    dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:2.0.0'

    // Is applied for HTML format in multi-project builds
    dokkaHtmlPartialPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:2.0.0'
}

Maven

<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.0.0</version>
            </plugin>
        </dokkaPlugins>
    </configuration>
</plugin>

CLI

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

配置 Dokka 插件

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

让我们看看如何配置 DokkaBase 插件，该插件负责生成 HTML 文档，通过向资产 (customAssets 选项) 添加自定义图片，通过添加自定义样式表 (customStyleSheets 选项)，以及通过修改页脚消息 (footerMessage 选项)：

Kotlin

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:2.0.0")
    }
}

tasks.withType<DokkaTask>().configureEach {
    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
        customAssets = listOf(file("my-image.png"))
        customStyleSheets = listOf(file("my-styles.css"))
        footerMessage = "(c) 2022 MyOrg"
    }
}

Groovy

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(
            // fully qualified plugin name to json configuration
            ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
    )
}

Maven

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    ...
    <configuration>
        <pluginsConfiguration>
            <!-- Fully qualified plugin name -->
            <org.jetbrains.dokka.base.DokkaBase>
                <!-- Options by name -->
                <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

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

值得注意的插件

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

名称	描述
Android documentation plugin	提升 Android 上的文档体验
Versioning plugin	添加版本选择器并帮助组织应用程序/库不同版本的文档
MermaidJS HTML plugin	渲染 KDocs 中发现的 MermaidJS 图表和可视化内容
Mathjax HTML plugin	优美地打印 KDocs 中的数学公式
Kotlin as Java plugin	渲染从 Java 视角看到的 Kotlin 签名

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