Переход на плагин Dokka Gradle v2

Проверьте поддерживаемые версии

Убедитесь, что ваш проект соответствует минимальным требованиям к версиям:

Включите DGP v2

Обновите версию Dokka до 2.2.0 в блоке plugins {} файла build.gradle.kts вашего проекта:

plugins {
    kotlin("jvm") version "2.1.10"
    id("org.jetbrains.dokka") version "2.2.0"
}

Кроме того, для включения плагина Dokka Gradle v2 можно использовать каталог версий.

Включите помощники миграции

В файле gradle.properties проекта задайте следующее свойство Gradle, чтобы активировать DGP v2 с помощниками:

org.jetbrains.dokka.experimental.gradle.pluginMode=V2EnabledWithHelpers

Это свойство активирует плагин DGP v2 с помощниками миграции. Эти помощники предотвращают ошибки компиляции, если в скриптах сборки есть ссылки на задачи из DGP v1, которые больше недоступны в DGP v2.

После завершения миграции отключите помощники миграции.

Синхронизируйте проект с Gradle

После включения DGP v2 и помощников миграции синхронизируйте проект с Gradle, чтобы убедиться, что DGP v2 применен правильно:

• Если вы используете IntelliJ IDEA, нажмите кнопку Перезагрузить все проекты Gradle в окне инструмента Gradle.

• Если вы используете Android Studio, выберите Файл | Синхронизировать проект с файлами Gradle.

Настройте параметры конфигурации

В DGP v2 изменены некоторые параметры конфигурации Gradle. В файле build.gradle.kts настройте параметры конфигурации в соответствии с конфигурацией вашего проекта.

tasks.withType<DokkaTask>().configureEach {
    suppressInheritedMembers.set(true)
    failOnWarning.set(true)
    dokkaSourceSets {
        named("main") {
            moduleName.set("Project Name")
            includes.from("README.md")
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(URL("https://example.com/src"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

tasks.dokkaHtml {
    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
        customStyleSheets.set(listOf("styles.css"))
        customAssets.set(listOf("logo.png"))
        footerMessage.set("(c) Your Company")
    }
}

// build.gradle.kts

dokka {
    moduleName.set("Project Name")
    dokkaPublications.html {
        suppressInheritedMembers.set(true)
        failOnWarning.set(true)
    }
    dokkaSourceSets.main {
        includes.from("README.md")
        sourceLink {
            localDirectory.set(file("src/main/kotlin"))
            remoteUrl("https://example.com/src")
            remoteLineSuffix.set("#L")
        }
    }
    pluginsConfiguration.html {
        customStyleSheets.from("styles.css")
        customAssets.from("logo.png")
        footerMessage.set("(c) Your Company")
    }
}

// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension
import org.jetbrains.dokka.gradle.engine.plugins.DokkaHtmlPluginParameters

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")

        project.extensions.configure(DokkaExtension::class.java) { dokka ->

            dokka.dokkaPublications.named("html") { publication ->
                publication.suppressInheritedMembers.set(true)
                publication.failOnWarning.set(true)
            }

            dokka.dokkaSourceSets.named("main") { dss ->
                dss.includes.from("README.md")
                dss.sourceLink {
                    it.localDirectory.set(project.file("src/main/kotlin"))
                    it.remoteUrl("https://example.com/src")
                    it.remoteLineSuffix.set("#L")
                }
            }

            dokka.pluginsConfiguration.named("html", DokkaHtmlPluginParameters::class.java) { html ->
                html.customStyleSheets.from("styles.css")
                html.customAssets.from("logo.png")
                html.footerMessage.set("(c) Your Company")
            }
        }
    }
}

import org.jetbrains.dokka.DokkaConfiguration.Visibility

// ...
documentedVisibilities.set(
    setOf(Visibility.PUBLIC)
) 

import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier

// ...
documentedVisibilities.set(
    setOf(VisibilityModifier.Public)
)

// OR

documentedVisibilities(VisibilityModifier.Public)

fun documentedVisibilities(vararg visibilities: VisibilityModifier): Unit =
    documentedVisibilities.set(visibilities.asList()) 

tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets {
        named("main") {
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(URL("https://github.com/your-repo"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

// build.gradle.kts

dokka {
    dokkaSourceSets.main {
        sourceLink {
            localDirectory.set(file("src/main/kotlin"))
            remoteUrl("https://github.com/your-repo")
            remoteLineSuffix.set("#L")
        }
    }
}

// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")
        project.extensions.configure(DokkaExtension::class.java) { dokka ->
            dokka.dokkaSourceSets.named("main") { dss ->
                dss.includes.from("README.md")
                dss.sourceLink {
                    it.localDirectory.set(project.file("src/main/kotlin"))
                    it.remoteUrl("https://example.com/src")
                    it.remoteLineSuffix.set("#L")
                }
            }
        }
    }
}

remoteUrl.set(URL("https://github.com/your-repo"))

remoteUrl.set(URI("https://github.com/your-repo"))

// or

remoteUrl("https://github.com/your-repo")

fun remoteUrl(@Language("http-url-reference") value: String): Unit =
    remoteUrl.set(URI(value))

// and

fun remoteUrl(value: Provider<String>): Unit =
    remoteUrl.set(value.map(::URI))

tasks.dokkaHtml {
    dokkaSourceSets {
        configureEach {
            externalDocumentationLink {
                url = URL("https://example.com/docs/")
                packageListUrl = File("/path/to/package-list").toURI().toURL()
            }
        }
    }
}

dokka {
    dokkaSourceSets.configureEach {
        externalDocumentationLinks.register("example-docs") {
            url("https://example.com/docs/")
            packageListUrl("https://example.com/docs/package-list")
        }
    }
}

customAssets = listOf(file("example.png"), file("example2.png"))

customAssets.from("example.png", "example2.png")

tasks.dokkaHtml {
    outputDirectory.set(layout.buildDirectory.dir("dokkaDir"))
}

dokka {
    dokkaPublications.html {
        outputDirectory.set(layout.buildDirectory.dir("dokkaDir"))
    }
}

tasks.dokkaHtmlMultiModule {
    outputDirectory.set(rootDir.resolve("docs/api/0.x"))
    includes.from(project.layout.projectDirectory.file("README.md"))
}

// build.gradle.kts

dokka {
    dokkaPublications.html {
        outputDirectory.set(rootDir.resolve("docs/api/0.x"))
        includes.from(project.layout.projectDirectory.file("README.md"))
    }
}

// CustomPlugin.kt

import org.gradle.api.Plugin
import org.gradle.api.Project
import org.jetbrains.dokka.gradle.DokkaExtension

abstract class CustomPlugin : Plugin<Project> {
    override fun apply(project: Project) {
        project.plugins.apply("org.jetbrains.dokka")
        project.extensions.configure(DokkaExtension::class.java) { dokka ->
            dokka.dokkaPublications.named("html") { html ->
                html.outputDirectory.set(project.rootDir.resolve("docs/api/0.x"))
                html.includes.from(project.layout.projectDirectory.file("README.md"))
            }
        }
    }
}

Настройте плагины Dokka

Настройка встроенных плагинов Dokka с помощью JSON устарела и заменена типобезопасным DSL. Это изменение улучшает совместимость с системой инкрементальной сборки Gradle и отслеживание входных данных задач.

Конфигурация в DGP v1:

В DGP v1 плагины Dokka настраивались вручную с помощью JSON. Такой подход вызывал проблемы с регистрацией входных данных задач для проверок актуальности в Gradle.

Ниже приведен пример устаревшей конфигурации на основе JSON для плагина управления версиями Dokka:

tasks.dokkaHtmlMultiModule {
    pluginsMapConfiguration.set(
        mapOf(
            "org.jetbrains.dokka.versioning.VersioningPlugin" to """
                { "version": "1.2", "olderVersionsDir": "$projectDir/dokka-docs" }
                """.trimIndent()
        )
    )
}

Конфигурация в DGP v2:

В DGP v2 плагины Dokka настраиваются с помощью типобезопасного DSL. Чтобы настроить плагины Dokka типобезопасным способом, используйте блок pluginsConfiguration{}:

dokka {
    pluginsConfiguration {
        versioning {
            version.set("1.2")
            olderVersionsDir.set(projectDir.resolve("dokka-docs"))
        }
    }
}

Пример конфигурации DGP v2 см. в разделе плагин управления версиями Dokka.

DGP v2 позволяет расширять свои возможности, настраивая пользовательские плагины. Пользовательские плагины позволяют выполнять дополнительную обработку или изменять процесс создания документации.

Общий доступ к конфигурации Dokka для подпроектов

В DPG v2 больше не используются subprojects {} или allprojects {} для предоставления общего доступа к конфигурации подпроектов. В будущих версиях Gradle использование этих подходов приведет к ошибкам.

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

После предоставления общего доступа к конфигурации Dokka можно объединить документацию нескольких подпроектов в один результат. Дополнительные сведения см. в разделе Обновление агрегации документации в проектах с несколькими модулями.

plugins {
    id("dokka-convention")
}

Обновите агрегацию документации в проектах с несколькими модулями

Dokka может объединять документацию нескольких подпроектов в один результат или публикацию.

Как объяснялось ранее, перед агрегацией документации примените плагин Dokka ко всем подпроектам, для которых создается документация.

В DGP v2 для агрегации используется блок dependencies {} вместо задач; его можно добавить в любой файл build.gradle.kts.

В DGP v1 агрегация неявно создавалась в корневом проекте. Чтобы воспроизвести это поведение в DGP v2, добавьте блок dependencies {} в файл build.gradle.kts корневого проекта.

Агрегация в DGP v1:

    tasks.dokkaHtmlMultiModule {
        // ...
    }

Агрегация в DGP v2:

dependencies {
    dokka(project(":some-subproject:"))
    dokka(project(":another-subproject:"))
}

Измените каталог агрегированной документации

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

В DGP v2 механизм агрегации обновлен для лучшего соответствия соглашениям Gradle. Теперь DGP v2 сохраняет полный путь к каталогу подпроекта, чтобы избежать конфликтов при агрегации документации в любом месте.

Каталог агрегации в DGP v1:

В DGP v1 агрегированная документация помещалась в каталог с упрощенной структурой. Например, если в проекте агрегация выполняется в :turbo-lib и есть вложенный подпроект :turbo-lib:maths, созданная документация помещалась по следующему пути:

turbo-lib/build/dokka/html/maths/

Каталог агрегации в DGP v2:

DGP v2 сохраняет полную структуру проекта, обеспечивая уникальный каталог для каждого подпроекта. Теперь та же агрегированная документация имеет следующую структуру:

turbo-lib/build/dokka/html/turbo-lib/maths/

Это изменение предотвращает конфликты между подпроектами с одинаковыми именами. Однако из-за изменения структуры каталогов внешние ссылки могут устареть, что может привести к ошибкам 404.

// /turbo-lib/maths/build.gradle.kts

plugins {
    id("org.jetbrains.dokka")
}

dokka {
    // Overrides the subproject directory to match the V1 structure
    modulePath.set("maths")
}

Создайте документацию с помощью обновленной задачи

В DGP v2 переименованы задачи Gradle, создающие документацию API.

Задача в DGP v1:

./gradlew dokkaHtml

// or

./gradlew dokkaHtmlMultiModule

Задача в DGP v2:

./gradlew :dokkaGenerate

Задача dokkaGenerate создает документацию API в каталоге build/dokka/.

В DGP v2 задача dokkaGenerate работает как для проектов с одним модулем, так и для проектов с несколькими модулями. Для создания вывода в формате HTML, Javadoc или одновременно в обоих форматах можно использовать разные задачи. Дополнительные сведения см. в разделе Выбор формата вывода документации.

Выберите формат вывода документации

Формат вывода DGP v2 по умолчанию — HTML. Однако можно выбрать создание документации API в формате HTML, Javadoc или одновременно в обоих форматах:

1. Поместите соответствующий плагин id в блок plugins {} файла build.gradle.kts проекта:

   plugins {
       // Generates HTML documentation
       id("org.jetbrains.dokka") version "2.2.0"
   
       // Generates Javadoc documentation
       id("org.jetbrains.dokka-javadoc") version "2.2.0"
   
       // Keeping both plugin IDs generates both formats
   }
   

2. Запустите соответствующую задачу Gradle.

Ниже приведен список плагинов id и задач Gradle для каждого формата:

Если вы используете IntelliJ IDEA, может отображаться задача Gradle dokkaGenerateHtml. Эта задача является псевдонимом задачи dokkaGeneratePublicationHtml. Обе задачи выполняют совершенно одинаковую операцию.

Учитывайте устаревшие и удаленные возможности

• Поддержка форматов вывода: DGP v2 поддерживает только форматы вывода HTML и Javadoc. Экспериментальные форматы, такие как Markdown и Jekyll, больше не поддерживаются.

• Задача-сборщик: задача DokkaCollectorTask удалена. Теперь нужно отдельно создавать документацию для каждого подпроекта, а затем при необходимости агрегировать документацию.

Установите флаг opt-in

После успешной миграции установите следующий флаг opt-in без вспомогательных средств в файле проекта gradle.properties:

org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled

Если вы удалили ссылки на задачи Gradle из DGP v1, которые больше недоступны в DGP v2, ошибок компиляции, связанных с этим, возникнуть не должно.

Включите кэш сборки и кэш конфигурации

Теперь DGP v2 поддерживает кэш сборки и кэш конфигурации Gradle, что повышает производительность сборки.

• Чтобы включить кэш сборки, следуйте инструкциям в документации по кэшу сборки Gradle.

• Чтобы включить кэш конфигурации, следуйте инструкциям в документации по кэшу конфигурации Gradle.