Dokka多模块项目中自定义模块URL路径的配置方法

Dokka作为Kotlin项目的文档生成工具，在处理多模块项目时提供了灵活的配置选项。本文将详细介绍如何自定义模块在生成文档中的URL路径，而不仅仅是修改显示名称。

问题背景

在多模块项目中，开发者有时需要自定义模块在文档中的显示名称和URL路径。虽然通过moduleName参数可以修改模块的显示名称，但默认情况下URL路径仍然保持与源代码模块名一致。这可能导致文档URL与显示名称不一致的问题。

解决方案

Dokka提供了modulePath配置项来解决这个问题。该参数允许开发者完全控制模块在生成文档中的路径表现，而不仅仅是显示名称。

配置示例

在Gradle构建脚本中，可以这样配置：

dokkaHtml {
    moduleName.set("自定义显示名称")
    modulePath.set("custom-path")
}

这个配置会同时影响：

1. 文档中显示的模块名称（由moduleName控制）
2. 文档生成的URL路径结构（由modulePath控制）

实际效果

配置后生成的文档将具有以下特点：

• 页面标题和导航栏显示"自定义显示名称"
• 所有相关链接使用"custom-path"作为路径基础
• 保持文档内部链接的正确性

注意事项

1. 路径设置应避免使用特殊字符和空格
2. 确保各模块的路径唯一性，避免冲突
3. 路径变更会影响已有的文档链接，需考虑兼容性

最佳实践

对于大型多模块项目，建议：

• 建立统一的路径命名规范
• 在项目文档中记录模块路径映射关系
• 在CI流程中验证路径唯一性

通过合理使用modulePath配置，开发者可以创建更加专业和一致的API文档结构，提升团队协作效率和文档可用性。