Skip to content

命令列介面

如果由於某些原因您無法使用 GradleMaven 建置工具,Dokka 提供了命令列介面 (CLI) 執行器來生成文件。

相比之下,它與 Dokka 的 Gradle 外掛程式具有相同甚至更多的功能。儘管它的設定要困難得多,因為沒有自動設定,尤其是在多平台和多模組環境中。

開始使用

CLI 執行器作為獨立的可執行產物發布到 Maven Central。

您可以在 Maven Central 上找到它,或直接下載

dokka-cli-2.0.0.jar 檔案儲存到您的電腦後,使用 -help 選項執行它以查看所有可用的設定選項及其說明:

Bash
java -jar dokka-cli-2.0.0.jar -help

它也適用於某些巢狀選項,例如 -sourceSet

Bash
java -jar dokka-cli-2.0.0.jar -sourceSet -help

產生文件

先決條件

由於沒有建置工具來管理依賴項,您必須自行提供依賴項 .jar 檔案。

以下是您需要為任何輸出格式準備的依賴項:

群組產物版本連結
org.jetbrains.dokkadokka-base2.0.0下載
org.jetbrains.dokkaanalysis-kotlin-descriptors2.0.0下載

以下是 HTML 輸出格式所需的額外依賴項:

群組產物版本連結
org.jetbrains.kotlinxkotlinx-html-jvm0.8.0下載
org.freemarkerfreemarker2.3.31下載

使用命令列選項執行

您可以傳遞命令列選項來設定 CLI 執行器。

至少需要提供以下選項:

  • -pluginsClasspath - 已下載依賴項的絕對/相對路徑列表,以分號 ; 分隔
  • -sourceSet - 要生成文件的程式碼來源的絕對路徑
  • -outputDir - 文件輸出目錄的絕對/相對路徑
Bash
java -jar dokka-cli-2.0.0.jar \
     -pluginsClasspath "./dokka-base-2.0.0.jar;./analysis-kotlin-descriptors-2.0.0.jar;./kotlinx-html-jvm-0.8.0.jar;./freemarker-2.3.31.jar" \
     -sourceSet "-src /home/myCoolProject/src/main/kotlin" \
     -outputDir "./dokka/html"

執行給定的範例會生成 HTML 輸出格式的文件。

有關更多設定詳情,請參閱命令列選項

使用 JSON 設定執行

可以使用 JSON 來設定 CLI 執行器。在此情況下,您需要提供 JSON 設定檔的絕對/相對路徑作為第一個也是唯一的參數。所有其他設定選項都將從中解析。

Bash
java -jar dokka-cli-2.0.0.jar dokka-configuration.json

至少需要以下 JSON 設定檔:

json
{
  "outputDir": "./dokka/html",
  "sourceSets": [
    {
      "sourceSetID": {
        "scopeId": "moduleName",
        "sourceSetName": "main"
      },
      "sourceRoots": [
        "/home/myCoolProject/src/main/kotlin"
      ]
    }
  ],
  "pluginsClasspath": [
    "./dokka-base-2.0.0.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./analysis-kotlin-descriptors-2.0.0.jar",
    "./freemarker-2.3.31.jar"
  ]
}

有關更多詳情,請參閱 JSON 設定選項

其他輸出格式

預設情況下,dokka-base 產物僅包含 HTML 輸出格式。

所有其他輸出格式都實現為 Dokka 外掛程式。為了使用它們,您必須將它們放到外掛程式類別路徑中。

例如,如果您想以實驗性的 GFM 輸出格式生成文件,您需要下載 gfm-plugin 的 JAR(下載)並將其傳遞給 pluginsClasspath 設定選項。

透過命令列選項:

Shell
java -jar dokka-cli-2.0.0.jar \
     -pluginsClasspath "./dokka-base-2.0.0.jar;...;./gfm-plugin-2.0.0.jar" \
     ...

透過 JSON 設定:

json
{
  ...
  "pluginsClasspath": [
    "./dokka-base-2.0.0.jar",
    "...",
    "./gfm-plugin-2.0.0.jar"
  ],
  ...
}

將 GFM 外掛程式傳遞給 pluginsClasspath 後,CLI 執行器將生成 GFM 輸出格式的文件。

有關更多資訊,請參閱 MarkdownJavadoc 頁面。

命令列選項

要查看所有可能的命令列選項及其詳細說明,請執行:

Bash
java -jar dokka-cli-2.0.0.jar -help

簡要摘要:

選項說明
moduleName專案/模組的名稱。
moduleVersion文件化版本。
outputDir輸出目錄路徑,預設為 ./dokka
sourceSetDokka 原始碼集的設定。包含巢狀設定選項。
pluginsConfigurationDokka 外掛程式的設定。
pluginsClasspath包含 Dokka 外掛程式及其依賴項的 JAR 檔案列表。接受以分號分隔的多個路徑。
offlineMode是否透過網路解析遠端檔案/連結。
failOnWarning如果 Dokka 發出警告或錯誤,是否中止文件生成。
delayTemplateSubstitution是否延遲某些元素的替換。用於多模組專案的增量建置。
noSuppressObviousFunctions是否抑制明顯的函式,例如繼承自 kotlin.Anyjava.lang.Object 的函式。
includes包含模組和套件文件的 Markdown 檔案。接受以分號分隔的多個值。
suppressInheritedMembers是否抑制未在給定類別中明確覆寫的繼承成員。
globalPackageOptions全域套件設定選項列表,格式為 "matchingRegex,-deprecated,-privateApi,+warnUndocumented,+suppress;+visibility:PUBLIC;..."。接受以分號分隔的多個值。
globalLinks全域外部文件連結,格式為 {url}^{packageListUrl}。接受以 ^^ 分隔的多個值。
globalSrcLink原始碼目錄與用於瀏覽程式碼的 Web 服務之間的全域映射。接受以分號分隔的多個路徑。
helpSourceSet顯示巢狀 -sourceSet 設定的幫助資訊。
loggingLevel日誌級別,可能的值:DEBUG, PROGRESS, INFO, WARN, ERROR
help, h使用資訊。

原始碼集選項

要查看巢狀 -sourceSet 設定的命令列選項列表,請執行:

Bash
java -jar dokka-cli-2.0.0.jar -sourceSet -help

簡要摘要:

選項說明
sourceSetName原始碼集的名稱。
displayName原始碼集的顯示名稱,內部和外部皆使用。
classpath用於分析和互動式範例的類別路徑。接受以分號分隔的多個路徑。
src要分析和文件化的原始碼根目錄。接受以分號分隔的多個路徑。
dependentSourceSets依賴原始碼集的名稱,格式為 moduleName/sourceSetName。接受以分號分隔的多個值。
samples包含範例函式的目錄或檔案列表。接受以分號分隔的多個路徑。
includes包含模組和套件文件的 Markdown 檔案。接受以分號分隔的多個路徑。
documentedVisibilities要文件化的可見性。接受以分號分隔的多個值。可能的值:PUBLICPRIVATEPROTECTEDINTERNALPACKAGE
reportUndocumented是否報告未文件化的宣告。
noSkipEmptyPackages是否為空套件建立頁面。
skipDeprecated是否跳過已棄用的宣告。
jdkVersion用於連結到 JDK Javadoc 的 JDK 版本。
languageVersion用於設定分析和範例的語言版本。
apiVersion用於設定分析和範例的 Kotlin API 版本。
noStdlibLink是否產生連結到 Kotlin 標準函式庫。
noJdkLink是否產生連結到 JDK Javadoc。
suppressedFiles要抑制的檔案路徑。接受以分號分隔的多個路徑。
analysisPlatform用於設定分析的平台。
perPackageOptions套件原始碼集設定列表,格式為 matchingRegexp,-deprecated,-privateApi,+warnUndocumented,+suppress;...。接受以分號分隔的多個值。
externalDocumentationLinks外部文件連結,格式為 {url}^{packageListUrl}。接受以 ^^ 分隔的多個值。
srcLink原始碼目錄與用於瀏覽程式碼的 Web 服務之間的映射。接受以分號分隔的多個路徑。

JSON 設定

以下是每個設定區塊的一些範例和詳細說明。您也可以在頁面底部找到一個套用所有設定選項的範例。

一般設定

json
{
  "moduleName": "Dokka Example",
  "moduleVersion": null,
  "outputDir": "./build/dokka/html",
  "failOnWarning": false,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": false,
  "offlineMode": false,
  "includes": [
    "module.md"
  ],
  "sourceLinks":  [
    { "_comment": "Options are described in a separate section" }
  ],
  "perPackageOptions": [
    { "_comment": "Options are described in a separate section" }
  ],
  "externalDocumentationLinks":  [
    { "_comment": "Options are described in a separate section" }
  ],
  "sourceSets": [
    { "_comment": "Options are described in a separate section" }
  ],
  "pluginsClasspath": [
    "./dokka-base-2.0.0.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./analysis-kotlin-descriptors-2.0.0.jar",
    "./freemarker-2.3.31.jar"
  ]
}
moduleName

用於指代模組的顯示名稱。它用於目錄、導覽、日誌記錄等。

預設值:root

moduleVersion

模組版本。

預設值:空白

outputDirectory

文件生成目標目錄,與輸出格式無關。

預設值:./dokka

failOnWarning

如果 Dokka 發出警告或錯誤,是否中止文件生成。 程序會先等待所有錯誤和警告發出。

此設定與 reportUndocumented 搭配使用效果良好

預設值:false

suppressObviousFunctions

是否抑制明顯的函式。

函式被視為明顯,如果它:
  • 繼承自 kotlin.AnyKotlin.Enumjava.lang.Objectjava.lang.Enum,例如 equalshashCodetoString
  • 合成(由編譯器生成)且沒有任何文件,例如 dataClass.componentNdataClass.copy

預設值:true

suppressInheritedMembers

是否抑制在給定類別中未明確覆寫的繼承成員。

注意:這可以抑制 equals / hashCode / toString 等函式, 但不能抑制 dataClass.componentNdataClass.copy 等合成函式。為此請使用 suppressObviousFunctions

預設值:false

offlineMode

是否透過網路解析遠端檔案/連結。

這包括用於生成外部文件連結的套件列表。 例如,使標準函式庫中的類別可點擊。

將此設定為 true 在某些情況下可以顯著加快建置時間, 但也可能降低文件品質和使用者體驗。例如,不 解析來自您的依賴項(包括標準函式庫)的類別/成員連結。

注意:您可以將已獲取的檔案快取到本地並將其作為本地路徑提供給 Dokka。請參閱 externalDocumentationLinks 部分。

預設值:false

includes

包含 模組和套件文件的 Markdown 檔案列表。

指定檔案的內容將被解析並嵌入文件中作為模組和套件描述。

這可以在每個套件的基礎上進行設定。

sourceSets

Kotlin 原始碼集的個別和額外設定。

有關可能選項的列表,請參閱原始碼集設定

sourceLinks

套用於所有原始碼集的全域原始碼連結設定。

有關可能選項的列表,請參閱原始碼連結設定

perPackageOptions

與其所在原始碼集無關的匹配套件的全域設定。

有關可能選項的列表,請參閱每個套件設定

externalDocumentationLinks

與其所在原始碼集無關的全域外部文件連結設定。

有關可能選項的列表,請參閱外部文件連結設定

pluginsClasspath

包含 Dokka 外掛程式及其依賴項的 JAR 檔案列表。

原始碼集設定

如何設定 Kotlin 原始碼集

json
{
  "sourceSets": [
    {
      "displayName": "jvm",
      "sourceSetID": {
        "scopeId": "moduleName",
        "sourceSetName": "main"
      },
      "dependentSourceSets": [
        {
          "scopeId": "dependentSourceSetScopeId",
          "sourceSetName": "dependentSourceSetName"
        }
      ],
      "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"],
      "reportUndocumented": false,
      "skipEmptyPackages": true,
      "skipDeprecated": false,
      "jdkVersion": 8,
      "languageVersion": "1.7",
      "apiVersion": "1.7",
      "noStdlibLink": false,
      "noJdkLink": false,
      "includes": [
        "module.md"
      ],
      "analysisPlatform": "jvm",
      "sourceRoots": [
        "/home/ignat/IdeaProjects/dokka-debug-mvn/src/main/kotlin"
      ],
      "classpath": [
        "libs/kotlin-stdlib-2.2.20.jar",
        "libs/kotlin-stdlib-common-2.2.20.jar"
      ],
      "samples": [
        "samples/basic.kt"
      ],
      "suppressedFiles": [
        "src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
      ],
      "sourceLinks":  [
        { "_comment": "Options are described in a separate section" }
      ],
      "perPackageOptions": [
        { "_comment": "Options are described in a separate section" }
      ],
      "externalDocumentationLinks":  [
        { "_comment": "Options are described in a separate section" }
      ]
    }
  ]
}
displayName

用於指代此原始碼集的顯示名稱。

該名稱在外部(例如,原始碼集名稱對文件閱讀器可見)和 內部(例如,用於 reportUndocumented 的日誌訊息)都使用。

如果沒有更好的替代方案,可以使用平台名稱。

sourceSetID

原始碼集的技術 ID

documentedVisibilities

應文件化的可見性修飾符集合。

如果您想文件化 protected/internal/private 宣告, 以及如果您想排除 public 宣告並僅文件化內部 API,可以使用此選項。

這可以在每個套件的基礎上進行設定。

可能的值:

  • PUBLIC
  • PRIVATE
  • PROTECTED
  • INTERNAL
  • PACKAGE

預設值:PUBLIC

reportUndocumented

是否發出關於可見的未文件化宣告的警告,即在被 KDocs documentedVisibilities 和其他篩選器過濾後沒有 KDocs 的宣告。

此設定與 failOnWarning 搭配使用效果良好。

這可以在每個套件的基礎上進行設定。

預設值:false

skipEmptyPackages

是否跳過在應用各種篩選器後不包含任何可見宣告的套件。

例如,如果 skipDeprecated 設定為 true 且您的套件僅包含 已棄用的宣告,則該套件將被視為空。

CLI 執行器的預設值為 false

skipDeprecated

是否文件化使用 @Deprecated 註解的宣告。

這可以在專案/模組級別設定。

預設值:false

jdkVersion

生成 Java 類型外部文件連結時使用的 JDK 版本。

例如,如果您在某些公共宣告簽章中使用 java.util.UUID, 並且此選項設定為 8,Dokka 將為其生成指向 JDK 8 Javadoc 的外部文件連結。

languageVersion

用於設定分析和 @sample 環境的Kotlin 語言版本

apiVersion

用於設定分析和 @sample 環境的Kotlin API 版本

noStdlibLink

是否生成指向 Kotlin 標準函式庫 API 參考文件的外部文件連結。

注意:當 noStdLibLink 設定為 false 時,連結生成。

預設值:false

noJdkLink

是否生成指向 JDK Javadoc 的外部文件連結。

JDK Javadoc 的版本由 jdkVersion 選項決定。

注意:當 noJdkLink 設定為 false 時,連結生成。

預設值:false

includes

包含模組和套件文件的 Markdown 檔案列表。

指定檔案的內容將被解析並嵌入文件中作為模組和套件描述。

analysisPlatform

用於設定程式碼分析和 @sample 環境的平台。

可能的值:

  • jvm
  • common
  • js
  • native
sourceRoots

要分析和文件化的原始碼根目錄。 可接受的輸入是目錄和單個 .kt / .java 檔案。

classpath

用於分析和互動式範例的類別路徑。

如果某些來自依賴項的類型未自動解析/選取,這會很有用。

此選項接受 .jar.klib 檔案。

samples

包含透過 @sample KDoc 標籤引用的範例函式的目錄或檔案列表。

suppressedFiles

生成文件時要抑制的檔案。

sourceLinks

僅適用於此原始碼集的原始碼連結參數集合。

有關可能選項的列表,請參閱原始碼連結設定

perPackageOptions

此原始碼集內匹配套件特有的參數集合。

有關可能選項的列表,請參閱每個套件設定

externalDocumentationLinks

僅適用於此原始碼集的外部文件連結參數集合。

有關可能選項的列表,請參閱外部文件連結設定

原始碼連結設定

源連結 (sourceLinks) 設定區塊允許您為每個簽章添加一個源連結,該連結指向帶有特定行號的 remoteUrl。(行號可以透過設定 remoteLineSuffix 來配置)。

這有助於讀者找到每個宣告的原始碼。

例如,請參閱 kotlinx.coroutinescount() 函式的文件。

您可以同時為所有原始碼集設定原始碼連結,或單獨設定

json
{
  "sourceLinks": [
    {
      "localDirectory": "src/main/kotlin",
      "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin",
      "remoteLineSuffix": "#L"
    }
  ]
}
localDirectory

本地原始碼目錄的路徑。

remoteUrl

原始碼託管服務的 URL,文件讀者可以存取該服務, 例如 GitHub、GitLab、Bitbucket 等。此 URL 用於生成 宣告的原始碼連結。

remoteLineSuffix

用於將原始碼行號附加到 URL 的後綴。這有助於讀者不僅導航 到檔案,還導航到宣告的特定行號。

數字本身將附加到指定的後綴。例如, 如果此選項設定為 #L 且行號為 10,則產生的 URL 後綴 為 #L10

常用服務使用的後綴:

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

預設值:空白(無後綴)

每個套件設定

套件設定 (perPackageOptions) 區塊允許為由 matchingRegex 匹配的特定套件設定一些選項。

您可以同時為所有原始碼集添加套件設定,或單獨添加

json
{
  "perPackageOptions": [
    {
      "matchingRegex": ".*internal.*",
      "suppress": false,
      "skipDeprecated": false,
      "reportUndocumented": false,
      "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
    }
  ]
}
matchingRegex

用於匹配套件的正規表達式。

suppress

生成文件時是否應跳過此套件。

預設值:false

skipDeprecated

是否文件化使用 @Deprecated 註解的宣告。

這可以在專案/模組級別設定。

預設值:false

reportUndocumented

是否發出關於可見的未文件化宣告的警告,即在被 KDocs documentedVisibilities 和其他篩選器過濾後沒有 KDocs 的宣告。

此設定與 failOnWarning 搭配使用效果良好。

這可以在原始碼集級別設定。

預設值:false

documentedVisibilities

應文件化的可見性修飾符集合。

如果您想文件化此套件內的 protected/internal/private 宣告, 以及如果您想排除 public 宣告並僅文件化內部 API,可以使用此選項。

可以在原始碼集級別設定。

預設值:PUBLIC

外部文件連結設定

外部文件連結 (externalDocumentationLinks) 區塊允許建立指向您依賴項的外部託管文件的連結。

例如,如果您正在使用 kotlinx.serialization 中的類型,預設情況下,它們在您的文件中是不可點擊的,就好像它們未解析一樣。但是,由於 kotlinx.serialization 的 API 參考文件是由 Dokka 建置並發布在 kotlinlang.org 上的,您可以為其設定外部文件連結。這使得 Dokka 能夠為該函式庫中的類型生成連結,使其成功解析並可點擊。

您可以同時為所有原始碼集設定外部文件連結,或單獨設定

json
{
  "externalDocumentationLinks": [
    {
      "url": "https://kotlinlang.org/api/kotlinx.serialization/",
      "packageListUrl": "https://kotlinlang.org/api/kotlinx.serialization/package-list"
    }
  ]
}
url

要連結到的文件的根 URL。它必須包含尾隨斜槓。

Dokka 會盡力自動為給定的 URL 找到 package-list, 並將宣告連結在一起。

如果自動解析失敗,或者您想使用本地快取的檔案, 請考慮設定 packageListUrl 選項。

packageListUrl

package-list 的確切位置。這是依賴 Dokka 自動解析的替代方案。

套件列表包含有關文件和專案本身的信息, 例如模組和套件名稱。

這也可以是本地快取的檔案,以避免網路呼叫。

完整設定

下方您可以看到同時套用所有可能設定選項的範例。

json
{
  "moduleName": "Dokka Example",
  "moduleVersion": null,
  "outputDir": "./build/dokka/html",
  "failOnWarning": false,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": false,
  "offlineMode": false,
  "sourceLinks": [
    {
      "localDirectory": "src/main/kotlin",
      "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin",
      "remoteLineSuffix": "#L"
    }
  ],
  "externalDocumentationLinks": [
    {
      "url": "https://docs.oracle.com/javase/8/docs/api/",
      "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
    },
    {
      "url": "https://kotlinlang.org/api/core/kotlin-stdlib/",
      "packageListUrl": "https://kotlinlang.org/api/core/kotlin-stdlib/package-list"
    }
  ],
  "perPackageOptions": [
    {
      "matchingRegex": ".*internal.*",
      "suppress": false,
      "reportUndocumented": false,
      "skipDeprecated": false,
      "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
    }
  ],
  "sourceSets": [
    {
      "displayName": "jvm",
      "sourceSetID": {
        "scopeId": "moduleName",
        "sourceSetName": "main"
      },
      "dependentSourceSets": [
        {
          "scopeId": "dependentSourceSetScopeId",
          "sourceSetName": "dependentSourceSetName"
        }
      ],
      "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"],
      "reportUndocumented": false,
      "skipEmptyPackages": true,
      "skipDeprecated": false,
      "jdkVersion": 8,
      "languageVersion": "1.7",
      "apiVersion": "1.7",
      "noStdlibLink": false,
      "noJdkLink": false,
      "includes": [
        "module.md"
      ],
      "analysisPlatform": "jvm",
      "sourceRoots": [
        "/home/ignat/IdeaProjects/dokka-debug-mvn/src/main/kotlin"
      ],
      "classpath": [
        "libs/kotlin-stdlib-2.2.20.jar",
        "libs/kotlin-stdlib-common-2.2.20.jar"
      ],
      "samples": [
        "samples/basic.kt"
      ],
      "suppressedFiles": [
        "src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
      ],
      "sourceLinks": [
        {
          "localDirectory": "src/main/kotlin",
          "remoteUrl": "https://github.com/Kotlin/dokka/tree/master/src/main/kotlin",
          "remoteLineSuffix": "#L"
        }
      ],
      "externalDocumentationLinks": [
        {
          "url": "https://docs.oracle.com/javase/8/docs/api/",
          "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
        },
        {
          "url": "https://kotlinlang.org/api/core/kotlin-stdlib/",
          "packageListUrl": "https://kotlinlang.org/api/core/kotlin-stdlib/package-list"
        }
      ],
      "perPackageOptions": [
        {
          "matchingRegex": ".*internal.*",
          "suppress": false,
          "reportUndocumented": false,
          "skipDeprecated": false,
          "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"]
        }
      ]
    }
  ],
  "pluginsClasspath": [
    "./dokka-base-2.0.0.jar",
    "./kotlinx-html-jvm-0.8.0.jar",
    "./analysis-kotlin-descriptors-2.0.0.jar",
    "./freemarker-2.3.31.jar"
  ],
  "pluginsConfiguration": [
    {
      "fqPluginName": "org.jetbrains.dokka.base.DokkaBase",
      "serializationFormat": "JSON",
      "values": "{\"separateInheritedMembers\":false,\"footerMessage\":\"© 2021 pretty good Copyright\"}"
    }
  ],
  "includes": [
    "module.md"
  ]
}