如何在 Jitpack 上使用 maven 为 Kotlin 库发布 KDoc？

Question

背景

经过大量的研究和尝试，并寻求帮助，我已经成功地在 Jitpack 上使用 maven 发布了一个私有的 Github 存储库（写在这里）。

所以，目前我放在 Jitpack 存储库中的文件只是这些：

• jitpack.yml - 告诉使用哪些文件
• library-release.aar -（混淆的）代码本身
• pom-default.xml - 依赖项和其他一些配置。

问题

虽然依赖问题和 AAR 文件本身很好，我可以使用该库，但我注意到我找不到一种方法将我在那里编写的内容作为 KDoc（如 JavaDocs，但适用于 Kotlin）提供给使用它的任何人。

我试过的

除了各种gradle任务，我还尝试了Android Studio本身的简单操作来制作。由于没有提到 KDoc，我使用Tools->Generate JavaDocs代替。

可悲的是，它告诉我没有，而且确实是在这里报道的。

但即使它确实成功了，我也不知道如何将它与其他文件一起发布。

问题

我希望这是可能的，但是如何在 Jitpack 上使用 maven 生成和公开 KDoc？

Answer 1

作为一个相对较新的 Android 开发者，我花了很长时间才弄清楚这一点，所以想花时间分享我的发现。

与文档一起发布 aar 库的解决方案是将“sources.jar”工件与 aar 一起打包。如果您熟悉 iOS，那么 resources.jar 本质上将充当代码的头文件，您可以在其中公开未缩小的库 API 和 KDocs。当使用 Android Studio/Gradle 的用户下载您的库时，它将自动提取您的sources.jar，并能够将您的 aar 链接到 IDE 中的 KDocs。

在您的 build.gradle 中，确保您使用的是“maven-publish”。

创建一个新任务来构建您的sources.jar。由于我正在使用闭源代码，因此我不想公开整个库，因此我手动选择了包含公共 API 及其文档的特定文件：

task androidSourcesJar(type: Jar) {
  group("documentation")
  classifier("sources")
  def sdkDir = "$projectDir/src/main/java/com/project/sdk"
  def publicAPI = ["$sdkDir/MyLibAPI.kt",
                   "$sdkDir/MyLibData.kt",
                   "$sdkDir/MyLibNotificationInterface.kt",
                   "$sdkDir/utils",
  from publicAPI
}

从那里，我们需要 Maven-publish 来运行此任务并将其作为工件包含到我们的 Maven 存储库中。每个人的 Maven 发布设置看起来都有点不同，但只需添加artifact(tasks["androidSourcesJar"])到您的发布块即可。我的看起来像这样：

publishing {
  publications {
    aar(MavenPublication) {
        artifactId = "mylib"
        artifact(tasks["androidSourcesJar"])
        artifact("$buildDir/outputs/aar/mylib-release.aar")
        ... (additional setup)
    }
  }
}

从那里您可以照常发布您的 aar，新创建的 source.jar 将与其一起发布，从而允许您的用户访问您的 Kdocs

就是这样。对我（来自 iOS）来说，这个过程的记录确实有点荒谬，尽管大多数已发布的库似乎已经弄清楚了这一点。