Dokkaプラグイン

Dokkaは、最初から簡単に拡張でき、高度にカスタマイズできるように構築されています。これにより、コミュニティは標準では提供されていない機能や、非常に特定の機能のためのプラグインを実装できます。

Dokkaプラグインは、他のプログラミング言語のソースのサポートから、珍しい出力形式まで多岐にわたります。独自のKDocタグやアノテーションのサポートを追加したり、KDocの説明に含まれるさまざまなDSLのレンダリング方法をDokkaに教えたり、会社のウェブサイトにシームレスに統合されるようにDokkaのページを視覚的に再設計したり、他のツールと統合したり、その他にも多くのことができます。

Dokkaプラグインの作成方法を学びたい場合は、開発者ガイドを参照してください。

Dokkaプラグインを適用する

Dokkaプラグインは別個のアーティファクトとして公開されているため、Dokkaプラグインを適用するには、それを依存関係として追加するだけです。そこから、プラグイン自体がDokkaを拡張します — それ以上の操作は不要です。

NOTE

同じ拡張ポイントを使用するプラグインや、同様の方法で動作するプラグインは、互いに干渉する可能性があります。

これは、視覚的なバグ、一般的な未定義の動作、さらにはビルドの失敗につながる可能性があります。ただし、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プラグインは、独自の構成オプションを持つこともできます。どのオプションが利用可能かを確認するには、使用しているプラグインのドキュメントを参照してください。

HTMLドキュメントの生成を担当するDokkaBaseプラグインを、アセットへのカスタム画像の追加（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	KDoc内に見つかるMermaidJSの図や視覚化をレンダリングします
Mathjax HTML plugin	KDoc内に見つかる数式をきれいに整形して表示します
Kotlin as Java plugin	Javaの視点から見たKotlinのシグネチャをレンダリングします

Dokkaプラグインの作者で、このリストにプラグインを追加したい場合は、SlackまたはGitHubを通じてメンテナーに連絡してください。