Skip to content

命令列介面 (CLI

[//]: # (title: 命令列介面 (CLI))

如果因為某些原因您無法使用 GradleMaven 建置工具,Dokka 提供了一個命令列 (CLI) 執行器,用於產生文件。

相較之下,它擁有的功能即使不比 Dokka 的 Gradle 外掛程式更多,也至少與之相同。儘管它在設定上要困難得多,因為沒有自動配置,尤其是在多平台和多模組環境中。

開始使用

CLI 執行器以獨立的可執行構件 (artifact) 的形式發佈到 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 來源集 (source set) 的配置。包含巢狀配置選項。
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 標準函式庫 API 參考文件的連結。
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

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

這包括用於產生外部文件連結的 `package-list`。 例如,使標準函式庫中的類別可點擊。

將此設定為 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.1.21.jar",
        "libs/kotlin-stdlib-common-2.1.21.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

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

此設定與 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

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

此設定與 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.1.21.jar",
        "libs/kotlin-stdlib-common-2.1.21.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"
  ]
}