Skip to content

DokkaのGradle設定オプション ​

Dokkaには、作成者と読者の体験をカスタマイズするための多くの設定オプションがあります。

以下に、各設定セクションの詳細な説明といくつかの例を示します。すべての設定オプションを適用した例も確認できます。

単一プロジェクトおよびマルチプロジェクトのビルドで設定ブロックを適用する方法の詳細については、設定例を参照してください。

一般設定 ​

Dokka Gradleプラグインの一般的な設定例は以下のとおりです。

  • トップレベルの dokka {} DSL設定を使用します。

  • DGPでは、Dokka publication(公開)設定を dokkaPublications{} ブロックで宣言します。

  • デフォルトのpublicationは html と javadoc です。

  • GradleのKotlin DSLはタイプセーフアクセサー(type-safe accessors)を使用するため、build.gradle.kts ファイルの構文は通常の .kt ファイル(Kotlinカスタムプラグインなどで使用されるものなど)とは異なります。

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

dokka {
    dokkaPublications.html {
        moduleName.set(project.name)
        moduleVersion.set(project.version.toString())
        // HTMLドキュメントの標準出力ディレクトリ
        outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
        failOnWarning.set(false)
        suppressInheritedMembers.set(false)
        suppressObviousFunctions.set(true)
        offlineMode.set(false)
        includes.from("packages.md", "extra.md")
        
        // 追加ファイルの出力ディレクトリ
        // 出力ディレクトリを変更して追加ファイルを含めたい場合は、
        // 標準ブロックの代わりにこれを使用します
        outputDirectory.set(rootDir.resolve("docs/api/0.x"))
        
        // 複数のファイルを追加するにはfileTreeを使用します
        includes.from(
            fileTree("docs") {
                include("**/*.md")
            }
        )
    }
}

ファイルの操作に関する詳細については、Gradleドキュメントを参照してください。

kotlin
// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")

        project.extensions.configure(DokkaExtension::class.java) { dokka ->
            
            dokka.moduleName.set(project.name)
            dokka.moduleVersion.set(project.version.toString())

            dokka.dokkaPublications.named("html") { publication ->
                // HTMLドキュメントの標準出力ディレクトリ
                publication.outputDirectory.set(project.layout.buildDirectory.dir("dokka/html"))
                publication.failOnWarning.set(true)
                publication.suppressInheritedMembers.set(true)
                publication.offlineMode.set(false)
                publication.suppressObviousFunctions.set(true)
                publication.includes.from("packages.md", "extra.md")

                // 追加ファイルの出力ディレクトリ
                // 出力ディレクトリを変更して追加ファイルを含めたい場合は、
                // 標準ブロックの代わりにこれを使用します
                html.outputDirectory.set(project.rootDir.resolve("docs/api/0.x"))
            }
        }
    }
}
groovy
plugins {
    id 'org.jetbrains.dokka' version '2.2.0'
}

dokka {
    dokkaPublications {
        html {
            // モジュールの基本情報を設定
            moduleName.set(project.name)
            moduleVersion.set(project.version.toString())

            // HTMLドキュメントの標準出力ディレクトリ
            outputDirectory.set(layout.buildDirectory.dir("dokka/html"))

            // Dokkaのコアオプション
            failOnWarning.set(false)
            suppressInheritedMembers.set(false)
            suppressObviousFunctions.set(true)
            offlineMode.set(false)
            includes.from(files("packages.md", "extra.md"))

            // 追加ファイルの出力ディレクトリ
            // 出力ディレクトリを変更して追加ファイルを含めたい場合は、
            // 標準ブロックの代わりにこれを使用します
            outputDirectory.set(file("$rootDir/docs/api/0.x"))
        }
    }
}
moduleName

プロジェクトドキュメントの表示名です。目次、ナビゲーション、ヘッダー、ログメッセージに表示されます。マルチプロジェクトビルドでは、各サブプロジェクトの moduleName が集約ドキュメント内のセクションタイトルとして使用されます。

デフォルト: Gradleプロジェクト名

moduleVersion

生成されたドキュメントに表示されるサブプロジェクトのバージョンです。単一プロジェクトビルドでは、プロジェクトのバージョンとして使用されます。マルチプロジェクトビルドでは、ドキュメントを集約する際に各サブプロジェクトの moduleVersion が使用されます。

デフォルト: Gradleプロジェクトのバージョン

outputDirectory

生成されたドキュメントが保存されるディレクトリです。

この設定は、dokkaGenerate タスクによって生成されるすべてのドキュメント形式(HTML、Javadocなど)に適用されます。

デフォルト: build/dokka/html

追加ファイルの出力ディレクトリ

単一プロジェクトおよびマルチプロジェクトビルドの両方で、出力ディレクトリを指定して追加ファイルを含めることができます。マルチプロジェクトビルドの場合は、ルートプロジェクトの設定で出力ディレクトリを設定し、追加ファイルを含めてください。

failOnWarning

ドキュメント生成中に警告が発生した際に、Dokkaがビルドを失敗させるかどうかを決定します。処理はまずすべてのエラーと警告が出力されるまで待機します。

この設定は reportUndocumented と併用すると効果的です。

デフォルト: false

suppressInheritedMembers

特定のクラスで明示的にオーバーライドされていない継承メンバーを除外するかどうか。

注意: これにより equals、hashCode、toString などの関数は除外されますが、dataClass.componentN や dataClass.copy などの合成(synthetic)関数は除外されません。それらを除外するには suppressObviousFunctions を使用してください。

デフォルト: false

suppressObviousFunctions

自明な(obvious)関数を除外するかどうか。

関数が以下のいずれかに該当する場合、自明であるとみなされます:

  • equals、hashCode、toString のように、kotlin.Any、Kotlin.Enum、java.lang.Object、または java.lang.Enum から継承されている。
  • dataClass.componentN や dataClass.copy のように、合成された(コンパイラによって生成された)ものであり、ドキュメントが存在しない。

デフォルト: true

offlineMode

ネットワーク経由でリモートファイルやリンクを解決するかどうか。

これには、外部ドキュメントへのリンク生成に使用される package-list が含まれます。たとえば、これにより標準ライブラリのクラスをドキュメント内でクリック可能にできます。

これを true に設定すると、場合によってはビルド時間を大幅に短縮できますが、標準ライブラリを含む依存関係のクラスやメンバーへのリンクが解決されなくなるなど、ユーザー体験が悪化する可能性もあります。

注意: 取得したファイルをローカルにキャッシュし、ローカルパスとしてDokkaに提供することができます。<a href="#external-documentation-links-configuration">externalDocumentationLinks</a> セクションを参照してください。

デフォルト: false

includes

サブプロジェクトおよびパッケージのドキュメントを含むMarkdownファイルのリストです。Markdownファイルは必要な形式に一致している必要があります。

指定されたファイルの内容が解析され、サブプロジェクトやパッケージの説明としてドキュメントに埋め込まれます。

外観や使用方法の例については、Dokka Gradleの例を参照してください。

ソースセット設定 ​

Dokkaでは、Kotlinソースセットのいくつかのオプションを設定できます。

kotlin
import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    // ..
    // 一般設定セクション
    // ..

    // ソースセット設定
    dokkaSourceSets {
        // 例: 'linux' ソースセット専用の設定
        named("linux") {
            dependentSourceSets{named("native")}
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(VisibilityModifier.Public)) // または documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")
           
            sourceLink {
                // ソースリンクセクション
            }
            perPackageOption {
                // パッケージオプションセクション
            }
            externalDocumentationLinks {
                // 外部ドキュメントリンクセクション
            }
        }
    }
}
groovy
import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    // ..
    // 一般設定セクション
    // ..

    // ソースセット設定
    dokkaSourceSets {
        // 例: 'linux' ソースセット専用の設定
        named("linux") {
            dependentSourceSets { named("native") }
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([VisibilityModifier.Public] as Set) // または documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                // ソースリンクセクション
            }
            perPackageOption {
                // パッケージオプションセクション
            }
            externalDocumentationLinks {
                // 外部ドキュメントリンクセクション
            }
        }
    }
}
suppress

ドキュメント生成時にこのソースセットをスキップするかどうか。

デフォルト: false

displayName

このソースセットを参照するために使用される表示名。

この名前は、外部向け(ドキュメントの読者に表示されるソースセット名など)と内部向け(reportUndocumented のログメッセージなど)の両方で使用されます。

デフォルトでは、Kotlin Gradleプラグインから提供される情報に基づいて推測されます。

documentedVisibilities

生成されるドキュメントにDokkaが含める可視性修飾子を定義します。

protected、internal、private の宣言をドキュメント化したい場合や、public 宣言を除外して内部APIのみをドキュメント化したい場合に使用します。

さらに、Dokkaの documentedVisibilities() 関数 を使用して、ドキュメント対象の可視性を追加することもできます。

これは個々のパッケージごとに設定できます。

デフォルト: VisibilityModifier.Public

reportUndocumented

documentedVisibilities やその他のフィルターでフィルタリングされた後、ドキュメントのない(KDocがない)可視宣言について警告を出力するかどうか。

この設定は failOnWarning と併用すると効果的です。

これは個々のパッケージごとに設定できます。

デフォルト: false

skipEmptyPackages

各種フィルターが適用された後に、可視宣言を含まないパッケージをスキップするかどうか。

たとえば、skipDeprecated が true に設定されており、パッケージに非推奨の宣言しか含まれていない場合、そのパッケージは空であるとみなされます。

デフォルト: true

skipDeprecated

@Deprecated でアノテーションが付けられた宣言をドキュメント化するかどうか。

これは個々のパッケージごとに設定できます。

デフォルト: false

suppressGeneratedFiles

生成されたファイルをドキュメント化するかどうか。

生成されたファイルは {project}/{buildDir}/generated ディレクトリの下に存在することが想定されています。

true に設定すると、そのディレクトリのすべてのファイルが事実上 suppressedFiles オプションに追加されるため、手動で設定することも可能です。

デフォルト: true

suppressAnnotatedWith

宣言を除外するためのアノテーションの完全修飾名(FQN)のセット。

これらのアノテーションのいずれかが付与されている宣言は、生成されるドキュメントから除外されます。

jdkVersion

Java型に対する外部ドキュメントリンクを生成する際に使用するJDKバージョン。

たとえば、公開宣言のシグネチャで java.util.UUID を使用しており、このオプションが 8 に設定されている場合、Dokkaはそれに対して JDK 8 Javadocs への外部ドキュメントリンクを生成します。

デフォルト: 8

languageVersion

解析および @sample 環境のセットアップに使用される Kotlin言語バージョン。

デフォルトでは、Dokkaの組み込みコンパイラで利用可能な最新の言語バージョンが使用されます。

apiVersion

解析および @sample 環境のセットアップに使用される Kotlin APIバージョン。

デフォルトでは、languageVersion から推測されます。

sourceRoots

解析およびドキュメント化の対象となるソースコードのルート。 受け入れ可能な入力は、ディレクトリならびに個別の .kt および .java ファイルです。

デフォルトでは、ソースルートはKotlin Gradleプラグインから提供される情報に基づいて推測されます。

classpath

解析およびインタラクティブなサンプルのためのクラスパス。

依存関係に由来する一部の型が自動的に解決または検出されない場合に役立ちます。

このオプションは .jar ファイルと .klib ファイルの両方を受け入れます。

デフォルトでは、クラスパスはKotlin Gradleプラグインから提供される情報に基づいて推測されます。

samples

@sample KDocタグを通じて参照されるサンプル関数を含むディレクトリまたはファイルのリスト。

読者がリモートリポジトリ内の各宣言のソースを見つけられるように、ソースリンクを設定します。 この設定には dokkaSourceSets.main {} ブロックを使用します。

sourceLinks {} 設定ブロックを使用すると、各シグネチャに特定の行番号付きで remoteUrl にリンクする source リンクを追加できます。 行番号は remoteLineSuffix を設定することで構成可能です。

例については、kotlinx.coroutines の count() 関数のドキュメントを参照してください。

GradleのKotlin DSLはタイプセーフアクセサーを使用するため、build.gradle.kts ファイルの構文は通常の .kt ファイル(カスタムGradleプラグインなどで使用されるものなど)とは異なります。

kotlin
// build.gradle.kts

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

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")
        project.extensions.configure(DokkaExtension::class.java) { dokka ->
            dokka.dokkaSourceSets.named("main") { dss ->
                dss.includes.from("README.md")
                dss.sourceLink {
                    it.localDirectory.set(project.file("src/main/kotlin"))
                    it.remoteUrl("https://example.com/src")
                    it.remoteLineSuffix.set("#L")
                }
            }
        }
    }
}
groovy
dokka {
    dokkaSourceSets {
        main {
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://github.com/your-repo"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}
localDirectory

ローカルのソースディレクトリへのパス。パスは現在のプロジェクトのルートからの相対パスである必要があります。

remoteUrl

GitHub、GitLab、Bitbucket、またはソースファイルに対して安定したURLを提供するホスティングサービスなど、ドキュメントの読者がアクセスできるソースコードホスティングサービスのURL。このURLは、宣言のソースコードリンクを生成するために使用されます。

remoteLineSuffix

URLにソースコードの行番号を追加するために使用されるサフィックス。これにより、読者はファイルだけでなく、宣言の特定の行番号に移動できます。

番号自体は指定されたサフィックスに追加されます。たとえば、このオプションが #L に設定されており、行番号が 10 の場合、結果のURLサフィックスは #L10 になります。

一般的なサービスで使用されるサフィックス:

  • GitHub: #L
  • GitLab: #L
  • Bitbucket: #lines-

デフォルト: #L

パッケージオプション ​

perPackageOption 設定ブロックを使用すると、matchingRegex に一致する特定のパッケージに対していくつかのオプションを設定できます。

kotlin
import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    dokkaPublications.html {
        dokkaSourceSets.configureEach {
            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(setOf(VisibilityModifier.Public)) // または documentedVisibilities(VisibilityModifier.Public)
            }
        }
    }
}
groovy
import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

dokka {
    dokkaPublications {
        html {
            dokkaSourceSets.configureEach {
                perPackageOption {
                    matchingRegex.set(".*api.*")
                    suppress.set(false)
                    skipDeprecated.set(false)
                    reportUndocumented.set(false)
                    documentedVisibilities.set([VisibilityModifier.Public] as Set)
                }
            }
        }
    }
}
matchingRegex

パッケージの一致判定に使用される正規表現。

デフォルト: .*

suppress

ドキュメント生成時にパッケージをスキップするかどうか。

デフォルト: false

skipDeprecated

@Deprecated でアノテーションが付けられた宣言をドキュメント化するかどうか。

これはソースセットレベルで設定できます。

デフォルト: false

reportUndocumented

documentedVisibilities やその他のフィルターでフィルタリングされた後、ドキュメントのない(KDocがない)可視宣言について警告を出力するかどうか。

この設定は failOnWarning と併用すると効果的です。

これはソースセットレベルで設定できます。

デフォルト: false

documentedVisibilities

生成されるドキュメントにDokkaが含める可視性修飾子を定義します。

このパッケージ内の protected、internal、private の宣言をドキュメント化したい場合や、public 宣言を除外して内部APIのみをドキュメント化したい場合に使用します。

さらに、Dokkaの documentedVisibilities() 関数 を使用して、ドキュメント対象の可視性を追加することもできます。

これはソースセットレベルで設定できます。

デフォルト: VisibilityModifier.Public

externalDocumentationLinks {} ブロックを使用すると、依存関係の外部ホストされているドキュメントへのリンクを作成できます。

たとえば、kotlinx.serialization の型を使用している場合、デフォルトでは未解決であるかのようにドキュメント内でクリックできません。しかし、kotlinx.serialization のAPIリファレンスドキュメントはDokkaによって構築され、kotlinlang.orgで公開されているため、それに対する外部ドキュメントリンクを設定できます。これにより、Dokkaはそのライブラリの型に対するリンクを生成し、正常に解決されてクリック可能になります。

デフォルトでは、Kotlin標準ライブラリ、JDK、Android SDK、およびAndroidXの外部ドキュメントリンクが設定されています。

各リンクを定義するには、register() メソッドを使用して外部ドキュメントリンクを登録します。 externalDocumentationLinks APIは、Gradle DSLの規則に合わせてこのメソッドを使用します。

kotlin
dokka {
    dokkaSourceSets.configureEach {
        externalDocumentationLinks.register("example-docs") {
            url("https://example.com/docs/")
            packageListUrl("https://example.com/docs/package-list")
        }
    }
}
groovy
dokka {
    dokkaSourceSets.configureEach {
        externalDocumentationLinks.register("example-docs") {
            url.set(new URI("https://example.com/docs/"))
            packageListUrl.set(new URI("https://example.com/docs/package-list"))
        }
    }
}
url

リンク先となるドキュメントのルートURL。末尾にスラッシュを含める必要があります。

Dokkaは、指定されたURLの package-list を自動的に見つけて宣言同士をリンクしようと試みます。

自動解決に失敗した場合や、代わりにローカルにキャッシュされたファイルを使用したい場合は、packageListUrl オプションの設定を検討してください。

packageListUrl

package-list の正確な場所。これはDokkaによる自動解決に依存する代替手段です。

パッケージリストには、サブプロジェクト名やパッケージ名など、ドキュメントおよびプロジェクト自体に関する情報が含まれています。

ネットワーク呼び出しを回避するために、ローカルにキャッシュされたファイルにすることもできます。

完全な設定 ​

以下は、可能なすべての設定オプションを同時に適用した例です。

kotlin
import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

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

dokka {
    dokkaPublications.html {
        moduleName.set(project.name)
        moduleVersion.set(project.version.toString())
        outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
        failOnWarning.set(false)
        suppressInheritedMembers.set(false)
        suppressObviousFunctions.set(true)
        offlineMode.set(false)
        includes.from("packages.md", "extra.md")
   }

    dokkaSourceSets {
        // 例: 'linux' ソースセット専用の設定
        named("linux") {
            dependentSourceSets{named("native")}
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set(setOf(VisibilityModifier.Public)) // または documentedVisibilities(VisibilityModifier.Public)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl("https://example.com/src")
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLinks {
                url = URL("https://example.com/docs/")
                packageListUrl = File("/path/to/package-list").toURI().toURL()
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set(
                    setOf(
                        VisibilityModifier.Public,
                        VisibilityModifier.Private,
                        VisibilityModifier.Protected,
                        VisibilityModifier.Internal,
                        VisibilityModifier.Package
                    )
                )
            }
        }
    }
}
groovy
import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

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

dokka {
    dokkaPublications {
        html {
            moduleName.set(project.name)
            moduleVersion.set(project.version.toString())
            outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
            failOnWarning.set(false)
            suppressInheritedMembers.set(false)
            suppressObviousFunctions.set(true)
            offlineMode.set(false)
            includes.from("packages.md", "extra.md")
        }
    }

    dokkaSourceSets {
        // 例: 'linux' ソースセット専用の設定
        named("linux") {
            dependentSourceSets { named("native") }
            sourceRoots.from(file("linux/src"))
        }

        configureEach {
            suppress.set(false)
            displayName.set(name)
            documentedVisibilities.set([VisibilityModifier.Public] as Set)
            reportUndocumented.set(false)
            skipEmptyPackages.set(true)
            skipDeprecated.set(false)
            suppressGeneratedFiles.set(true)
            jdkVersion.set(8)
            languageVersion.set("1.7")
            apiVersion.set("1.7")
            sourceRoots.from(file("src"))
            classpath.from(file("libs/dependency.jar"))
            samples.from("samples/Basic.kt", "samples/Advanced.kt")

            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(new URI("https://example.com/src"))
                remoteLineSuffix.set("#L")
            }

            externalDocumentationLinks {
                url.set(new URI("https://example.com/docs/"))
                packageListUrl.set(new File("/path/to/package-list").toURI().toURL())
            }

            perPackageOption {
                matchingRegex.set(".*api.*")
                suppress.set(false)
                skipDeprecated.set(false)
                reportUndocumented.set(false)
                documentedVisibilities.set([
                        VisibilityModifier.Public,
                        VisibilityModifier.Private,
                        VisibilityModifier.Protected,
                        VisibilityModifier.Internal,
                        VisibilityModifier.Package
                ] as Set)
            }
        }
    }
}