Dokka Gradle 配置選項
Dokka 提供了許多配置選項,用以自訂你與讀者的體驗。
以下是各個配置區段的詳細說明與部分範例。 你也可以找到套用了 所有配置選項 的範例。
如需在單一專案與多專案組建中套用配置區塊的更多詳細資訊, 請參閱配置範例。
一般配置
以下是一般 Dokka Gradle 外掛程式配置的範例:
使用最頂層的
dokka {}DSL 配置。在 DGP 中,於
dokkaPublications{}區塊內宣告 Dokka 發佈配置。build.gradle.kts檔案的語法與一般.kt檔案(例如用於 Kotlin 自訂外掛程式的檔案)不同,因為 Gradle 的 Kotlin DSL 使用了型別安全存取器。
plugins {
id("org.jetbrains.dokka") version "2.2.0"
}
dokka {
dokkaPublications.html {
moduleName.set(project.name)
moduleVersion.set(project.version.toString())
// Standard output directory for HTML documentation
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")
// Output directory for additional files
// Use this block instead of the standard when you
// want to change the output directory and include extra files
outputDirectory.set(rootDir.resolve("docs/api/0.x"))
// Use fileTree to add multiple files
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 ->
// Standard output directory for HTML documentation
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")
// Output directory for additional files
// Use this instead of the standard block when you
// want to change the output directory and include extra files
html.outputDirectory.set(project.rootDir.resolve("docs/api/0.x"))
}
}
}
}plugins {
id 'org.jetbrains.dokka' version '2.2.0'
}
dokka {
dokkaPublications {
html {
// Sets general module information
moduleName.set(project.name)
moduleVersion.set(project.version.toString())
// Standard output directory for HTML documentation
outputDirectory.set(layout.buildDirectory.dir("dokka/html"))
// Core Dokka options
failOnWarning.set(false)
suppressInheritedMembers.set(false)
suppressObviousFunctions.set(true)
offlineMode.set(false)
includes.from(files("packages.md", "extra.md"))
// Output directory for additional files
// Use this block instead of the standard when you want to
// change the output directory and include extra files
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
是否抑制顯而易見的函式。
如果符合以下情況,則該函式會被視為顯而易見的函式:
- 繼承自
kotlin.Any、Kotlin.Enum、java.lang.Object或java.lang.Enum,例如equals、hashCode、toString。 - 合成的(由編譯器產生)且沒有任何說明文件,例如
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 {
// ..
// General configuration section
// ..
// Source sets configuration
dokkaSourceSets {
// Example: Configuration exclusive to the 'linux' source set
named("linux") {
dependentSourceSets{named("native")}
sourceRoots.from(file("linux/src"))
}
configureEach {
suppress.set(false)
displayName.set(name)
documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR 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 {
// Source link section
}
perPackageOption {
// Package options section
}
externalDocumentationLinks {
// External documentation links section
}
}
}
}import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
dokka {
// ..
// General configuration section
// ..
// Source sets configuration
dokkaSourceSets {
// Example: Configuration exclusive to the 'linux' source set
named("linux") {
dependentSourceSets { named("native") }
sourceRoots.from(file("linux/src"))
}
configureEach {
suppress.set(false)
displayName.set(name)
documentedVisibilities.set([VisibilityModifier.Public] as Set) // OR 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 {
// Source link section
}
perPackageOption {
// Package options section
}
externalDocumentationLinks {
// External documentation links section
}
}
}
}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
用於分析與互動式範例的類別路徑 (classpath)。
如果某些來自依賴項的型別未被自動解析或採用,此設定會非常有用。
此選項可接受 .jar 與 .klib 檔案。
預設情況下,類別路徑會從 Kotlin Gradle 外掛程式所提供的資訊推導得出。
samples
包含透過 @sample KDoc 標籤參照之範例函式的目錄或檔案清單。
原始碼連結配置
配置原始碼連結,以協助讀者在遠端存儲庫中找到各宣告的原始碼。 請使用 dokkaSourceSets.main {} 區塊進行此配置。
sourceLinks {} 配置區塊允許你為每個簽章新增一個 source 連結, 該連結指向帶有特定行號的 remoteUrl。 行號可透過設定 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
文件讀者可存取的原始碼代管服務 URL, 例如 GitHub、GitLab、Bitbucket,或任何為原始碼檔案提供穩定 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)) // OR 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 {
// Example: Configuration exclusive to the 'linux' source set
named("linux") {
dependentSourceSets{named("native")}
sourceRoots.from(file("linux/src"))
}
configureEach {
suppress.set(false)
displayName.set(name)
documentedVisibilities.set(setOf(VisibilityModifier.Public)) // OR 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 {
// Example: Configuration exclusive to the 'linux' source set
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)
}
}
}
}