命令列介面
如果由於某些原因您無法使用 Gradle 或 Maven 建置工具,Dokka 提供了命令列介面 (CLI) 執行器來生成文件。
相比之下,它與 Dokka 的 Gradle 外掛程式具有相同甚至更多的功能。儘管它的設定要困難得多,因為沒有自動設定,尤其是在多平台和多模組環境中。
開始使用
CLI 執行器作為獨立的可執行產物發布到 Maven Central。
您可以在 Maven Central 上找到它,或直接下載。
將 dokka-cli-2.0.0.jar
檔案儲存到您的電腦後,使用 -help
選項執行它以查看所有可用的設定選項及其說明:
java -jar dokka-cli-2.0.0.jar -help
它也適用於某些巢狀選項,例如 -sourceSet
:
java -jar dokka-cli-2.0.0.jar -sourceSet -help
產生文件
先決條件
由於沒有建置工具來管理依賴項,您必須自行提供依賴項 .jar
檔案。
以下是您需要為任何輸出格式準備的依賴項:
群組 | 產物 | 版本 | 連結 |
---|---|---|---|
org.jetbrains.dokka | dokka-base | 2.0.0 | 下載 |
org.jetbrains.dokka | analysis-kotlin-descriptors | 2.0.0 | 下載 |
以下是 HTML 輸出格式所需的額外依賴項:
群組 | 產物 | 版本 | 連結 |
---|---|---|---|
org.jetbrains.kotlinx | kotlinx-html-jvm | 0.8.0 | 下載 |
org.freemarker | freemarker | 2.3.31 | 下載 |
使用命令列選項執行
您可以傳遞命令列選項來設定 CLI 執行器。
至少需要提供以下選項:
-pluginsClasspath
- 已下載依賴項的絕對/相對路徑列表,以分號;
分隔-sourceSet
- 要生成文件的程式碼來源的絕對路徑-outputDir
- 文件輸出目錄的絕對/相對路徑
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 設定檔的絕對/相對路徑作為第一個也是唯一的參數。所有其他設定選項都將從中解析。
java -jar dokka-cli-2.0.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.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
設定選項。
透過命令列選項:
java -jar dokka-cli-2.0.0.jar \
-pluginsClasspath "./dokka-base-2.0.0.jar;...;./gfm-plugin-2.0.0.jar" \
...
透過 JSON 設定:
{
...
"pluginsClasspath": [
"./dokka-base-2.0.0.jar",
"...",
"./gfm-plugin-2.0.0.jar"
],
...
}
將 GFM 外掛程式傳遞給 pluginsClasspath
後,CLI 執行器將生成 GFM 輸出格式的文件。
有關更多資訊,請參閱 Markdown 和 Javadoc 頁面。
命令列選項
要查看所有可能的命令列選項及其詳細說明,請執行:
java -jar dokka-cli-2.0.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.0.0.jar -sourceSet -help
簡要摘要:
選項 | 說明 |
---|---|
sourceSetName | 原始碼集的名稱。 |
displayName | 原始碼集的顯示名稱,內部和外部皆使用。 |
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 | 要抑制的檔案路徑。接受以分號分隔的多個路徑。 |
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.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.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
是否透過網路解析遠端檔案/連結。
這包括用於生成外部文件連結的套件列表。 例如,使標準函式庫中的類別可點擊。
將此設定為 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.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
sourceRoots
要分析和文件化的原始碼根目錄。 可接受的輸入是目錄和單個 .kt
/ .java
檔案。
classpath
用於分析和互動式範例的類別路徑。
如果某些來自依賴項的類型未自動解析/選取,這會很有用。
此選項接受 .jar
和 .klib
檔案。
samples
包含透過 @sample KDoc 標籤引用的範例函式的目錄或檔案列表。
suppressedFiles
生成文件時要抑制的檔案。
sourceLinks
僅適用於此原始碼集的原始碼連結參數集合。
有關可能選項的列表,請參閱原始碼連結設定。
perPackageOptions
此原始碼集內匹配套件特有的參數集合。
有關可能選項的列表,請參閱每個套件設定。
externalDocumentationLinks
僅適用於此原始碼集的外部文件連結參數集合。
有關可能選項的列表,請參閱外部文件連結設定。
原始碼連結設定
源連結 (sourceLinks
) 設定區塊允許您為每個簽章添加一個源連結,該連結指向帶有特定行號的 remoteUrl
。(行號可以透過設定 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
是否發出關於可見的未文件化宣告的警告,即在被 KDocs documentedVisibilities
和其他篩選器過濾後沒有 KDocs 的宣告。
此設定與 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 自動解析的替代方案。
套件列表包含有關文件和專案本身的信息, 例如模組和套件名稱。
這也可以是本地快取的檔案,以避免網路呼叫。
完整設定
下方您可以看到同時套用所有可能設定選項的範例。
{
"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"
]
}