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

Question

背景

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

因此，目前我在Jitpack存储库中放置的文件就是：

• jitpack.yml -告诉您要使用哪些文件
• 库-Relase.aar-(模糊的)代码本身
• pom-default.xml -依赖项和一些其他配置。

问题所在

虽然依赖关系问题和AAR文件本身都很好，而且我可以使用库，但我注意到我无法找到一种方法来向使用它的人提供我在那里编写的KDoc (比如JavaDocs，但对于Kotlin)。

我试过的

除了各种分级任务之外，我还尝试了使用Android本身的简单操作来生成它。由于没有提到KDoc，所以我使用了Tools->Generate JavaDocs。

不幸的是，它告诉我没有，而且确实报告了这里。

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

问题是

我希望这是可能的，但是如何使用Jitpack上的maven生成&公共KDoc呢？

Answer 1

作为Android开发的新手，我花了很长时间才弄明白，所以想花点时间来分享我的发现。

发布aar库以及文档的解决方案是将"sources.jar“工件与您的aar一起打包。如果您熟悉iOS，那么sources.jar本质上将充当您的代码的头文件，在这里您可以使用它公开您的无限制的库API和KDocs。当使用Android /Gradle的用户下载您的库时，它将自动拉入您的sources.jar，并能够将您的KDocs链接到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发布来运行这个任务，并将它作为工件包含到我们的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的)来说，这个过程的文档化程度很低，这确实有点荒谬，尽管大多数已发布的库似乎都已经搞清楚了。

Answer 2

您需要使用Dokka来自动记录Kotlin项目。您可以在这篇文章上找到对Dokka的简短解释，如果需要的话也可以阅读文档。

使用Gradle插件 首选的方法是使用插件块。 build.gradle.kts: plugins { id("org.jetbrains.dokka")版本"1.4.32“}存储库{ mavenCentral() } 插件将dokkaHtml、dokkaJavadoc、dokkaGfm和dokkaJekyll任务添加到项目中。应用插件 Dokka插件以dokka${format}Plugin的形式为每种输出格式创建Gradle配置： 依赖项{ dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.4.32") } 您还可以创建一个自定义Dokka任务，并直接在其中添加插件： 通过创建(DokkaTask：：customDokkaTask ){customDokkaTask{customDokkaTask}} 请注意，dokkaJavadoc任务只正确地记录单个jvm源代码集。 若要生成文档，请使用适当的dokka${format} Gradle任务： ./gradlew dokkaHtml 有关示例，请参见Dokka Gradle示例项目。 确保您在com.android.library和kotlin-android之后应用了Dokka。 buildscript {依赖项{ classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlin_version}") classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}") }}存储库{ mavenCentral() }应用(plugin= "com.android.library")应用(plugin= "kotlin-android")应用(plugin= "org.jetbrains.dokka") dokkaHtml.configure { dokkaSourceSets {命名("main") { noAndroidSdkLink.set(false) }}

更多的官方GitHub回购- https://github.com/Kotlin/dokka，你可能也喜欢这篇文章。