DokkaのGradle設定オプション
Dokkaには、作成者と読者の体験をカスタマイズするための多くの設定オプションがあります。
以下に、各設定セクションの詳細な説明といくつかの例を示します。すべての設定オプションを適用した例も確認できます。
単一プロジェクトおよびマルチプロジェクトのビルドで設定ブロックを適用する方法の詳細については、設定例を参照してください。
一般設定
Dokka Gradleプラグインの一般的な設定例は以下のとおりです。
トップレベルの
dokka {}DSL設定を使用します。DGPでは、Dokka publication(公開)設定を
dokkaPublications{}ブロックで宣言します。GradleのKotlin DSLはタイプセーフアクセサー(type-safe accessors)を使用するため、
build.gradle.ktsファイルの構文は通常の.ktファイル(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ドキュメントを参照してください。
// 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"))
}
}
}
}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ソースセットのいくつかのオプションを設定できます。
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 {
// 外部ドキュメントリンクセクション
}
}
}
}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プラグインなどで使用されるものなど)とは異なります。
// build.gradle.kts
dokka {
dokkaSourceSets.main {
sourceLink {
localDirectory.set(file("src/main/kotlin"))
remoteUrl("https://github.com/your-repo")
remoteLineSuffix.set("#L")
}
}
}// 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")
}
}
}
}
}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 に一致する特定のパッケージに対していくつかのオプションを設定できます。
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)
}
}
}
}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の規則に合わせてこのメソッドを使用します。
dokka {
dokkaSourceSets.configureEach {
externalDocumentationLinks.register("example-docs") {
url("https://example.com/docs/")
packageListUrl("https://example.com/docs/package-list")
}
}
}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による自動解決に依存する代替手段です。
パッケージリストには、サブプロジェクト名やパッケージ名など、ドキュメントおよびプロジェクト自体に関する情報が含まれています。
ネットワーク呼び出しを回避するために、ローカルにキャッシュされたファイルにすることもできます。
完全な設定
以下は、可能なすべての設定オプションを同時に適用した例です。
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
)
)
}
}
}
}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)
}
}
}
}