CLI
如果出於某種原因,你無法使用 Gradle 或 Maven 建置工具,Dokka 也提供了用於產生文件的命令列 (CLI) 執行器。
相較之下,它的功能與 Dokka 的 Gradle 外掛程式相同,甚至更多。不過,由於沒有自動設定,設定起來會困難得多,特別是在多平台與多模組環境中。
開始使用
CLI 執行器以獨立的可執行的產物發布至 Maven Central。
你可以在 Maven Central 上找到它,或者直接下載。
將 dokka-cli-2.2.0.jar 檔案儲存至你的電腦後,使用 -help 選項執行它以查看所有可用的設定選項及其說明:
java -jar dokka-cli-2.2.0.jar -help它也適用於某些巢狀選項,例如 -sourceSet:
java -jar dokka-cli-2.2.0.jar -sourceSet -help產生文件
必要條件
由於沒有建置工具來管理相依性,你必須自行提供相依的 .jar 檔案。
以下列出任何輸出格式皆需要的相依性:
| Group | Artifact | Version | Link |
|---|---|---|---|
org.jetbrains.dokka | dokka-base | 2.2.0 | 下載 |
org.jetbrains.dokka | analysis-kotlin-symbols | 2.2.0 | 下載 |
以下是 HTML 輸出格式所需的額外相依性:
| Group | Artifact | Version | Link |
|---|---|---|---|
org.jetbrains.kotlinx | kotlinx-html-jvm | 0.8.0 | 下載 |
org.freemarker | freemarker | 2.3.31 | 下載 |
使用命令列選項執行
你可以傳遞命令列選項來設定 CLI 執行器。
你至少需要提供以下選項:
-pluginsClasspath- 已下載相依性的絕對/相對路徑清單,以分號;分隔-sourceSet- 要為其產生文件的原始碼之絕對路徑-outputDir- 文件輸出目錄的絕對/相對路徑
java -jar dokka-cli-2.2.0.jar \
-pluginsClasspath "./dokka-base-2.2.0.jar;./analysis-kotlin-symbols-2.2.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 設定檔的絕對/相對路徑作為第一個且唯一的引數。所有其他設定選項都會從中進行剖析。
java -jar dokka-cli-2.2.0.jar dokka-configuration.json你至少需要以下 JSON 設定檔:
{
"outputDir": "./dokka/html",
"sourceSets": [
{
"sourceSetID": {
"scopeId": "moduleName",
"sourceSetName": "main"
},
"sourceRoots": [
"/home/myCoolProject/src/main/kotlin"
]
}
],
"pluginsClasspath": [
"./dokka-base-2.2.0.jar",
"./kotlinx-html-jvm-0.8.0.jar",
"./analysis-kotlin-symbols-2.2.0.jar",
"./freemarker-2.3.31.jar"
]
}詳情請參閱 JSON 設定選項。
其他輸出格式
預設情況下,dokka-base 產物僅包含 HTML 輸出格式。
所有其他輸出格式均實作為 Dokka 外掛程式。若要使用它們,你必須將它們放在外掛程式類別路徑(plugins classpath)中。
例如,如果你想要以實驗性的 GFM 輸出格式產生文件,你需要下載 gfm-plugin 的 JAR(下載),並將其傳遞至 pluginsClasspath 設定選項中。
透過命令列選項:
java -jar dokka-cli-2.2.0.jar \
-pluginsClasspath "./dokka-base-2.2.0.jar;...;./gfm-plugin-2.2.0.jar" \
...透過 JSON 設定:
{
...
"pluginsClasspath": [
"./dokka-base-2.2.0.jar",
"...",
"./gfm-plugin-2.2.0.jar"
],
...
}將 GFM 外掛程式傳遞給 pluginsClasspath 後,CLI 執行器便會產生 GFM 輸出格式的文件。
命令列選項
若要查看所有可能的命令列選項清單及其詳細說明,請執行:
java -jar dokka-cli-2.2.0.jar -help簡要總結:
| 選項 | 說明 |
|---|---|
moduleName | 專案/模組名稱。 |
moduleVersion | 記載的文件版本。 |
outputDir | 輸出目錄路徑,預設為 ./dokka。 |
sourceSet | Dokka 原始碼集的設定。包含巢狀設定選項。 |
pluginsConfiguration | Dokka 外掛程式的設定。 |
pluginsClasspath | 包含 Dokka 外掛程式及其相依性的 JAR 清單。接受以分號分隔的多個路徑。 |
offlineMode | 是否透過網路解析遠端檔案/連結。 |
failOnWarning | 當 Dokka 發出警告或錯誤時,是否使文件產生失敗。 |
delayTemplateSubstitution | 是否延遲某些元素的替換。用於多模組專案的累加建置。 |
noSuppressObviousFunctions | 是否隱藏顯而易見的函式,例如繼承自 kotlin.Any 與 java.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 設定的命令列選項清單,請執行:
java -jar dokka-cli-2.2.0.jar -sourceSet -help簡要總結:
| 選項 | 說明 |
|---|---|
sourceSetName | 原始碼集的名稱。 |
displayName | 原始碼集的顯示名稱,用於內部與外部。 |
classpath | 用於分析和互動式範例的 Classpath。接受以分號分隔的多個路徑。 |
src | 要分析並產生文件的原始碼根目錄。接受以分號分隔的多個路徑。 |
dependentSourceSets | 相依原始碼集的名稱,格式為 moduleName/sourceSetName。接受以分號分隔的多個值。 |
samples | 包含範例函式的目錄或檔案清單。接受以分號分隔的多個路徑。 |
includes | 包含模組與套件文件的 Markdown 檔案。接受以分號分隔的多個路徑。 |
documentedVisibilities | 要記錄的文件可見性。接受以分號分隔的多個值。可能的值:PUBLIC、PRIVATE、PROTECTED、INTERNAL、PACKAGE。 |
reportUndocumented | 是否回報未撰寫文件的宣告。 |
noSkipEmptyPackages | 是否為空套件建立頁面。 |
skipDeprecated | 是否跳過已棄用的宣告。 |
jdkVersion | 用於連結至 JDK Javadoc 的 JDK 版本。 |
languageVersion | 用於設定分析與範例環境的語言版本。 |
apiVersion | 用於設定分析與範例環境的 Kotlin API 版本。 |
noStdlibLink | 是否產生指向 Kotlin 標準函式庫的連結。 |
noJdkLink | 是否產生指向 JDK Javadoc 的連結。 |
suppressedFiles | 要排除的檔案路徑。接受以分號分隔的多個路徑。 |
suppressAnnotatedWith | 要排除標註有特定註解的宣告之註解完整限定名稱 (FQN)。接受以分號分隔的多個值。 |
analysisPlatform | 用於設定分析的平台。 |
perPackageOptions | 套件原始碼集設定清單,格式為 matchingRegexp,-deprecated,-privateApi,+warnUndocumented,+suppress;...。接受以分號分隔的多個值。 |
externalDocumentationLinks | 外部文件連結,格式為 {url}^{packageListUrl}。接受以 ^^ 分隔的多個值。 |
srcLink | 原始碼目錄與用於瀏覽程式碼的 Web 服務之間的對應。接受以分號分隔的多個路徑。 |
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.2.0.jar",
"./kotlinx-html-jvm-0.8.0.jar",
"./analysis-kotlin-symbols-2.2.0.jar",
"./freemarker-2.3.31.jar"
]
}moduleName
用於指稱模組的顯示名稱。它用於目錄、導覽、記錄等。
預設值:root
moduleVersion
模組版本。
預設值:空白
outputDirectory
產生文件的目錄,無論輸出格式為何。
預設值:./dokka
failOnWarning
當 Dokka 發出警告或錯誤時,是否使文件產生失敗。 該程序會先等待所有錯誤與警告全部發出。
此設定與 reportUndocumented 搭配使用效果良好
預設值:false
suppressObviousFunctions
是否隱藏顯而易見的函式。
函式在符合以下情況時被視為顯而易見:- 繼承自
kotlin.Any、Kotlin.Enum、java.lang.Object或java.lang.Enum,例如equals、hashCode、toString。 - 屬於合成函式(由編譯器產生)且沒有任何文件,例如
dataClass.componentN或dataClass.copy。
預設值:true
suppressInheritedMembers
是否隱藏在給定類別中未被明確覆寫的繼承成員。
注意:這可以隱藏諸如 equals / hashCode / toString 等函式, 但無法隱藏合成函式,例如 dataClass.componentN 和 dataClass.copy。對此請改用 suppressObviousFunctions。
預設值:false
offlineMode
是否透過網路解析遠端檔案/連結。
這包括用於產生外部文件連結的 package-list。 例如,讓標準函式庫中的類別可以點擊。
在某些情況下將此設定為 true 可以大幅加快建置速度, 但也可能降低文件品質和使用者體驗。例如, 無法解析來自相依項(包括標準函式庫)的類別/成員連結。
注意:你可以在本機快取擷取的檔案,並將它們作為本機路徑提供給 Dokka。請參閱 externalDocumentationLinks 區段。
預設值:false
includes
sourceLinks
套用於所有原始碼集的全域原始碼連結設定。
有關可能選項的清單,請參閱原始碼連結設定。
perPackageOptions
相符套件的全域設定,無論它們位於哪個原始碼集中。
有關可能選項的清單,請參閱個別套件設定。
externalDocumentationLinks
外部文件連結的全域設定,無論它們在哪個原始碼集中使用。
有關可能選項的清單,請參閱外部文件連結設定。
pluginsClasspath
包含 Dokka 外掛程式及其相依性的 JAR 檔案清單。
原始碼集設定
如何設定 Kotlin 原始碼集:
{
"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.4.21.jar",
"libs/kotlin-stdlib-common-2.4.21.jar"
],
"samples": [
"samples/basic.kt"
],
"suppressedFiles": [
"src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
],
"suppressAnnotatedWith": [
"com.example.SuppressMe"
],
"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 時,可以使用此選項。
這可以在個別套件層級進行設定。
可能的值:
PUBLICPRIVATEPROTECTEDINTERNALPACKAGE
預設值: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
sourceRoots
要分析並產生文件的原始碼根目錄。 可接受的輸入包括目錄以及個別的 .kt / .java 檔案。
classpath
用於分析和互動式範例的 Classpath。
如果來自相依性的某些型別未被自動解析/選取,此選項會非常有用。
此選項同時接受 .jar 與 .klib 檔案。
samples
包含透過 @sample KDoc 標籤參照之範例函式的目錄或檔案清單。
suppressedFiles
產生文件時要排除的檔案。
suppressAnnotatedWith
要排除標註有特定註解的宣告之註解完整限定名稱 (FQN) 清單。
標註有其中任一註解的任何宣告都將從產生的文件中排除。
sourceLinks
僅套用於此原始碼集的原始碼連結參數集。
有關可能選項的清單,請參閱原始碼連結設定。
perPackageOptions
專門套用於此原始碼集中相符套件的參數集。
有關可能選項的清單,請參閱個別套件設定。
externalDocumentationLinks
僅套用於此原始碼集的外部文件連結參數集。
有關可能選項的清單,請參閱外部文件連結設定。
原始碼連結設定
sourceLinks 設定區塊允許你為每個簽章新增一個指向帶有特定行號之 remoteUrl 的 source 連結。(行號可透過設定 remoteLineSuffix 進行設定)。
這有助於讀者找到每個宣告的原始碼。
相關範例,請參閱 kotlinx.coroutines 中 count() 函式的文件。
你可以同時為所有原始碼集統一設定原始碼連結,也可以個別設定:
{
"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 相符的特定套件設定部分選項。
你可以同時為所有原始碼集新增套件設定,也可以個別設定:
{
"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 就能為來自該程式庫的型別產生連結,使其成功解析並可點擊。
你可以同時為所有原始碼集統一設定外部文件連結,也可以個別設定:
{
"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 自動解析之外的另一種選擇。
Package 清單包含有關文件和專案本身的資訊, 例如模組與套件名稱。
這也可以是本機快取的檔案,以避免網路請求。
完整設定
以下你可以看到同時套用所有可能設定選項的範例。
{
"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.4.21.jar",
"libs/kotlin-stdlib-common-2.4.21.jar"
],
"samples": [
"samples/basic.kt"
],
"suppressedFiles": [
"src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
],
"suppressAnnotatedWith": [
"com.example.SuppressMe"
],
"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.2.0.jar",
"./kotlinx-html-jvm-0.8.0.jar",
"./analysis-kotlin-symbols-2.2.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"
]
}