CLI

最终更新: 2025/02/06

如果你由于某些原因无法使用 Gradle 或 Maven 构建工具, Dokka 有一个命令行(CLI)运行器用来生成文档.

与 Gradle plugin for Dokka 相比, 它拥有相同甚至更多的能力. 但它更加难于设置, 因为没有自动配置, 尤其是对于跨平台和多模块环境.

入门

CLI 运行器作为单独的可执行 artifact 发布到 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 文件.

对于所有的输出格式, 你所需要的依赖项如下:

Group

Artifact

版本

链接

org.jetbrains.dokka

dokka-base

2.0.0

下载

org.jetbrains.dokka

analysis-kotlin-descriptors

2.0.0

下载

对于 HTML 输出格式, 你需要的额外的依赖项如下:

Group

Artifact

版本

链接

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 配置文件的绝对/相对路径, 作为第一个也是唯一一个参数. 所有其它的配置选项都从 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 artifact 只包含 HTML 输出格式.

其他所有输出格式都以 Dokka plugin 的形式实现. 要使用这些格式, 你需要将它们添加到 plugin classpath.

例如, 如果你想要使用试验性的 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"
  ],
  ...
}

通过传递给 pluginsClasspath 的 GFM plugin, CLI 运行器会使用 GFM 输出格式生成文档.

更多详情, 请参见 Markdown 和 Javadoc 章节.

命令行选项

要查看所有可用的命令行选项列表, 以及它们的详细描述, 请运行:

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

简单的总结如下:

选项

描述

moduleName

项目/模块名称.

moduleVersion

需要生成文档的版本.

outputDir

输出目录路径, 默认值为 ./dokka.

sourceSet

对 Dokka 源代码集的配置. 包含嵌套的配置选项.

pluginsConfiguration

对 Dokka plugin 的配置.

pluginsClasspath

Dokka plugin 以及它们的依赖项的 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 Service 之间的全局的对应. 可以接受多个路径, 以分号分隔.

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

设置代码分析和示例环境时使用的 Kotlin 语言版本.

apiVersion

设置代码分析和示例环境时使用的 Kotlin API 版本.

noStdlibLink

是否生成指向 Kotlin 标准库的链接.

noJdkLink

是否生成指向 JDK Javadoc 的链接.

suppressedFiles

需要禁止输出的文件路径. 可以接受多个路径, 以分号分隔.

analysisPlatform

设置代码分析环境时使用的平台.

perPackageOptions

包源代码集配置列表, 格式为 matchingRegexp,-deprecated,-privateApi,+warnUndocumented,+suppress;.... 可以接受多个值, 以分号分隔.

externalDocumentationLinks

外部文档链接, 格式为 {url}^{packageListUrl}. 可以接受多个值, 以 ^^ 分隔.

srcLink

源代码目录与用于浏览源代码的 Web Service 之间的对应. 可以接受多个路径, 以分号分隔.

JSON 配置

下面是对每个配置小节的一些示例和详细解释. 在本章的最后, 你还可以看到一个示例, 它使用了 所有的配置选项.

一般配置

{
  "moduleName": "Dokka Example",
  "moduleVersion": null,
  "outputDir": "./build/dokka/html",
  "failOnWarning": false,
  "suppressObviousFunctions": true,
  "suppressInheritedMembers": false,
  "offlineMode": false,
  "includes": [
    "module.md"
  ],
  "sourceLinks":  [
    { "_comment": "参见其它章节" }
  ],
  "perPackageOptions": [
    { "_comment": "参见其它章节" }
  ],
  "externalDocumentationLinks":  [
    { "_comment": "参见其它章节" }
  ],
  "sourceSets": [
    { "_comment": "参见其它章节" }
  ],
  "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"
  ]
}

源代码集配置

如何配置 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.1.0.jar",
        "libs/kotlin-stdlib-common-2.1.0.jar"
      ],
      "samples": [
        "samples/basic.kt"
      ],
      "suppressedFiles": [
        "src/main/kotlin/org/jetbrains/dokka/Suppressed.kt"
      ],
      "sourceLinks":  [
        { "_comment": "参见其它章节" }
      ],
      "perPackageOptions": [
        { "_comment": "参见其它章节" }
      ],
      "externalDocumentationLinks":  [
        { "_comment": "参见其它章节" }
      ]
    }
  ]
}

源代码链接配置

sourceLinks 配置块可以用来为每个签名添加 source 链接, 链接地址是带有特定代码行的 remoteUrl. (代码行可以通过 remoteLineSuffix 进行配置).

这样可以帮助读者找到每个声明的源代码.

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

你可以对所有的源代码集一起配置源代码链接, 也可以 分别配置:

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

各包配置

perPackageOptions 配置块可以对指定的包设置一些选项, 包通过 matchingRegex 来匹配.

你可以对所有的源代码集一起添加包配置, 也可以 分别配置:

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

外部文档链接配置

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

完整的配置

下面的例子中, 你可以看到同时使用了所有的配置选项.

{
  "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.0.jar",
        "libs/kotlin-stdlib-common-2.1.0.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"
  ]
}