Add Dokka for Javadoc generation and enhance publishing. (#17)

Introduce Dokka plugin to Gradle builds for generating Javadoc artifacts. Replace hardcoded publication logic with more modular and conditional setups. Update GitHub workflows to add publication steps and improve naming consistency.
lamba92 · Dec 15, 2024 · 32c608a · 32c608a
1 parent 134e7e7
commit 32c608a
Show file tree

Hide file tree

Showing 6 changed files with 103 additions and 46 deletions.
diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
@@ -4,12 +4,12 @@ on:
     branches:
       - master
 
-name: Test and lint
+name: Verify
 
 jobs:
   check-android:
     runs-on: ubuntu-latest
-    name: Android tests
+    name: Tests / Android
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
@@ -37,7 +37,7 @@ jobs:
 
   lint:
     runs-on: ubuntu-latest
-    name: Linting check
+    name: Linting
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-java@v4
@@ -53,7 +53,7 @@ jobs:
       matrix:
         os: [ubuntu, windows, macos]
     runs-on: ${{ matrix.os }}-latest
-    name: "Native, JVM, JS tests on ${{ matrix.os }}"
+    name: Tests / ${{ matrix.os == 'ubuntu' && 'Ubuntu' || matrix.os == 'windows' && 'Windows' || matrix.os == 'macos' && 'macOs' }}
     steps:
     - uses: actions/checkout@v4
     - uses: actions/setup-java@v4
@@ -64,3 +64,19 @@ jobs:
     - uses: gradle/actions/setup-gradle@v4
     - name: Run tests
       run: ./gradlew allTests
+
+  publication:
+    strategy:
+      matrix:
+        os: [ ubuntu, windows, macos ]
+    runs-on: ${{ matrix.os }}-latest
+    name: Publishing / ${{ matrix.os == 'ubuntu' && 'Ubuntu' || matrix.os == 'windows' && 'Windows' || matrix.os == 'macos' && 'macOs' }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gradle/actions/setup-gradle@v4
+      - run: chmod +x gradlew
+      - uses: actions/setup-java@v4
+        with:
+          distribution: adopt
+          java-version: 21
+      - run: ./gradlew publishAllPublicationsToTestRepository --stacktrace
diff --git a/buildSrc/src/main/kotlin/kotlin-jvm-convention.gradle.kts b/buildSrc/src/main/kotlin/kotlin-jvm-convention.gradle.kts
@@ -4,10 +4,12 @@ import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
 import kotlin.io.path.ExperimentalPathApi
 import kotlin.io.path.absolutePathString
+import org.jetbrains.kotlin.gradle.internal.builtins.StandardNames.FqNames.target
 
 plugins {
     kotlin("jvm")
     kotlin("plugin.serialization")
+    id("org.jetbrains.dokka")
     id("versions")
 }
 

diff --git a/buildSrc/src/main/kotlin/kotlin-multiplatform-convention.gradle.kts b/buildSrc/src/main/kotlin/kotlin-multiplatform-convention.gradle.kts
@@ -12,11 +12,10 @@ import kotlin.io.path.deleteRecursively
 plugins {
     kotlin("multiplatform")
     kotlin("plugin.serialization")
+    id("org.jetbrains.dokka")
     id("versions")
 }
 
-val currentOs: OperatingSystem = OperatingSystem.current()
-
 kotlin {
     sourceSets.silenceOptIns()
     jvmToolchain(8)
@@ -65,27 +64,4 @@ tasks {
             showStackTraces = true
         }
     }
-
-    // in CI we only want to publish the artifacts for the current OS only
-    // but when developing we want to publish all the possible artifacts to test them
-    if (isCi) {
-
-        val linuxNames = listOf("linux", "android", "jvm", "js", "kotlin", "metadata", "wasm")
-        val windowsNames = listOf("mingw", "windows")
-        val appleNames = listOf("macos", "ios", "watchos", "tvos")
-
-        withType<AbstractPublishToMaven> {
-            when {
-                name.containsAny(linuxNames) -> onlyIf { currentOs.isLinux }
-                name.containsAny(windowsNames) -> onlyIf { currentOs.isWindows }
-                name.containsAny(appleNames) -> onlyIf { currentOs.isMacOsX }
-            }
-        }
-    }
 }
-
-val isCi
-    get() = System.getenv("CI") == "true"
-
-fun String.containsAny(strings: List<String>, ignoreCase: Boolean = true): Boolean =
-    strings.any { contains(it, ignoreCase) }
diff --git a/buildSrc/src/main/kotlin/kotlin-multiplatform-with-android-convention.gradle.kts b/buildSrc/src/main/kotlin/kotlin-multiplatform-with-android-convention.gradle.kts
@@ -1,7 +1,6 @@
 @file:OptIn(ExperimentalPathApi::class, ExperimentalKotlinGradlePluginApi::class)
 
 import com.android.build.gradle.tasks.factory.AndroidUnitTest
-import gradle.kotlin.dsl.accessors._f5ffce11a4b5604b3d89b5ef03ba37e3.android
 import kotlin.io.path.ExperimentalPathApi
 import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
 import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSetTree

diff --git a/buildSrc/src/main/kotlin/publishing-convention.gradle.kts b/buildSrc/src/main/kotlin/publishing-convention.gradle.kts
@@ -1,18 +1,47 @@
+import gradle.kotlin.dsl.accessors._5110d0ad46c3465a3034c0fe268105a5.kotlin
 import kotlin.io.path.Path
 import kotlin.io.path.readText
+import org.gradle.internal.os.OperatingSystem
 
 plugins {
-    id("org.jetbrains.dokka")
     id("org.jlleitschuh.gradle.ktlint")
     `maven-publish`
     signing
 }
 
-val javadocJar by tasks.registering(Jar::class) {
-    dependsOn(tasks.dokkaGeneratePublicationHtml)
-    archiveClassifier = "javadoc"
-    from(tasks.dokkaGeneratePublicationHtml)
-    destinationDirectory = layout.buildDirectory.dir("artifacts")
+val kotlinPlugins = listOf(
+    "org.jetbrains.kotlin.jvm",
+    "org.jetbrains.kotlin.multiplatform"
+)
+
+kotlinPlugins.forEach { kotlinPluginId ->
+    plugins.withId(kotlinPluginId) {
+        plugins.withId("org.jetbrains.dokka") {
+            val javadocJar by tasks.registering(Jar::class) {
+                dependsOn("dokkaGeneratePublicationHtml")
+                archiveClassifier = "javadoc"
+                from("dokkaGeneratePublicationHtml")
+                destinationDirectory = layout.buildDirectory.dir("artifacts")
+            }
+            publishing {
+                publications.withType<MavenPublication> {
+                    artifact(javadocJar)
+                }
+            }
+            if ("jvm" in kotlinPluginId) {
+                val sourcesJar by tasks.registering(Jar::class) {
+                    archiveClassifier = "sources"
+                    from(kotlin.sourceSets.getByName("main").kotlin)
+                    destinationDirectory = layout.buildDirectory.dir("artifacts")
+                }
+                publishing {
+                    publications.withType<MavenPublication> {
+                        artifact(sourcesJar)
+                    }
+                }
+            }
+        }
+    }
 }
 
 publishing {
@@ -22,13 +51,7 @@ publishing {
         }
     }
     publications.withType<MavenPublication> {
-
-        // the publishing plugin is old AF and does not support lazy
-        // properties, so we need to set the artifactId after the
-        // publication is created
-        afterEvaluate { artifactId = "kotlin-document-store-$artifactId" }
-
-        artifact(javadocJar)
+        artifactId = "kotlin-document-store-$artifactId"
         pom {
             name = "kotlin-document-store"
             description = "Kotlin Multiplatform NoSQL document storage"
@@ -66,6 +89,7 @@ signing {
         System.getenv("SIGNING_PASSWORD")
             ?: project.properties["central.signing.privateKeyPassword"] as? String
             ?: return@signing
+    logger.lifecycle("Signing enabled")
     useInMemoryPgpKeys(privateKey, password)
     sign(publishing.publications)
 }
@@ -76,4 +100,28 @@ tasks {
     withType<PublishToMavenRepository> {
         dependsOn(withType<Sign>())
     }
+
+    // in CI we only want to publish the artifacts for the current OS only
+    // but when developing we want to publish all the possible artifacts to test them
+    if (isCi) {
+
+        val linuxNames = listOf("linux", "android", "jvm", "js", "kotlin", "metadata", "wasm")
+        val windowsNames = listOf("mingw", "windows")
+        val appleNames = listOf("macos", "ios", "watchos", "tvos")
+        val currentOs: OperatingSystem = OperatingSystem.current()
+
+        withType<AbstractPublishToMaven> {
+            when {
+                name.containsAny(linuxNames) -> onlyIf { currentOs.isLinux }
+                name.containsAny(windowsNames) -> onlyIf { currentOs.isWindows }
+                name.containsAny(appleNames) -> onlyIf { currentOs.isMacOsX }
+            }
+        }
+    }
 }
+
+val isCi
+    get() = System.getenv("CI") == "true"
+
+fun String.containsAny(strings: List<String>, ignoreCase: Boolean = true): Boolean =
+    strings.any { contains(it, ignoreCase) }
diff --git a/version-catalog/build.gradle.kts b/version-catalog/build.gradle.kts
@@ -2,15 +2,16 @@ import kotlin.io.path.createDirectories
 import kotlin.io.path.writeText
 
 plugins {
-    versions
+    `publishing-convention`
     `version-catalog`
-    `maven-publish`
+    versions
 }
 
 val output = layout.buildDirectory.file("libs.versions.toml")
 val replaceVersion by tasks.registering {
     val input = file("libs.versions.toml")
     inputs.file(input)
+    outputs.file(output)
     doLast {
         output.get()
             .asPath
@@ -36,11 +37,26 @@ catalog {
     }
 }
 
+val sourcesJar by tasks.registering(Jar::class) {
+    dependsOn(replaceVersion)
+    archiveClassifier = "sources"
+    from(replaceVersion)
+    destinationDirectory = layout.buildDirectory.dir("artifacts")
+}
+
+val javadocJar by tasks.registering(Jar::class) {
+    dependsOn(replaceVersion)
+    archiveClassifier = "javadoc"
+    from(replaceVersion)
+    destinationDirectory = layout.buildDirectory.dir("artifacts")
+}
+
 publishing {
     publications {
         create<MavenPublication>(rootProject.name) {
-            artifactId = "kotlin-document-store-version-catalog"
             from(components["versionCatalog"])
+            artifact(sourcesJar)
+            artifact(javadocJar)
         }
     }
 }