How do you publish KDoc for a Kotlin library using maven on Jitpack?

Question

Background

After a lot of researching and trying out, and also asking for help, I've succeeded publishing a private Github repository using maven on Jitpack (written here).

So, currently the files that I put on the repository for Jitpack are just these:

• jitpack.yml - tells which files to use
• library-release.aar - the (obfuscated) code itself
• pom-default.xml - the dependencies and some other configurations.

The problem

While dependencies issues and the AAR file itself are fine and I can use the library, I've noticed I can't find a way to offer what I wrote there as KDoc (like JavaDocs, but for Kotlin) to whoever uses it.

What I've tried

Besides the various gradle tasks, I've also tried the simple operation of Android Studio itself to produce it. Since there is no mention of KDoc, I used Tools->Generate JavaDocs instead.

Sadly, it told me there are none, and indeed it was reported here.

But even if it did succeed, I wouldn't have known how to publish it together with the rest of the files.

The question

I hope it's possible, but how can I generate&public KDoc using maven on Jitpack?

Answer 1

As someone relatively new to Android development, this took me a long time to figure out, so wanted to take the time to share what I found.

The solution for publishing aar libraries along with the documentation is to package a "sources.jar" artifact along with your aar. 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. When a user with Android Studio/Gradle downloads your library, it will automatically pull in your sources.jar, and be able to link your aar to your KDocs within the IDE.

In your build.gradle, make sure you are using 'maven-publish'.

Create a new task that will build your sources.jar. Since I'm working with closed source, I didn't want to expose my entire library, so I hand select specific files that comprise my public API and its documentation:

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
}

From there, we need Maven-publish to run this task and include it as an artifact to our maven repository. Everyone's maven publish setup looks a bit different, but simply add artifact(tasks["androidSourcesJar"]) to your publication block. Mine looked something like this:

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

From there you can publish your aar as usual and the newly created source.jar will be published alongside it, allowing your users to access your Kdocs

That's it. It does seem a bit absurd to me (coming from iOS) how poorly documented this process is, even though most published libraries seem to have figured it out.