Gradle

このガイドは Dokka Gradle プラグイン (DGP) v2 モードに適用されます。以前の DGP v1 モードはサポートされなくなりました。 v1 から v2 モードにアップグレードする場合は、移行ガイド (Migration guide) を参照してください。

Gradle ベースのプロジェクトのドキュメントを生成するには、Dokka 用の Gradle プラグインを使用できます。

Dokka Gradle プラグイン (DGP) には、プロジェクト用の基本的な自動構成が含まれており、ドキュメント生成用の Gradle タスクが含まれています。また、出力をカスタマイズするための構成オプションも提供されています。

Dokka を試したり、さまざまなプロジェクトでの構成方法を確認したりするには、Gradle サンプルプロジェクトを探索してください。

サポートされているバージョン

プロジェクトが以下の最小バージョン要件を満たしていることを確認してください。

ツール	バージョン
Gradle	7.6 以上
Android Gradle プラグイン	7.0 以上
Kotlin Gradle プラグイン	1.9 以上

Dokka の適用

Dokka Gradle プラグインを適用する推奨される方法は、plugins ブロックを使用することです。プロジェクトの build.gradle.kts ファイルの plugins {} ブロックに以下を追加します。

Gradle Kotlin DSLGradle Groovy DSL

kotlin

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

groovy

plugins {
    id 'org.jetbrains.dokka' version '2.1.0'
}

マルチプロジェクトビルドをドキュメント化する場合、ドキュメント化したいすべてのサブプロジェクトにプラグインを明示的に適用する必要があります。各サブプロジェクトで直接 Dokka を構成することも、コンベンションプラグインを使用してサブプロジェクト間で Dokka の構成を共有することもできます。詳細については、シングルプロジェクト構成およびマルチプロジェクト構成の方法を参照してください。

内部的には、Dokka は Kotlin Gradle プラグインを使用して、ドキュメントが生成されるソースセット (source sets) を自動的に構成します。Kotlin Gradle プラグインを適用するか、ソースセットを手動で構成してください。
プリコンパイル済みスクリプトプラグイン (precompiled script plugin) で Dokka を使用している場合は、Kotlin Gradle プラグインを依存関係として追加し、正しく動作することを確認してください。

ビルドキャッシュと構成キャッシュの有効化

DGP は Gradle のビルドキャッシュ (build cache) と構成キャッシュ (configuration cache) をサポートしており、ビルドのパフォーマンスが向上します。

ビルドキャッシュを有効にするには、Gradle ビルドキャッシュのドキュメントの指示に従ってください。
構成キャッシュを有効にするには、Gradle 構成キャッシュのドキュメントの指示に従ってください。

ドキュメントの生成

Dokka Gradle プラグインには、HTML および Javadoc の出力形式が組み込まれています。

ドキュメントを生成するには、以下の Gradle タスクを使用します。

shell

./gradlew :dokkaGenerate

dokkaGenerate Gradle タスクの主な動作は以下の通りです。

このタスクは、シングルプロジェクトおよびマルチプロジェクトビルドの両方でドキュメントを生成します。
デフォルトでは、ドキュメントの出力形式は HTML です。適切なプラグインを追加することで、Javadoc を生成したり、HTML と Javadoc の両方の形式を生成したりすることもできます。
生成されたドキュメントは、シングルプロジェクトおよびマルチプロジェクトビルドの両方で、自動的に build/dokka/html ディレクトリに配置されます。場所 (outputDirectory) を変更することも可能です。

ドキュメントの出力形式の構成

Javadoc 出力形式はアルファ版 (Alpha) です。使用中にバグが発生したり、移行の問題が発生したりする可能性があります。 Javadoc を入力として受け入れるツールとの正常な統合は保証されません。自己責任で使用してください。

API ドキュメントを HTML、Javadoc、またはその両方の形式で同時に生成するように選択できます。

プロジェクトの build.gradle.kts ファイルの plugins {} ブロックに対応するプラグイン id を配置します。

kotlin

plugins {
    // HTML ドキュメントを生成
    id("org.jetbrains.dokka") version "2.1.0"

    // Javadoc ドキュメントを生成
    id("org.jetbrains.dokka-javadoc") version "2.1.0"

    // 両方のプラグイン ID を保持すると、両方の形式が生成されます
}

対応する Gradle タスクを実行します。

各形式に対応するプラグイン id と Gradle タスクのリストは以下の通りです。

	HTML	Javadoc	両方
プラグイン `id`	`id("org.jetbrains.dokka")`	`id("org.jetbrains.dokka-javadoc")`	HTML と Javadoc 両方のプラグインを使用
Gradle タスク	`./gradlew :dokkaGeneratePublicationHtml`	`./gradlew :dokkaGeneratePublicationJavadoc`	`./gradlew :dokkaGenerate`

dokkaGenerate タスクは、適用されているプラグインに基づいて、利用可能なすべての形式でドキュメントを生成します。 HTML と Javadoc の両方のプラグインが適用されている場合、dokkaGeneratePublicationHtml タスクを実行して HTML のみを生成するか、dokkaGeneratePublicationJavadoc タスクを実行して Javadoc のみを生成するかを選択できます。

IntelliJ IDEA を使用している場合、dokkaGenerateHtml という Gradle タスクが表示されることがあります。このタスクは単に dokkaGeneratePublicationHtml のエイリアスです。両方のタスクはまったく同じ操作を実行します。

マルチプロジェクトビルドでのドキュメント出力の集約

Dokka は、複数のサブプロジェクトからのドキュメントを単一の出力またはパブリケーションに集約 (aggregate) できます。

ドキュメントを集約する前に、ドキュメント化可能なすべてのサブプロジェクトに Dokka プラグインを適用する必要があります。

複数のサブプロジェクトからドキュメントを集約するには、ルートプロジェクトの build.gradle.kts ファイルに dependencies {} ブロックを追加します。

kotlin

dependencies {
    dokka(project(":childProjectA:"))
    dokka(project(":childProjectB:"))
}

次のような構造のプロジェクトを想定します。

text

.
└── parentProject/
    ├── childProjectA/
    │   └── demo/
    │       └── ChildProjectAClass.kt
    └── childProjectB/
        └── demo/
            └── ChildProjectBClass.kt

生成されたドキュメントは次のように集約されます。

dokkaHtmlMultiModule タスクの出力のスクリーンショット

詳細については、マルチプロジェクトのサンプルを参照してください。

集約されたドキュメントのディレクトリ

DGP がサブプロジェクトを集約すると、各サブプロジェクトは集約されたドキュメント内に独自のサブディレクトリを持ちます。 DGP は、完全なプロジェクト構造を維持することで、各サブプロジェクトがユニークなディレクトリを持つようにします。

例えば、:turbo-lib に集約があり、ネストされたサブプロジェクト :turbo-lib:maths があるプロジェクトの場合、生成されたドキュメントは以下の場所に配置されます。

text

turbo-lib/build/dokka/html/turbo-lib/maths/

サブプロジェクトのディレクトリを手動で指定することで、この動作を変更できます。各サブプロジェクトの build.gradle.kts ファイルに以下の構成を追加します。

kotlin

// /turbo-lib/maths/build.gradle.kts

plugins {
    id("org.jetbrains.dokka")
}

dokka {
    // サブプロジェクトのディレクトリをオーバーライド
    modulePath.set("maths")
}

この構成により、:turbo-lib:maths モジュールの生成されたドキュメントは turbo-lib/build/dokka/html/maths/ に生成されるようになります。

javadoc.jar のビルド

ライブラリをリポジトリに公開する場合、ライブラリの API リファレンスドキュメントを含む javadoc.jar ファイルを提供する必要がある場合があります。

例えば、Maven Central に公開する場合、プロジェクトと一緒に javadoc.jar を提供する必要があります。ただし、すべてのリポジトリにそのルールがあるわけではありません。

Dokka Gradle プラグインは、これをそのまま行う方法は提供していませんが、カスタムの Gradle タスクで実現できます。1 つは HTML 形式でドキュメントを生成するためのもの、もう 1 つは Javadoc 形式のためのものです。

Gradle Kotlin DSLGradle Groovy DSL

kotlin

// HTML でドキュメントを生成する場合
val dokkaHtmlJar by tasks.registering(Jar::class) {
    description = "A HTML Documentation JAR containing Dokka HTML"
    from(tasks.dokkaGeneratePublicationHtml.flatMap { it.outputDirectory })
    archiveClassifier.set("html-doc")
}

// Javadoc でドキュメントを生成する場合
val dokkaJavadocJar by tasks.registering(Jar::class) {
    description = "A Javadoc JAR containing Dokka Javadoc"
    from(tasks.dokkaGeneratePublicationJavadoc.flatMap { it.outputDirectory })
    archiveClassifier.set("javadoc")
}

groovy

// HTML でドキュメントを生成する場合
tasks.register('dokkaHtmlJar', Jar) {
    description = 'A HTML Documentation JAR containing Dokka HTML'
    from(tasks.named('dokkaGeneratePublicationHtml').flatMap { it.outputDirectory })
    archiveClassifier.set('html-doc')
}

// Javadoc でドキュメントを生成する場合
tasks.register('dokkaJavadocJar', Jar) {
    description = 'A Javadoc JAR containing Dokka Javadoc'
    from(tasks.named('dokkaGeneratePublicationJavadoc').flatMap { it.outputDirectory })
    archiveClassifier.set('javadoc')
}

ライブラリを Maven Central に公開する場合、javadoc.io のようなサービスを使用して、ライブラリの API ドキュメントを無料で、セットアップなしでホストできます。このサービスは javadoc.jar から直接ドキュメントページを取得します。この例に示されているように、HTML 形式でもうまく機能します。

構成例

お使いのプロジェクトの種類によって、Dokka の適用方法と構成方法が若干異なります。ただし、構成オプション自体はプロジェクトの種類に関係なく同じです。

プロジェクトのルートにある単一の build.gradle.kts または build.gradle ファイルを持つ、シンプルでフラットなプロジェクトについては、シングルプロジェクト構成を参照してください。

サブプロジェクトや複数のネストされた build.gradle.kts または build.gradle ファイルを持つ、より複雑なビルドについては、マルチプロジェクト構成を参照してください。

シングルプロジェクト構成

シングルプロジェクトビルドには、通常、プロジェクトのルートに build.gradle.kts または build.gradle ファイルが 1 つだけあります。これらはシングルプラットフォームまたはマルチプラットフォームのいずれかであり、通常は次のような構造をしています。

KotlinGroovy

シングルプラットフォーム:

text

.
├── build.gradle.kts
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

マルチプラットフォーム:

text

.
├── build.gradle.kts
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

シングルプラットフォーム:

text

.
├── build.gradle
└── src/
    └── main/
        └── kotlin/
            └── HelloWorld.kt

マルチプラットフォーム:

text

.
├── build.gradle
└── src/
    ├── commonMain/
    │   └── kotlin/
    │       └── Common.kt
    ├── jvmMain/
    │   └── kotlin/
    │       └── JvmUtils.kt
    └── nativeMain/
        └── kotlin/
            └── NativeUtils.kt

ルートの build.gradle.kts ファイルで Dokka Gradle プラグインを適用し、トップレベルの dokka {} DSL を使用して構成します。

Gradle Kotlin DSLGradle Groovy DSL

kotlin

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

dokka {
    dokkaPublications.html {
        moduleName.set("MyProject")
        outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
        includes.from("README.md")
   }

    dokkaSourceSets.main {
        sourceLink {
            localDirectory.set(file("src/main/kotlin"))
            remoteUrl.set(URI("https://github.com/your-repo"))
            remoteLineSuffix.set("#L")
        }
    }
}

./build.gradle 内:

groovy

plugins {
    id 'org.jetbrains.dokka' version '2.1.0'
}

dokka {
    dokkaPublications {
        html {
            moduleName.set("MyProject")
            outputDirectory.set(layout.buildDirectory.dir("documentation/html"))
            includes.from("README.md")
        }
    }

    dokkaSourceSets {
        named("main") {
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://github.com/your-repo"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

この構成により、プロジェクトに Dokka が適用され、ドキュメントの出力ディレクトリが設定され、メインのソースセットが定義されます。同じ dokka {} ブロック内でカスタムアセット、可視性フィルタ、またはプラグイン構成を追加することで、さらに拡張できます。詳細については、構成オプションを参照してください。

マルチプロジェクト構成

マルチプロジェクトビルドには、通常、複数のネストされた build.gradle.kts ファイルが含まれ、次のような構造になります。

KotlinGroovy

text

.
├── build.gradle.kts
├── settings.gradle.kts
├── subproject-A/
│   ├── build.gradle.kts
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle.kts
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

text

.
├── build.gradle
├── settings.gradle
├── subproject-A/
│   ├── build.gradle
│   └── src/
│       └── main/
│           └── kotlin/
│               └── HelloFromA.kt
└── subproject-B/
    ├── build.gradle
    └── src/
        └── main/
            └── kotlin/
                └── HelloFromB.kt

シングルプロジェクトとマルチプロジェクトのドキュメントは、同じトップレベル dokka {} DSL を使用した構成モデルを共有します。

マルチプロジェクトビルドで Dokka を構成するには、2 つの方法があります。

コンベンションプラグインを介した共有構成 (推奨): コンベンションプラグインを定義し、それをすべてのサブプロジェクトに適用します。これにより、Dokka の設定が集中管理されます。
手動構成: 各サブプロジェクトで Dokka プラグインを適用し、同じ dokka {} ブロックを繰り返します。コンベンションプラグインは必要ありません。

サブプロジェクトを構成した後、複数のサブプロジェクトからのドキュメントを単一の出力に集約できます。詳細については、マルチプロジェクトビルドでのドキュメント出力の集約を参照してください。

マルチプロジェクトの例については、Dokka の GitHub リポジトリを参照してください。

コンベンションプラグインを介した共有構成

以下の手順に従って、コンベンションプラグインをセットアップし、サブプロジェクトに適用します。

buildSrc ディレクトリをセットアップする

プロジェクトルートに、次の 2 つのファイルを含む buildSrc ディレクトリを作成します。
- settings.gradle.kts
- build.gradle.kts
buildSrc/settings.gradle.kts ファイルに、以下のスニペットを追加します。
kotlin
```
rootProject.name = "buildSrc"
```

buildSrc/build.gradle.kts ファイルに、以下のスニペットを追加します。

kotlin

plugins {
    `kotlin-dsl`
}

repositories {
    mavenCentral()
    gradlePluginPortal()
}

dependencies {
    implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.1.0")
}

Dokka コンベンションプラグインをセットアップする

buildSrc ディレクトリをセットアップした後、Dokka コンベンションプラグインをセットアップします。

コンベンションプラグインをホストするために buildSrc/src/main/kotlin/dokka-convention.gradle.kts ファイルを作成します。
dokka-convention.gradle.kts ファイルに、以下のスニペットを追加します。
kotlin
```
plugins {
    id("org.jetbrains.dokka") 
}

dokka {
    // 共有構成をここに記述します
}
```
dokka {} ブロック内に、すべてのサブプロジェクトに共通する共有の Dokka 構成を追加する必要があります。また、Dokka のバージョンを指定する必要はありません。バージョンはすでに buildSrc/build.gradle.kts ファイルで設定されています。

コンベンションプラグインをサブプロジェクトに適用する

各サブプロジェクトの build.gradle.kts ファイルに追加することで、サブプロジェクト全体に Dokka コンベンションプラグインを適用します。

kotlin

plugins {
    id("dokka-convention")
}

手動構成

プロジェクトでコンベンションプラグインを使用していない場合は、同じ dokka {} ブロックを各サブプロジェクトに手動でコピーすることで、同じ Dokka 構成パターンを再利用できます。

すべてのサブプロジェクトの build.gradle.kts ファイルで Dokka プラグインを適用します。
kotlin
```
plugins {
    id("org.jetbrains.dokka") version "2.1.0"
}
```
各サブプロジェクトの dokka {} ブロックで共有構成を宣言します。構成を集中管理するコンベンションプラグインがないため、サブプロジェクト間で必要な構成を複製します。詳細については、構成オプションを参照してください。

親プロジェクトの構成

マルチプロジェクトビルドでは、ルートプロジェクトでドキュメント全体に適用される設定を構成できます。これには、出力形式の定義、出力ディレクトリ、ドキュメントのサブプロジェクト名、すべてのサブプロジェクトからのドキュメントの集約、およびその他の構成オプションが含まれます。

kotlin

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

dokka {
    // プロジェクト全体にプロパティを設定します
    dokkaPublications.html {
        moduleName.set("My Project")
        outputDirectory.set(layout.buildDirectory.dir("docs/html"))
        includes.from("README.md")
    }

    dokkaSourceSets.configureEach {
        documentedVisibilities.set(setOf(VisibilityModifier.Public)) // または documentedVisibilities(VisibilityModifier.Public)    
    }
}

// サブプロジェクトのドキュメントを集約
dependencies {
    dokka(project(":childProjectA"))
    dokka(project(":childProjectB"))
}

さらに、カスタム構成が必要な場合は、各サブプロジェクトに独自の dokka {} ブロックを持たせることができます。次の例では、サブプロジェクトが Dokka プラグインを適用し、カスタムサブプロジェクト名を設定し、その README.md ファイルから追加のドキュメントを含めています。

kotlin

// subproject/build.gradle.kts
plugins {
    id("org.jetbrains.dokka")
}

dokka {
    dokkaPublications.html {
        moduleName.set("Child Project A")
        includes.from("README.md")
    }
}

Dokkaを実行する

出力形式

取得

操作と演算子

Gradle ​

サポートされているバージョン ​

Dokka の適用 ​

ビルドキャッシュと構成キャッシュの有効化 ​

ドキュメントの生成 ​

ドキュメントの出力形式の構成 ​

マルチプロジェクトビルドでのドキュメント出力の集約 ​

集約されたドキュメントのディレクトリ ​

javadoc.jar のビルド ​

構成例 ​

シングルプロジェクト構成 ​

マルチプロジェクト構成 ​

コンベンションプラグインを介した共有構成 ​

buildSrc ディレクトリをセットアップする ​

Dokka コンベンションプラグインをセットアップする ​

コンベンションプラグインをサブプロジェクトに適用する ​

手動構成 ​

親プロジェクトの構成 ​

Gradle

サポートされているバージョン

Dokka の適用

ビルドキャッシュと構成キャッシュの有効化

ドキュメントの生成

ドキュメントの出力形式の構成

マルチプロジェクトビルドでのドキュメント出力の集約

集約されたドキュメントのディレクトリ

javadoc.jar のビルド

構成例

シングルプロジェクト構成

マルチプロジェクト構成

コンベンションプラグインを介した共有構成

buildSrc ディレクトリをセットアップする

Dokka コンベンションプラグインをセットアップする

コンベンションプラグインをサブプロジェクトに適用する

手動構成

親プロジェクトの構成