Publish sources and javadoc for bdk-android

[kirillzh]

Problem

It seems that sources and javadocs for bdk-android are not being generated and published to maven:
https://repo1.maven.org/maven2/org/bitcoindevkit/bdk-android/0.4.0.

Description

When using bdk-android as a library in your project it's not currently possible to look up source code and documentation of bdk-android because sources and javadocs are not being generated and published.

With AGP 7.1.0 publishing Android sources and javadocs is very simple, we can use that https://developer.android.com/studio/releases/gradle-plugin#build-variant-publishing.

Alternatives

No response

[notmandatory]

Since the Kotlin code for this project is auto generated by uniffi-rs and that project isn't currently able to take docs from the original rust project and translate them into the generated native languages docs. But @thunderbiscuit has #31 to semi-automate keeping the Kotlin docs up-to-date. Once this goes in our current publish task should publish them to maven central.

[kirillzh]

Once this goes in our current publish task should publish them to maven central.

It looks like only bdk-jvm artifact is configured to publish sources and javadoc right now, not the bdk-android so that still needs to be configured: #33. But I guess since Dokka (yay!) is going to be used instead of javadoc we probably cannot use withJavadocJar() that comes with maven-publish in AGP 7.1.0 and might need to write custom task to pull out dokka docs (using dokkaJavadoc) as its own artifact (which is easy): Kotlin/dokka#42 (comment).

[thunderbiscuit]

@kirillzh if you have experience building those types of docs I'd love to discuss more with you! My current process works but is not... ideal (described in #18), and I wonder if I could optimize it, or even automate it (I don't have high hopes for full automation at the moment, but you never know).

[thunderbiscuit]

I'm playing around with the answers proposed in in your link above but so far unable to replace the javadoc jar with the dokka docs.

The build script is unable to find the task task javadocJar in the :android project, which prevents me from fiddling around with it.

(trying something like this:)

tasks.named<Jar>("javadocJar") {
    classifier = "javadoc"
    from("$buildDir/dokka/html")
}

[kirillzh]

The build script is unable to find the task task javadocJar in the :android project

Right, that's because maven publish plugin in AGP pre-7.1.0 does not know how to work with javadocs, #33 should fix that. I unfortunately don't have a ton of experience setting up dokka... Your custom task looks right but I wonder if it should depend on dokkaJavadoc task directly to ensure that $buildDir/dokka/html exists? Unsure if that's the problem but wondering if this version works (assuming #33 is applied)?

val javadocJar = tasks.named<Jar>("javadocJar") {
  archiveClassifier.set("javadoc")
  from(tasks.named("dokkaJavadoc"))
}

[thunderbiscuit]

Yeah no that was me testing your PR #33 actually! That's why I was a bit puzzled by it. You bumped AGP to 7.1.2 and it's still not finding it.

When I print the list of tasks available under :android I see javaDocReleaseJar (don't remember that one, but I think it is definitely added by the plugin), but even that doesn't get found when I search by name using the tasks.named(), so not sure what is going on there.

Also I get the same error when running your code block above (I tried it just in case it would fix it but no dice).

[kirillzh]

When I print the list of tasks available under :android I see javaDocReleaseJar

@thunderbiscuit, I think this is because publishing is only configured for release build variant:

publishing {
    singleVariant("release") {
        withSourcesJar()
        withJavadocJar()
    }
}

If we want to configure it for all variants we can do it like so:

publishing {
    multipleVariants {
        withSourcesJar()
        withJavadocJar()
        allVariants()
    }
}

Which now generates tasks in all variants:

$ ./gradlew tasks --all
...
android:javaDocDebugGeneration
android:javaDocDebugJar
android:javaDocReleaseGeneration
android:javaDocReleaseJar
...

When I ran ./gradlew :android:publishToMavenLocal -x signMavenPublication locally I see it correctly generating and publishing sources and javadoc in my local maven, so I wonder if signMavenPublication is somehow set up to work in release variant. 🤔

[kirillzh]

Also, I just tried generating local bdk-kotlin and applying docs with dokka on #18 branch + this changes from this PR and I see documentation as part of aar now which is amazing! 🎉

On high level, this is what it looks like when I jump to BDK definitions (e.g.BitcoinTime) from https://github.com/thunderbiscuit/devkit-wallet repo. It now has a comment which was not there before:

[thunderbiscuit]

@kirillzh Ha it's funny I was also playing with the multipleVariants block to see if it made a difference for the grabbing of the task and adding the dokka docs. It adds tasks and all, but I still can't apply the proposed fixes in the thread you linked to. Anyway, problem for tomorrow me.

As for the inline docs, that's awesome. I hadn't even taken a look myself yet. And honestly because I'm still vetting the workflow, I haven't invested time in actually writing and porting the full docs from the bdk library, but there is a lot more that we'll be able to bring once we're happy with the PR in #31. So that's awesome signal.