feat: generate and publish docs (#320)

Author: stainless-app[bot]

README.md

@@ -3,14 +3,15 @@
 <!-- x-release-please-start-version -->
 
 [![Maven Central](https://img.shields.io/maven-central/v/com.withorb.api/orb-java)](https://central.sonatype.com/artifact/com.withorb.api/orb-java/0.45.0)
+[![javadoc](https://javadoc.io/badge2/com.withorb.api/orb-java/0.45.0/javadoc.svg)](https://javadoc.io/doc/com.withorb.api/orb-java/0.45.0)
 
 <!-- x-release-please-end -->
 
 The Orb Java SDK provides convenient access to the Orb REST API from applications written in Java.
 
 The Orb Java SDK is similar to the Orb Kotlin SDK but with minor differences that make it more ergonomic for use in Java, such as `Optional` instead of nullable values, `Stream` instead of `Sequence`, and `CompletableFuture` instead of suspend functions.
 
-The REST API documentation can be found on [docs.withorb.com](https://docs.withorb.com/reference/api-reference).
+The REST API documentation can be found on [docs.withorb.com](https://docs.withorb.com/reference/api-reference). Javadocs are also available on [javadoc.io](https://javadoc.io/doc/com.withorb.api/orb-java/0.45.0).
 
 ## Installation
 

build.gradle.kts

@@ -1,4 +1,23 @@
+plugins {
+    id("org.jetbrains.dokka") version "2.0.0"
+}
+
+repositories {
+    mavenCentral()
+}
+
 allprojects {
     group = "com.withorb.api"
     version = "0.45.0" // x-release-please-version
 }
+
+subprojects {
+    apply(plugin = "org.jetbrains.dokka")
+}
+
+// Avoid race conditions between `dokkaJavadocCollector` and `dokkaJavadocJar` tasks
+tasks.named("dokkaJavadocCollector").configure {
+    subprojects.flatMap { it.tasks }
+        .filter { it.project.name != "orb-java" && it.name == "dokkaJavadocJar" }
+        .forEach { mustRunAfter(it) }
+}

buildSrc/src/main/kotlin/orb.publish.gradle.kts

@@ -1,3 +1,5 @@
+import com.vanniktech.maven.publish.JavadocJar
+import com.vanniktech.maven.publish.KotlinJvm
 import com.vanniktech.maven.publish.MavenPublishBaseExtension
 import com.vanniktech.maven.publish.SonatypeHost
 
@@ -19,6 +21,12 @@ configure<MavenPublishBaseExtension> {
     publishToMavenCentral(SonatypeHost.CENTRAL_PORTAL)
 
     coordinates(project.group.toString(), project.name, project.version.toString())
+    configure(
+        KotlinJvm(
+            javadocJar = JavadocJar.Dokka("dokkaJavadoc"),
+            sourcesJar = true,
+        )
+    )
 
     pom {
         name.set("API Reference")

orb-java/build.gradle.kts

@@ -6,3 +6,24 @@ plugins {
 dependencies {
     api(project(":orb-java-client-okhttp"))
 }
+
+// Redefine `dokkaJavadoc` to:
+// - Depend on the root project's task for merging the docs of all the projects
+// - Forward that task's output to this task's output
+tasks.named("dokkaJavadoc").configure {
+    actions.clear()
+
+    val dokkaJavadocCollector = rootProject.tasks["dokkaJavadocCollector"]
+    dependsOn(dokkaJavadocCollector)
+
+    val outputDirectory = project.layout.buildDirectory.dir("dokka/javadoc")
+    doLast {
+        copy {
+            from(dokkaJavadocCollector.outputs.files)
+            into(outputDirectory)
+            duplicatesStrategy = DuplicatesStrategy.INCLUDE
+        }
+    }
+
+    outputs.dir(outputDirectory)
+}