如何通过Maven仓库正确分发Kotlin JVM库的Kdocs？

核心错误 #

你当前只上传了Dokka生成的单个index.html文件，但Dokka输出的是完整的HTML文档站点（包含CSS、JS、子页面等资源文件），单独的index.html既无法正常导航，也不符合Maven仓库对javadoc构件的格式要求——IDEA期望的是打包成*-javadoc.jar的完整文档包。

正确配置步骤 #

1. 添加Dokka文档打包任务 #

在build.gradle.kts中注册任务，将Dokka生成的HTML目录打包为javadoc jar：

// 生成javadoc jar（包含完整Dokka HTML文档）
tasks.register<Jar>("dokkaHtmlJar") {
    dependsOn(tasks.dokkaHtml)
    from(tasks.dokkaHtml.get().outputDirectory)
    archiveClassifier.set("javadoc")
}

// 可选：生成sources jar（方便IDEA查看源码）
tasks.register<Jar>("sourcesJar") {
    from(kotlin.sourceSets.main.get().kotlin.srcDirs)
    archiveClassifier.set("sources")
}

2. 修改Maven发布配置 #

不再手动指定本地jar文件，而是通过Gradle组件和任务引用正确的构件：

publishing {
    repositories {
        repsy()
    }
    publications {
        create("main", MavenPublication::class.java) {
            artifactId = project.name
            version = project.version as String
            groupId = project.group as String
            
            // 自动关联主jar构件
            from(components["java"])
            
            // 添加javadoc jar和sources jar
            artifact(tasks.named("dokkaHtmlJar"))
            artifact(tasks.named("sourcesJar")) // 可选但推荐
        }
    }
}

3. 验证发布结果 #

执行发布任务后，你的Maven仓库应该包含三个构件：

• {project-name}-{version}.jar（主库）
• {project-name}-{version}-javadoc.jar（文档包）
• {project-name}-{version}-sources.jar（源码包，可选）

此时IDEA会自动下载javadoc.jar，通过Ctrl+Q就能正常查看Kdocs，文档的内部导航也能正常工作。

额外说明 #

• 不要手动指定本地jar路径（如file("./build/libs/...")），通过components["java"]可以让Gradle自动关联编译产出的主jar，避免路径硬编码带来的问题。
• Dokka的dokkaHtml任务默认输出到build/dokka/html，打包任务会自动依赖该任务，确保先生成文档再打包。

内容的提问来源于stack exchange，提问作者David Zhubrev