Dokkaプラグイン
このガイドは Dokka Gradle プラグイン(DGP)v2 モードに適用されます。DGP v1 モードはサポートが終了しました。 v1 から v2 モードにアップグレードするには、マイグレーションガイドに従ってください。
Dokka は、簡単に拡張でき、高度にカスタマイズできるようにゼロから構築されています。これにより、標準では提供されていない不足している機能や、非常に特殊な要件のためのプラグインをコミュニティが実装できます。
Dokka プラグインの対象範囲は、他のプログラミング言語のソースサポートから珍しい出力フォーマットまで多岐にわたります。独自の KDoc タグやアノテーションのサポートを追加したり、KDoc の記述に含まれるさまざまな DSL をレンダリングする方法を Dokka に教えたり、組織の Web サイトにシームレスに統合できるように Dokka のページを視覚的に再設計したり、他のツールと連携させたりなど、さまざまなことが可能です。
Dokka プラグインの作成方法を学びたい場合は、開発者ガイドを参照してください。
Dokkaプラグインの適用
Dokka プラグインは個別のアーティファクトとして公開されているため、Dokka プラグインを適用するには依存関係として追加するだけです。その後はプラグイン自身によって Dokka が拡張されるため、それ以上のアクションは必要ありません。
同じ拡張ポイントを使用したり、同様の方法で動作したりするプラグイン同士は、互いに干渉し合う可能性があります。 これにより、視覚的なバグ、一般的な予期しない動作、あるいはビルドの失敗につながるおそれがあります。ただし、Dokka は変更可能なデータ構造やオブジェクトを公開していないため、並行性の問題にはつながりません。
このような問題に気づいた場合は、どのプラグインが適用されていて、それらが何を行っているかを確認することをお勧めします。
プロジェクトに mathjax プラグイン を適用する方法を見てみましょう。
plugins {
id("org.jetbrains.dokka") version "2.2.0"
}
dependencies {
dokkaPlugin("org.jetbrains.dokka:mathjax-plugin")
}組み込みプラグイン(HTML や Javadoc など)は常に自動的に適用されます。設定を行うだけでよく、それらに対する依存関係を宣言する必要はありません。
マルチモジュールプロジェクト(マルチプロジェクトビルド)のドキュメントを生成する場合は、サブプロジェクト間で Dokka の設定とプラグインを共有する必要があります。
plugins {
id 'org.jetbrains.dokka' version '2.2.0'
}
dependencies {
dokkaPlugin 'org.jetbrains.dokka:mathjax-plugin'
}マルチプロジェクト ビルドのドキュメントを生成する場合は、サブプロジェクト間で 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.2.0</version>
</plugin>
</dokkaPlugins>
</configuration>
</plugin>CLI ランナーを コマンドラインオプション で使用している場合、Dokka プラグインは .jar ファイルとして -pluginsClasspath に渡す必要があります。
java -jar dokka-cli-2.2.0.jar \
-pluginsClasspath "./dokka-base-2.2.0.jar;...;./mathjax-plugin-2.2.0.jar" \
...JSON 設定 を使用している場合、Dokka プラグインは pluginsClasspath の下に指定する必要があります。
{
...
"pluginsClasspath": [
"./dokka-base-2.2.0.jar",
"...",
"./mathjax-plugin-2.2.0.jar"
],
...
}Dokkaプラグインの設定
Dokka プラグインは、それぞれ独自の設定オプションを持つこともできます。利用可能なオプションを確認するには、使用しているプラグインのドキュメントを参照してください。
組み込みの HTML プラグインを設定する例として、アセットへのカスタム画像の追加(customAssets オプション)、カスタムスタイルシートの追加(customStyleSheets オプション)、変更されたフッターメッセージ(footerMessage オプション)を設定する方法を見てみましょう。
Dokka プラグインをタイプセーフな方法で設定するには、dokka.pluginsConfiguration {} ブロックを使用します。
dokka {
pluginsConfiguration.html {
customAssets.from("logo.png")
customStyleSheets.from("styles.css")
footerMessage.set("(c) Your Company")
}
}Dokka プラグインの設定例については、Dokka のバージョニングプラグイン を参照してください。
Dokka では、カスタムプラグインの設定 を行うことで、機能を拡張し、ドキュメント生成プロセスを変更できます。
dokka {
pluginsConfiguration {
html {
customAssets.from("logo.png")
customStyleSheets.from("styles.css")
footerMessage.set("(c) Your Company")
}
}
}<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.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 設定を受け付けます。
{
"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 内の数式を綺麗に整形して表示(pretty print)します |
| Kotlin as Java plugin | Java から見た視点で Kotlin のシグネチャをレンダリングします |
| GFM plugin | GitHub Flavored Markdown 形式でドキュメントを生成する機能を追加します |
| Jekyll plugin | Jekyll Flavored Markdown 形式でドキュメントを生成する機能を追加します |
Dokka プラグインの作者の方で、このリストに自身のプラグインを追加したい場合は、Slack または GitHub 経由でメンテナーにお問い合わせください。
