Kotlin Dokka 文档生成工具迁移指南：从v1到v2版本

【免费下载链接】dokka API documentation engine for Kotlin 项目地址: https://gitcode.com/gh_mirrors/do/dokka

概述

Kotlin Dokka 是一个功能强大的文档生成工具，专门为Kotlin项目设计，能够处理Kotlin的KDoc注释和Java的Javadoc注释，生成结构化的HTML或Javadoc格式文档。随着Dokka 2.0.0的发布，全新的Gradle插件v2版本带来了显著的改进和优化。

为什么需要迁移到v2版本

Dokka Gradle插件v2（DGP v2）是一个实验性功能，它带来了以下重要改进：

1. 性能提升：采用Gradle原生类型，显著提高构建效率
2. 配置简化：使用直观的顶层DSL配置，取代了低级的任务配置方式
3. 多项目管理优化：采用声明式文档聚合方式，简化多项目文档管理
4. 类型安全：插件配置完全类型安全，提高构建脚本的可靠性
5. 缓存支持：全面支持Gradle配置缓存和构建缓存

迁移前的准备工作

版本要求检查

在开始迁移前，请确保您的项目满足以下最低版本要求：

工具	最低版本要求
Gradle	7.6或更高
Android Gradle插件	7.0或更高
Kotlin Gradle插件	1.9或更高

启用DGP v2

在项目的build.gradle.kts文件中更新Dokka版本：

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

启用迁移助手

在项目的gradle.properties文件中添加以下配置：

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

这个设置会激活迁移助手，防止构建脚本中引用的v1任务在v2中不可用导致的编译错误。

迁移步骤详解

配置选项调整

顶层DSL配置

v2版本使用更简洁的顶层DSL配置：

dokka {
    moduleName.set("项目名称")
    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")
        }
    }
}

可见性设置

v2版本中可见性设置有所变化：

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

documentedVisibilities.set(setOf(VisibilityModifier.Public))

源代码链接

源代码链接配置现在更加简洁：

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

外部文档链接

外部文档链接的注册方式更加规范：

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

插件配置

v2版本弃用了JSON配置方式，改用类型安全的DSL：

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

多项目配置策略

不使用约定插件的情况

在根项目的build.gradle.kts中：

subprojects {
    apply(plugin = "org.jetbrains.dokka")
    
    extensions.configure<DokkaExtension> {
        // 共享配置
    }
}

使用约定插件的情况

1. 创建build-logic子项目
2. 在约定插件中定义Dokka配置
3. 在各模块中应用约定插件

迁移后的验证

完成迁移后，建议：

1. 运行文档生成任务验证输出
2. 检查所有自定义配置是否生效
3. 确认多模块文档聚合功能正常工作

常见问题解答

Q: 迁移过程中遇到任务找不到的错误怎么办？

A: 确保已正确启用迁移助手，并检查是否所有v1任务引用都已更新为v2等效配置。

Q: 多模块项目的文档聚合不工作怎么办？

A: 检查根项目的配置是否正确，并确保所有子项目都应用了Dokka插件。

Q: 自定义样式和资源不显示怎么办？

A: 确认资源路径正确，并使用新的customAssets.from()语法配置。

总结

Dokka Gradle插件v2版本带来了显著的改进，虽然迁移过程可能需要一些调整，但最终会带来更简洁的配置、更好的性能和更可靠的构建体验。按照本指南的步骤，您可以顺利完成从v1到v2的迁移。

【免费下载链接】dokka API documentation engine for Kotlin 项目地址: https://gitcode.com/gh_mirrors/do/dokka