HTML
HTML — это стандартный и рекомендуемый формат вывода Dokka. В настоящее время он находится в стадии бета-тестирования и приближается к стабильной версии.
Вы можете ознакомиться с примером вывода, просмотрев документацию для kotlinx.coroutines.
Генерация HTML-документации
Формат HTML поддерживается всеми запускаемыми приложениями. Для генерации HTML-документации следуйте этим шагам, в зависимости от вашего инструмента сборки или исполняемого приложения:
Для Gradle, запустите задачи
dokkaHtmlилиdokkaHtmlMultiModule.Для Maven, запустите цель
dokka:dokka.Для CLI-приложения, запустите с настроенными HTML-зависимостями.
Настройка
HTML-формат является базовым форматом Dokka, поэтому он настраивается через классы DokkaBase и DokkaBaseConfiguration.
Через безопасный 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.8.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(
// fully qualified plugin name to json configuration
"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(
// fully qualified plugin name to json configuration
["org.jetbrains.dokka.base.DokkaBase": dokkaBaseConfiguration]
)
}
<plugin>
<groupId>org.jetbrains.dokka</groupId>
<artifactId>dokka-maven-plugin</artifactId>
...
<configuration>
<pluginsConfiguration>
<!-- Fully qualified plugin name -->
<org.jetbrains.dokka.base.DokkaBase>
<!-- Options by name -->
<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.8.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}"
}
]
}
Параметры конфигурации
Ниже приведена таблица всех возможных параметров конфигурации и их назначение.
Параметр |
Описание |
|---|---|
|
Список путей к изображениям, которые должны быть включены в документацию. Изображения могут иметь любой расширение файла. Подробнее см. Настройка активов. |
|
Список путей к |
|
Путь к каталогу с пользовательскими HTML-шаблонами. Подробнее см. Шаблоны. |
|
Текст, отображаемый в нижней части страницы. |
|
Это логический параметр. Если он установлен в значение |
|
Это логический параметр. Если он установлен в значение |
Дополнительную информацию о настройке плагинов Dokka см. в разделе Настройка плагинов Dokka.
Настройка
Чтобы добавить свой собственный вид и ощущения к документации, формат HTML поддерживает ряд опций настройки.
Настройка стилей
Вы можете использовать свои собственные таблицы стилей, используя опцию customStyleSheets настройки. Они применяются ко всем страницам.
Также можно переопределить стандартные таблицы стилей Dokka, предоставив файлы с одинаковым именем:
Имя таблицы стилей |
Описание |
|---|---|
|
Основная таблица стилей, содержит большинство стилей, используемых на всех страницах |
|
Стиль логотипа заголовка |
|
Стиль для подсветки синтаксиса PrismJS |
Исходный код всех таблиц стилей Dokka доступен на GitHub.
Настройка ресурсов
Вы можете предоставить собственные изображения, которые будут включены в документацию, используя опцию customAssets настройки.
Эти файлы копируются в каталог <output>/images.
Можно переопределить изображения и значки Dokka, предоставив файлы с одинаковыми именами. Самым полезным и релевантным является logo-icon.svg, изображение, используемое в заголовке. Остальные в основном значки.
Все изображения, используемые Dokka, можно найти на GitHub.
Изменение логотипа
Чтобы настроить логотип, начните с предоставления собственного ресурса для logo-icon.svg.
Если вам не нравится его внешний вид, или вы хотите использовать файл .png, вместо стандартного файла .svg, вы можете переопределить таблицу стилей logo-styles.css, чтобы настроить его.
Пример выполнения этого действия можно найти в проекте примера пользовательского формата.
Изменение подвала
Вы можете изменить текст в подвале, используя опцию footerMessage настройки.
Шаблоны
Dokka предоставляет возможность изменить шаблоны FreeMarker, используемые для генерации страниц документации.
Вы можете полностью изменить заголовок, добавить собственные баннеры/меню/поиск, загрузить аналитику, изменить стили тела и так далее.
Dokka использует следующие шаблоны:
Шаблон |
Описание |
|---|---|
|
Определяет общий дизайн всех страниц для рендеринга. |
|
Заголовок страницы, который по умолчанию содержит логотип, версию, селектор наборов исходных кодов, переключатель тем свет/темно и поиск. |
|
Подвал страницы, содержащий опцию |
|
Метаданные, используемые в контейнере |
|
Селектор набора исходных кодов в заголовке. |
Базовый шаблон base.ftl включает все остальные перечисленные шаблоны. Исходный код всех шаблонов Dokka доступен на GitHub.
Вы можете переопределить любой шаблон, используя опцию templatesDir настройки. Dokka ищет шаблоны с точным именем в указанном каталоге. Если пользовательские шаблоны не найдены, используются стандартные шаблоны.
Переменные
Внутри всех шаблонов доступны следующие переменные:
Переменная |
Описание |
|---|---|
|
Имя страницы |
|
Текст, заданный опцией |
|
Возможный список наборов исходных кодов для страниц мультиплатформ. Каждый элемент имеет свойства |
|
Имя проекта. Доступно только внутри директивы |
|
Путь к корню от текущей страницы. Полезно для определения расположения ресурсов и доступно только внутри директивы |
Переменные projectName и pathToRoot доступны только внутри директивы template_cmd , так как требуют больше контекста и, следовательно, должны быть разрешены на более поздних этапах задачей MultiModule:
<@template_cmd name="projectName">
<span>${projectName}</span>
</@template_cmd>
Директивы
Вы также можете использовать следующие определённые Dokka директивы:
Переменная |
Описание |
|---|---|
|
Основное содержимое страницы. |
|
Ресурсы, такие как скрипты и таблицы стилей. |
|
Версия модуля, взятая из настроек. Если применяется плагин versioning, он заменяется навигатором по версиям. |
© 2010–2023 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/dokka-html.html