Skip to content

Gradle ​

本指南適用於 Dokka Gradle 外掛程式 (DGP) v2 模式。之前的 DGP v1 模式已不再受支援。 如果您正從 v1 升級到 v2 模式,請參閱遷移指南。

若要為基於 Gradle 的專案產生文件,您可以使用 Dokka 的 Gradle 外掛程式。

Dokka Gradle 外掛程式 (DGP) 附帶專案的基本自動組態, 包含用於產生文件的 Gradle 任務,並提供組態選項來 自訂輸出。

您可以在我們的 Gradle 範例專案中 嘗試使用 Dokka 並探索如何為各種專案進行配置。

支援的版本 ​

確保您的專案符合最低版本需求:

工具版本
Gradle7.6 或更高
Android Gradle 外掛程式7.0 或更高
Kotlin Gradle 外掛程式1.9 或更高

套用 Dokka ​

套用 Dokka 的 Gradle 外掛程式的建議方式是使用 plugins 區塊。 將其新增至專案 build.gradle.kts 檔案的 plugins {} 區塊中:

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

在為多專案組建編寫文件時,您需要將外掛程式明確套用到每個想要編寫文件的子專案中。 您可以直接在每個子專案中配置 Dokka,或使用慣例外掛程式在子專案之間共用 Dokka 組態。 如需詳細資訊,請參閱 如何配置單一專案和多專案組建。

啟用組建快取和組態快取 ​

DGP 支援 Gradle 組建快取和組態快取,可提高組建效能。

產生文件 ​

Dokka Gradle 外掛程式內建了 HTML 和 Javadoc 輸出格式。

使用以下 Gradle 任務來產生文件:

shell
./gradlew :dokkaGenerate

dokkaGenerate Gradle 任務的主要行為是:

配置文件輸出格式 ​

Javadoc 輸出格式目前處於 Alpha 階段。 使用時可能會遇到錯誤和遷移問題。 不保證能與接受 Javadoc 作為輸入的工具成功整合。 請自行承擔使用風險。

您可以選擇產生 HTML、Javadoc 格式的 API 文件, 或同時產生這兩種格式:

  1. 在專案 build.gradle.kts 檔案的 plugins {} 區塊中放置對應的外掛程式 id:

    kotlin
    plugins {
        // 產生 HTML 文件
        id("org.jetbrains.dokka") version "2.2.0"
    
        // 產生 Javadoc 文件
        id("org.jetbrains.dokka-javadoc") version "2.2.0"
    
        // 同時保留兩個外掛程式 ID 會產生兩種格式
    }
  2. 執行對應的 Gradle 任務。

    以下是對應於每種格式的外掛程式 id 和 Gradle 任務列表:

    HTMLJavadoc兩者皆有
    外掛程式 idid("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 可以將多個子專案的文件彙總到單一輸出或發布中。

您必須在彙總文件之前將 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 任務來實現。一個用於產生 HTML 格式文件,另一個用於產生 Javadoc 格式文件:

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 檔案。 它們可以是單平台或多平台,通常具有以下結構:

單平台:

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 進行配置:

kotlin
plugins {
    id("org.jetbrains.dokka") version "2.2.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.2.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 檔案,且具有類似以下的結構:

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 有兩種方式:

  • 透過慣例外掛程式共用組態(偏好方式):定義一個慣例外掛程式並將其套用到所有子專案。 這可以集中管理您的 Dokka 設定。

  • 手動配置:套用 Dokka 外掛程式並在每個子專案中重複相同的 dokka {} 區塊。 您不需要慣例外掛程式。

在配置子專案後,您可以將來自多個子專案的文件彙總至單一輸出。 如需詳細資訊,請參閱 彙總多專案組建的文件輸出。

如需多專案範例,請參閱 Dokka GitHub 儲存庫。

透過慣例外掛程式共用組態 ​

遵循下列步驟來設定慣例外掛程式並將其套用到您的子專案。

設定 buildSrc 目錄 ​
  1. 在專案根目錄中,建立一個包含兩個檔案的 buildSrc 目錄:

    • settings.gradle.kts
    • build.gradle.kts
  2. 在 buildSrc/settings.gradle.kts 檔案中,新增以下片段:

    kotlin
    rootProject.name = "buildSrc"
  3. 在 buildSrc/build.gradle.kts 檔案中,新增以下片段:

    kotlin
    plugins {
        `kotlin-dsl`
    }
    
    repositories {
        mavenCentral()
        gradlePluginPortal()
    }
    
    dependencies {
        implementation("org.jetbrains.dokka:dokka-gradle-plugin:2.2.0")
    }
設定 Dokka 慣例外掛程式 ​

設定 buildSrc 目錄後,設定 Dokka 慣例外掛程式:

  1. 建立 buildSrc/src/main/kotlin/dokka-convention.gradle.kts 檔案以裝載慣例外掛程式。

  2. 在 dokka-convention.gradle.kts 檔案中,新增以下片段:

    kotlin
    plugins {
        id("org.jetbrains.dokka") 
    }
    
    dokka {
        // 共用組態放在這裡
    }

    您需要在 dokka {} 區塊中新增所有子專案通用的共用 Dokka 組態。 此外,您不需要指定 Dokka 版本。 版本已在 buildSrc/build.gradle.kts 檔案中設定。

將慣例外掛程式套用到您的子專案 ​

透過將 Dokka 慣例外掛程式新增到每個子專案的 build.gradle.kts 檔案中,來將其套用到您的子專案:

kotlin
plugins {
    id("dokka-convention")
}

手動配置 ​

如果您的專案不使用慣例外掛程式,您可以透過手動 將相同的 dokka {} 區塊複製到每個子專案中來重複使用相同的 Dokka 配置模式:

  1. 在每個子專案的 build.gradle.kts 檔案中套用 Dokka 外掛程式:

    kotlin
    plugins {
        id("org.jetbrains.dokka") version "2.2.0"
    }
  2. 在每個子專案的 dokka {} 區塊中宣告共用組態。因為沒有集中配置的慣例外掛程式,所以您需要跨子專案重複任何您想要的配置。如需詳細資訊, 請參閱組態選項。

根專案組態 ​

在多專案組建中,您可以在根專案中配置適用於整份文件的設定。 這可以包括定義輸出格式、輸出目錄、文件子專案名稱、 從所有子專案彙總文件,以及其他組態選項:

kotlin
plugins {
    id("org.jetbrains.dokka") version "2.2.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")
    }
}