Spec-Zone.ru › Kotlin 1.9

HTML

HTML — это стандартный и рекомендуемый формат вывода Dokka. В настоящее время он находится в стадии бета-тестирования и приближается к стабильной версии.

Вы можете ознакомиться с примером вывода, просмотрев документацию для kotlinx.coroutines.

Генерация HTML-документации

Формат HTML поддерживается всеми запускаемыми приложениями. Для генерации HTML-документации следуйте этим шагам, в зависимости от вашего инструмента сборки или исполняемого приложения:

  • Для Gradle, запустите задачи dokkaHtml или dokkaHtmlMultiModule.

  • Для Maven, запустите цель dokka:dokka.

  • Для CLI-приложения, запустите с настроенными HTML-зависимостями.

HTML-страницы, сгенерированные в этом формате, должны быть размещены на веб-сервере для правильного отображения.

Вы можете использовать любые бесплатные услуги хостинга статических сайтов, такие как GitHub Pages.

В локальном режиме вы можете использовать встроенный веб-сервер IntelliJ IDE.

Настройка

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

Параметры конфигурации

Ниже приведена таблица всех возможных параметров конфигурации и их назначение.

Параметр

Описание

customAssets

Список путей к изображениям, которые должны быть включены в документацию. Изображения могут иметь любой расширение файла. Подробнее см. Настройка активов.

customStyleSheets

Список путей к .css стилям, которые должны быть включены в документацию и использоваться для рендеринга. Подробнее см. Настройка стилей.

templatesDir

Путь к каталогу с пользовательскими HTML-шаблонами. Подробнее см. Шаблоны.

footerMessage

Текст, отображаемый в нижней части страницы.

separateInheritedMembers

Это логический параметр. Если он установлен в значение true, Dokka отображает свойства/функции и унаследованные свойства/унаследованные функции отдельно. По умолчанию отключено.

mergeImplicitExpectActualDeclarations

Это логический параметр. Если он установлен в значение true, Dokka объединяет объявления, которые не объявлены как expect/actual, но имеют одинаковое полное имя. Это может быть полезно для устаревших кодовых баз. По умолчанию отключено.

Дополнительную информацию о настройке плагинов Dokka см. в разделе Настройка плагинов Dokka.

Настройка

Чтобы добавить свой собственный вид и ощущения к документации, формат HTML поддерживает ряд опций настройки.

Настройка стилей

Вы можете использовать свои собственные таблицы стилей, используя опцию customStyleSheets настройки. Они применяются ко всем страницам.

Также можно переопределить стандартные таблицы стилей Dokka, предоставив файлы с одинаковым именем:

Имя таблицы стилей

Описание

style.css

Основная таблица стилей, содержит большинство стилей, используемых на всех страницах

logo-styles.css

Стиль логотипа заголовка

prism.css

Стиль для подсветки синтаксиса 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

Определяет общий дизайн всех страниц для рендеринга.

includes/header.ftl

Заголовок страницы, который по умолчанию содержит логотип, версию, селектор наборов исходных кодов, переключатель тем свет/темно и поиск.

includes/footer.ftl

Подвал страницы, содержащий опцию footerMessage настройки и авторские права.

includes/page_metadata.ftl

Метаданные, используемые в контейнере <head>.

includes/source_set_selector.ftl

Селектор набора исходных кодов в заголовке.

Базовый шаблон base.ftl включает все остальные перечисленные шаблоны. Исходный код всех шаблонов Dokka доступен на GitHub.

Вы можете переопределить любой шаблон, используя опцию templatesDir настройки. Dokka ищет шаблоны с точным именем в указанном каталоге. Если пользовательские шаблоны не найдены, используются стандартные шаблоны.

Переменные

Внутри всех шаблонов доступны следующие переменные:

Переменная

Описание

${pageName}

Имя страницы

${footerMessage}

Текст, заданный опцией footerMessage настройки

${sourceSets}

Возможный список наборов исходных кодов для страниц мультиплатформ. Каждый элемент имеет свойства name, platform, и filter.

${projectName}

Имя проекта. Доступно только внутри директивы template_cmd.

${pathToRoot}

Путь к корню от текущей страницы. Полезно для определения расположения ресурсов и доступно только внутри директивы template_cmd.

Переменные projectName и pathToRoot доступны только внутри директивы template_cmd , так как требуют больше контекста и, следовательно, должны быть разрешены на более поздних этапах задачей MultiModule:

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

Директивы

Вы также можете использовать следующие определённые Dokka директивы:

Переменная

Описание

<@content/>

Основное содержимое страницы.

<@resources/>

Ресурсы, такие как скрипты и таблицы стилей.

<@version/>

Версия модуля, взятая из настроек. Если применяется плагин versioning, он заменяется навигатором по версиям.

Последнее изменение: 25 июля 2023 г.
Командная строка Markdown

© 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

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API