如何在 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 。

可悲的是，它告訴我沒有，而且確實在這里報道過。

但即使它確實成功了，我也不知道如何將它與文件的 rest 一起發布。

問題

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

Answer 1

您需要使用 Dokka 自動記錄 Kotlin 項目。 您可以在本文中找到 Dokka 的簡要說明，並在需要時閱讀文檔。

使用 Gradle 插件

首選方法是使用插件塊。

 build.gradle.kts: plugins { id("org.jetbrains.dokka") version "1.4.32" } repositories { mavenCentral() }

該插件將dokkaHtml 、 dokkaJavadoc 、 dokkaGfm和dokkaJekyll任務添加到項目中。

應用插件

Dokka 插件以dokka${format}Plugin的形式為每個 output 格式創建 Gradle 配置：

 dependencies { dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.4.32") }

您還可以創建自定義 Dokka 任務並直接在其中添加插件：

 val customDokkaTask by creating(DokkaTask::class) { dependencies { plugins("org.jetbrains.dokka:kotlin-as-java-plugin:1.4.32") } }

請注意，dokkaJavadoc 任務將僅正確記錄單個 jvm 源集

要生成文檔，請使用適當的 dokka${format} Gradle 任務：

 ./gradlew dokkaHtml

有關示例，請參閱 Dokka Gradle 示例項目。

確保在com.android.library和kotlin-android之后應用 Dokka。

 buildscript { dependencies { classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlin_version}") classpath("org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}") } } repositories { mavenCentral() } apply(plugin= "com.android.library") apply(plugin= "kotlin-android") apply(plugin= "org.jetbrains.dokka") dokkaHtml.configure { dokkaSourceSets { named("main") { noAndroidSdkLink.set(false) } } }

更多在官方 GitHub repo - https://github.com/Kotlin/dokka你也可能喜歡這篇文章。

Answer 2

作為一個對Android開發比較陌生的人，這花了我很長時間才弄清楚，所以想花時間分享我的發現。

與文檔一起發布 aar 庫的解決方案是將 package 與您的 aar 一起發布為“sources.jar”工件。 If you're familiar with iOS, then the sources.jar will essentially act as your header files for your code, where you can expose your unminified library API and KDocs with it. 當使用 Android Studio/Gradle 的用戶下載您的庫時，它將自動拉入您的源代碼。jar，並能夠將您的 aar 鏈接到 Z581D6381F3F35E4F364D77201ACFZ7 中的 KDocs。

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

創建一個將構建您的源代碼的新任務。jar。 由於我使用的是封閉源代碼，我不想公開我的整個庫，所以我提交了包含我的公共 API 及其文檔的 select 特定文件：

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 和新創建的源。jar 將與它一起發布，允許您的用戶訪問您的 Kdocs

而已。 對我（來自 iOS）來說，這個過程記錄得多么糟糕似乎有點荒謬，盡管大多數已發布的庫似乎已經弄清楚了。