Kotlin 语言参考文档 中文版 Help

HTML

HTML 是 Dokka 的默认并且推荐的输出格式. 目前处于 Beta 版, 正在接近稳定发布版.

你可以浏览 kotlinx.coroutines 的文档, 看看 HTML 输出的示例.

生成 HTML 文档

所有的运行器都支持 HTML 输出格式. 要生成 HTML 文档, 请根据你的构建工具和运行器, 执行以下步骤:

  • 对于 Gradle, 运行 dokkaHtmldokkaHtmlMultiModule task.

  • 对于 Maven, 运行 dokka:dokka goal.

  • 对于 CLI 运行器, 运行 HTML 依赖项集合.

配置

HTML 格式是 Dokka 的基本格式, 因此它可以通过 DokkaBaseDokkaBaseConfiguration 类配置:

通过类型安全的 Kotlin DSL:

import org.jetbrains.dokka.base.DokkaBase import org.jetbrains.dokka.gradle.DokkaTask import org.jetbrains.dokka.base.DokkaBaseConfiguration buildscript { dependencies { classpath("org.jetbrains.dokka:dokka-base:1.9.20") } } tasks.withType<DokkaTask>().configureEach { pluginConfiguration<DokkaBase, DokkaBaseConfiguration> { customAssets = listOf(file("my-image.png")) customStyleSheets = listOf(file("my-styles.css")) footerMessage = "(c) 2022 MyOrg" separateInheritedMembers = false templatesDir = file("dokka/templates") mergeImplicitExpectActualDeclarations = false } }

通过 JSON:

import org.jetbrains.dokka.gradle.DokkaTask tasks.withType<DokkaTask>().configureEach { val dokkaBaseConfiguration = """ { "customAssets": ["${file("assets/my-image.png")}"], "customStyleSheets": ["${file("assets/my-styles.css")}"], "footerMessage": "(c) 2022 MyOrg", "separateInheritedMembers": false, "templatesDir": "${file("dokka/templates")}", "mergeImplicitExpectActualDeclarations": false } """ pluginsMapConfiguration.set( mapOf( // plugin 的完整限定名称, to, json 配置 "org.jetbrains.dokka.base.DokkaBase" to dokkaBaseConfiguration ) ) }
import org.jetbrains.dokka.gradle.DokkaTask tasks.withType(DokkaTask.class) { String dokkaBaseConfiguration = """ { "customAssets": ["${file("assets/my-image.png")}"], "customStyleSheets": ["${file("assets/my-styles.css")}"], "footerMessage": "(c) 2022 MyOrg" "separateInheritedMembers": false, "templatesDir": "${file("dokka/templates")}", "mergeImplicitExpectActualDeclarations": false } """ pluginsMapConfiguration.set( // plugin 的完整限定名称, :, json 配置 ["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration] ) }
<plugin> <groupId>org.jetbrains.dokka</groupId> <artifactId>dokka-maven-plugin</artifactId> ... <configuration> <pluginsConfiguration> <!-- plugin 的完整限定名称 --> <org.jetbrains.dokka.base.DokkaBase> <!-- 选项名称 --> <customAssets> <asset>${project.basedir}/my-image.png</asset> </customAssets> <customStyleSheets> <stylesheet>${project.basedir}/my-styles.css</stylesheet> </customStyleSheets> <footerMessage>(c) MyOrg 2022 Maven</footerMessage> <separateInheritedMembers>false</separateInheritedMembers> <templatesDir>${project.basedir}/dokka/templates</templatesDir> <mergeImplicitExpectActualDeclarations>false</mergeImplicitExpectActualDeclarations> </org.jetbrains.dokka.base.DokkaBase> </pluginsConfiguration> </configuration> </plugin>

通过 命令行选项:

java -jar dokka-cli-1.9.20.jar \ ... -pluginsConfiguration "org.jetbrains.dokka.base.DokkaBase={\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false} "

通过 JSON 配置:

{ "moduleName": "Dokka Example", "pluginsConfiguration": [ { "fqPluginName": "org.jetbrains.dokka.base.DokkaBase", "serializationFormat": "JSON", "values": "{\"customAssets\": [\"my-image.png\"], \"customStyleSheets\": [\"my-styles.css\"], \"footerMessage\": \"(c) 2022 MyOrg\", \"separateInheritedMembers\": false, \"templatesDir\": \"dokka/templates\", \"mergeImplicitExpectActualDeclarations\": false}" } ] }

配置选项

下表包括所有可以使用的配置选项, 以及它们的用途.

选项

描述

customAssets

要与文档绑定到一起的图片资源的路径列表. 图片资源可以使用任意的文件扩展名. 更多详情请参见 自定义资源.

customStyleSheets

要与文档绑定到一起并在显示时使用的 .css 样式表的路径列表. 更多详情请参见 自定义样式表.

templatesDir

包含自定义 HTML 模板的目录路径. 更多详情请参见 模板.

footerMessage

在页脚显示的文字.

separateInheritedMembers

这是一个 boolean 选项. 如果设置为 true, Dokka 会将属性/函数与继承的属性/继承的函数分开显示. 这个设置默认关闭.

mergeImplicitExpectActualDeclarations

这是一个 boolean 选项. 如果设置为 true, Dokka 合并那些没有声明为 expect/actual 的声明, 但使用相同的完整限定名称. 这个设置对旧的代码库可能很有用. 这个设置默认关闭.

关于 Dokka plugin 配置的更多详情, 请参见 配置 Dokka plugins.

自定义

为了帮助你为你的文档添加自己的外观和风格, HTML 格式支持很多的自定义选项.

自定义样式表

你可以使用 customStyleSheets 配置选项, 使用你自己的样式表. 这些配置会被应用于所有的页面.

可以通过提供相同名称的文件来覆盖 Dokka 的默认样式表:

样式表名称

描述

style.css

主样式表, 包含在所有页面中使用的大部分样式

logo-styles.css

页头 logo 样式

prism.css

用于 PrismJS 语法高亮度显示器的样式

Dokka 所有样式表的源代码, 请参见 GitHub.

自定义资源

你可以使用 customAssets 配置选项, 提供你自己的绑定到文档的图片.

这些文件会被复制到 <output>/images 目录.

可以通过提供相同名称的文件来覆盖 Dokka 的图片和图标. 最重要的是 logo-icon.svg, 它是用于页头的图片. 其他主要是图标.

Dokka 使用的所有图片, 请参见 GitHub.

要自定义 logo, 你可以从 提供你自己的 logo-icon.svg 资源 开始.

如果你不喜欢它的外观, 或者你想要使用 .png 文件, 而不是默认的 .svg 文件, 你可以 覆盖 logo-styles.css 样式表 来定制它.

具体的例子, 请参见我们的 自定义格式的示例项目.

你可以使用 footerMessage 配置选项, 修改页脚中的文字.

模板

Dokka 提供了修改用于生成文档页面的 FreeMarker 模板的能力.

你可以完全彻底的修改页头, 添加你的自己的横幅/菜单/搜索, 负载析, 修改页面 body 样式, 等等等等.

Dokka 使用以下模板:

模板

描述

base.ftl

定义显示的所有页面的通常设计.

includes/header.ftl

页头, 默认包含 logo, 版本, 源代码集选择器, 浅色/深色主题切换, 以及搜索.

includes/footer.ftl

页脚, 包含 footerMessage 配置选项, 以及版权信息.

includes/page_metadata.ftl

<head> 容器内使用的元数据.

includes/source_set_selector.ftl

页头中的 源代码集 选择器.

基础模板是 base.ftl, 它引入(include)其它所有模板. Dokka 所有模板的源代码请参见 GitHub.

你可以使用 templatesDir 配置选项 覆盖任何一个模板. Dokka 会在指定的目录搜索指定的模板名称. 如果无法找到用户定义的模板, 它会使用默认模板.

变量

下表是在所有模板内可以使用的变量:

变量

描述

${pageName}

页面名称

${footerMessage}

footerMessage 配置选项 设置的文字

${sourceSets}

用于对跨平台页面的 源代码集 List, 可为 null. List 中的每个元素包含 name, platform, 和 filter 属性.

${projectName}

项目名称. 只能在 template_cmd 命令内使用.

${pathToRoot}

从当前页面到根的路径. 可以用于定位资源, 只能在 template_cmd 命令内使用.

变量 projectNamepathToRoot 只能在 template_cmd 命令内使用, 因为它们需要更多的上下文信息, 因此需要在更晚的阶段由 MultiModule task 解析:

<@template_cmd name="projectName"> <span>${projectName}</span> </@template_cmd>

命令

你也可以使用下面这些由 Dokka 定义的 命令:

变量

描述

<@content/>

主页面内容.

<@resources/>

资源, 例如脚本和样式表.

<@version/>

从配置得到的模块版本. 如果应用了 versioning plugin, 它会被替换为一个版本导航器.

最终更新: 2024/10/17