Dokkaプラグイン

Dokkaは、拡張が容易で高度にカスタマイズ可能であるようにゼロから構築されており、コミュニティが標準で提供されていない不足機能や非常に特定の機能のためのプラグインを実装することを可能にします。

Dokkaプラグインは、他のプログラミング言語ソースのサポートから、珍しい出力フォーマットまで多岐にわたります。独自のKDocタグやアノテーションのサポートを追加したり、KDocの説明に見られる異なるDSLをDokkaにレンダリングさせたり、Dokkaのページを視覚的に再設計して会社のウェブサイトにシームレスに統合したり、他のツールと統合したりと、できることは他にもたくさんあります。

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

Dokkaプラグインの適用

Dokkaプラグインは個別の成果物として公開されているため、Dokkaプラグインを適用するには、それを依存関係として追加するだけで済みます。そこから、プラグインはDokkaをそれ自体で拡張します — それ以上の操作は不要です。

同じ拡張ポイントを使用する、または同様の方法で機能するプラグインは、互いに干渉する可能性があります。これにより、視覚的なバグ、一般的な未定義の動作、さらにはビルドの失敗につながる可能性があります。ただし、Dokkaは可変のデータ構造やオブジェクトを公開していないため、同時実行性の問題にはつながりません。

このような問題に気づいた場合は、どのプラグインが適用されており、それらが何をするのかを確認することをお勧めします。

プロジェクトにmathjaxプラグインを適用する方法を見てみましょう。

KotlinGroovyMavenCLI

Dokka用Gradleプラグインは、プラグインを全体的に適用するか、特定の出力形式のみに適用することを可能にする便利な依存関係構成を作成します。

dependencies {
    // 全体的に適用されます
    dokkaPlugin("org.jetbrains.dokka:mathjax-plugin:2.0.0")

    // シングルモジュールのdokkaHtmlタスクにのみ適用されます
    dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:2.0.0")

    // マルチプロジェクトビルドのHTML形式に適用されます
    dokkaHtmlPartialPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:2.0.0")
}

マルチプロジェクトビルドをドキュメント化する場合、サブプロジェクト内およびその親プロジェクトでもDokkaプラグインを適用する必要があります。

Dokka用Gradleプラグインは、Dokkaプラグインを全体的に適用するか、特定の出力形式のみに適用することを可能にする便利な依存関係構成を作成します。

dependencies {
    // 全体的に適用されます
    dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin:2.0.0'

    // シングルモジュールのdokkaHtmlタスクにのみ適用されます
    dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:2.0.0'

    // マルチプロジェクトビルドのHTML形式に適用されます
    dokkaHtmlPartialPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:2.0.0'
}

マルチプロジェクトビルドをドキュメント化する場合、サブプロジェクト内およびその親プロジェクトでもDokkaプラグインを適用する必要があります。

<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ランナーをコマンドラインオプションで使用している場合、Dokkaプラグインは.jarファイルとして-pluginsClasspathに渡す必要があります。

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

JSON設定を使用している場合、DokkaプラグインはpluginsClasspathの下に指定する必要があります。

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

Dokkaプラグインの設定

Dokkaプラグインは独自の構成オプションを持つこともできます。利用可能なオプションを確認するには、使用しているプラグインのドキュメントを参照してください。

HTMLドキュメントの生成を担当するDokkaBaseプラグインを、アセットへのカスタム画像の追加 (customAssetsオプション)、カスタムスタイルシートの追加 (customStyleSheetsオプション)、フッターメッセージの変更 (footerMessageオプション) によって設定する方法を見てみましょう。

KotlinGroovyMavenCLI

GradleのKotlin DSLでは、タイプセーフなプラグイン設定が可能です。これは、プラグインの成果物をbuildscriptブロック内のクラスパス依存関係に追加し、その後プラグインと構成クラスをインポートすることで実現できます。

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

または、プラグインは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(
            // 完全修飾プラグイン名から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(
            // 完全修飾プラグイン名からJSON設定へ
            ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
    )
}

<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ランナーをコマンドラインオプションで使用している場合、fullyQualifiedPluginName=jsonの形式でJSON設定を受け入れる-pluginsConfigurationオプションを使用します。

複数のプラグインを設定する必要がある場合は、^^で区切られた複数の値を渡すことができます。

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

JSON設定を使用している場合、valuesでJSON設定を受け入れる同様のpluginsConfiguration配列が存在します。

{
  "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	KDocs内のMermaidJS図と視覚化をレンダリングします
Mathjax HTML plugin	KDocs内の数式をきれいに整形して表示します
Kotlin as Java plugin	Javaの視点から見たKotlinのシグネチャをレンダリングします

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