Skip to content

CLI ​

如果出于某种原因无法使用 Gradle 或 Maven 构建工具,Dokka 提供了用于生成文档的命令行 (CLI) 运行程序。

相比之下,它的功能与 Dokka 的 Gradle 插件相同(甚至更多)。不过,由于没有自动配置,它的设置难度要大得多,尤其是在多平台和多模块环境中。

快速开始 ​

CLI 运行程序作为单独的可运行构件发布到 Maven Central。

您可以在 Maven Central 上找到它,或者直接下载。

将 dokka-cli-2.2.0.jar 文件保存到计算机后,使用 -help 选项运行它,即可查看所有可用的配置选项及其说明:

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

它也适用于某些嵌套选项,例如 -sourceSet:

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

生成文档 ​

前提条件 ​

由于没有构建工具来管理依赖项,您必须自行提供依赖项 .jar 文件。

下面列出了任何输出格式所需的依赖项:

GroupArtifactVersionLink
org.jetbrains.dokkadokka-base2.2.0下载
org.jetbrains.dokkaanalysis-kotlin-symbols2.2.0下载

以下是 HTML 输出格式所需的额外依赖项:

GroupArtifactVersionLink
org.jetbrains.kotlinxkotlinx-html-jvm0.8.0下载
org.freemarkerfreemarker2.3.31下载

使用命令行选项运行 ​

您可以传递命令行选项来配置 CLI 运行程序。

您至少需要提供以下选项:

  • -pluginsClasspath - 以分号 ; 分隔的已下载依赖项的绝对/相对路径列表
  • -sourceSet - 要为其生成文档的源代码的绝对路径
  • -outputDir - 文档输出目录的绝对/相对路径
Bash
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 配置文件的绝对/相对路径作为第一个且唯一的实参。所有其他配置选项都将从中解析。

Bash
java -jar dokka-cli-2.2.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.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 插件。为了使用它们,必须将它们置于插件类路径中。

例如,如果要以实验性的 GFM 输出格式生成文档,则需要下载 gfm-plugin 的 JAR(下载)并将其传递到 pluginsClasspath 配置选项中。

通过命令行选项:

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

通过 JSON 配置:

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

将 GFM 插件传递到 pluginsClasspath 后,CLI 运行程序将以 GFM 输出格式生成文档。

有关更多信息,请参阅 GFM 和 Javadoc 页面。

命令行选项 ​

要查看所有可用命令行选项的列表及其详细说明,请运行:

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

简要概述:

选项说明
moduleName项目/模块的名称。
moduleVersion记录在文档中的版本。
outputDir输出目录路径,默认为 ./dokka。
sourceSetDokka 源集的配置。包含嵌套配置选项。
pluginsConfigurationDokka 插件的配置。
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 配置的命令行选项列表,请运行:

Bash
java -jar dokka-cli-2.2.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要抑制的文件路径。接受以分号分隔的多个路径。
suppressAnnotatedWith用于抑制带有指定注解声明的注解完全限定名称 (FQN)。接受以分号分隔的多个值。
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.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

包含模块和软件包文档的 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.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,可以使用此项。

这可以按软件包进行配置。

可能的值:

  • 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

生成文档时要抑制的文件。

suppressAnnotatedWith

用于抑制带有指定注解声明的注解完全限定名称 (FQN) 列表。

带有这些注解之一的任何声明都将从生成的文档中排除。

sourceLinks

仅应用于此源集的源代码链接参数集。

有关可用选项的列表,请参阅源代码链接配置。

perPackageOptions

特定于此源集中匹配软件包的参数集。

有关可用选项的列表,请参阅按软件包配置。

externalDocumentationLinks

仅应用于此源集的外部文档链接参数集。

有关可用选项的列表,请参阅外部文档链接配置。

sourceLinks 配置块允许您为每个签名添加一个指向带有特定行号的 remoteUrl 的 source 链接。(行号可通过设置 remoteLineSuffix 进行配置)。

这有助于读者查找每个声明的源代码。

例如,请参阅 kotlinx.coroutines 中 count() 函数的文档。

您可以同时为所有源集配置源代码链接,也可以分别配置:

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.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"
  ]
}