Dokka Gradle 設定オプション
Dokka には、開発者や読者の体験をカスタマイズするための多くの設定オプションがあります。
以下に、各設定セクションの詳細な説明といくつかの例を示します。 また、すべての設定オプションを適用した例も確認できます。
シングルプロジェクトおよびマルチプロジェクトビルドでの設定ブロックの適用に関する詳細は、 設定例を参照してください。
一般設定 (General configuration)
以下は、一般的な Dokka Gradle プラグインの設定例です。
トップレベルの
dokka {}DSL 設定を使用します。DGP(Dokka Gradle Plugin)では、
dokkaPublications{}ブロックで Dokka のパブリケーション設定を宣言します。build.gradle.ktsファイルの構文は、通常の.ktファイル(Kotlin カスタムプラグインなどで使用されるもの)とは異なります。これは、Gradle の Kotlin DSL が型安全なアクセサを使用するためです。
plugins {
id("org.jetbrains.dokka") version "2.1.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.1.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 などの合成関数は抑制しません。 それらを抑制するには suppressObviousFunctions を使用してください。
デフォルト:false
suppressObviousFunctions
明白な関数(obvious functions)を抑制するかどうかを指定します。
以下の条件に当てはまる場合、その関数は明白であるとみなされます:
kotlin.Any、Kotlin.Enum、java.lang.Object、またはjava.lang.Enumから継承されており、equals、hashCode、toStringなどである場合。- 合成(コンパイラによって生成)されており、ドキュメントがない場合(
dataClass.componentNやdataClass.copyなど)。
デフォルト:true
offlineMode
リモートファイルやリンクをネットワーク経由で解決するかどうかを指定します。
これには、外部ドキュメントへのリンクを生成するために使用される package-lists が含まれます。 たとえば、これにより標準ライブラリのクラスをドキュメント内でクリック可能にすることができます。
これを true に設定すると、特定の場合にビルド時間を大幅に短縮できますが、ユーザー体験が悪化する可能性もあります。 たとえば、標準ライブラリを含む依存関係からのクラスやメンバーのリンクが解決されなくなります。
注:取得したファイルをローカルにキャッシュし、ローカルパスとして Dokka に提供することができます。externalDocumentationLinks セクションを参照してください。
デフォルト:false
includes
サブプロジェクトおよびパッケージのドキュメントを含む Markdown ファイルのリストです。Markdown ファイルは要求される形式に一致している必要があります。
指定されたファイルの内容は解析され、サブプロジェクトやパッケージの説明としてドキュメントに埋め込まれます。
外観や使用方法の例については、Dokka Gradle の例を参照してください。
ソースセット設定 (Source set configuration)
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 に設定されており、パッケージに非推奨(deprecated)の宣言しか含まれていない場合、そのパッケージは空であるとみなされます。
デフォルト:true
skipDeprecated
@Deprecated アノテーションが付いた宣言をドキュメント化するかどうかを指定します。
これはパッケージごとに個別に設定することも可能です。
デフォルト:false
suppressGeneratedFiles
生成されたファイルをドキュメント化するかどうかを指定します。
生成されたファイルは {project}/{buildDir}/generated ディレクトリの下にあることが期待されます。
true に設定すると、そのディレクトリにあるすべてのファイルが suppressedFiles オプションに実質的に追加されます。手動で設定することも可能です。
デフォルト:true
suppressAnnotatedWith
指定されたアノテーションが付与された宣言を抑制するための、アノテーションの完全修飾名(FQN)のセットです。
これらのアノテーションのいずれかが付与された宣言は、生成されたドキュメントから除外されます。
jdkVersion
Java 型の外部ドキュメントリンクを生成する際に使用する JDK バージョンです。
たとえば、公開された宣言のシグネチャで java.util.UUID を使用しており、このオプションが 8 に設定されている場合、Dokka はそれに対して JDK 8 Javadoc への外部ドキュメントリンクを生成します。
デフォルト:8
languageVersion
解析および @sample 環境の設定に使用される Kotlin 言語バージョンです。
デフォルトでは、Dokka の組み込みコンパイラで利用可能な最新の言語バージョンが使用されます。
apiVersion
解析および @sample 環境の設定に使用される Kotlin API バージョンです。
デフォルトでは、languageVersion から推論されます。
sourceRoots
解析およびドキュメント化されるソースコードのルートです。 入力としてディレクトリ、および個別の .kt、.java ファイルを受け付けます。
デフォルトでは、Kotlin Gradle プラグインから提供される情報に基づいてソースルートが推論されます。
classpath
解析およびインタラクティブサンプルのためのクラスパスです。
依存関係にある一部の型が自動的に解決されなかったり、取得できなかったりする場合に便利です。
このオプションは .jar ファイルと .klib ファイルの両方を受け付けます。
デフォルトでは、Kotlin Gradle プラグインから提供される情報に基づいてクラスパスが推論されます。
samples
@sample KDoc タグを介して参照されるサンプル関数を含むディレクトリまたはファイルのリストです。
ソースリンク設定 (Source link configuration)
ソースリンクを設定して、読者がリモートリポジトリ内の各宣言のソースを見つけられるようにします。 この設定には dokkaSourceSets.main {} ブロックを使用します。
sourceLinks {} 設定ブロックを使用すると、各シグネチャに特定の行番号を持つ remoteUrl への source リンクを追加できます。 行番号は remoteLineSuffix を設定することでカスタマイズ可能です。
例として、kotlinx.coroutines の count() 関数のドキュメントを参照してください。
build.gradle.kts ファイルの構文は、通常の .kt ファイル(カスタム Gradle プラグインなどで使用されるもの)とは異なります。これは、Gradle の Kotlin DSL が型安全なアクセサを使用するためです。
// 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
パッケージオプション (Package options)
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
外部ドキュメントリンクの設定 (External documentation links configuration)
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 による自動解決に頼る代わりの方法です。
パッケージリストには、サブプロジェクトやパッケージ名など、ドキュメントとプロジェクト自体に関する情報が含まれています。
ネットワーク呼び出しを避けるために、ローカルにキャッシュされたファイルにすることも可能です。
全設定の例 (Complete configuration)
以下に、考えられるすべての設定オプションを同時に適用した例を示します:
import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
plugins {
id("org.jetbrains.dokka") version "2.1.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.1.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)
}
}
}
}