Merge pull request #249 from NordicSemiconductor/migration/dokka

Migration from JavaDoc to Dokka for released modules

Author: philips77

gradle/libs.versions.toml

@@ -79,7 +79,7 @@ nordic-mcumgr = "1.9.2"
 nordic-scanner = "1.6.0"
 nordic-common = "2.0.0"
 nordic-memfault = "1.0.2"
-nordicPlugins = "2.2.4"
+nordicPlugins = "2.3"
 dokkaPlugin = "1.9.20"
 googleServicesPlugins = "4.4.0"
 firebaseCrashlyticsPlugins = "2.9.9"
@@ -244,6 +244,7 @@ nordic-blek-uiscanner = { group = "no.nordicsemi.android.kotlin.ble", name = "ui
 android-gradlePlugin = { group = "com.android.tools.build", name = "gradle", version.ref = "androidGradlePlugin" }
 kotlin-gradlePlugin = { group = "org.jetbrains.kotlin", name = "kotlin-gradle-plugin", version.ref = "kotlin" }
 compose-gradlePlugin = { module = "org.jetbrains.kotlin:compose-compiler-gradle-plugin", version.ref = "kotlin" }
+dokka-gradlePlugin = { group = "org.jetbrains.dokka", name = "dokka-gradle-plugin", version.ref = "dokkaPlugin" }
 
 [plugins]
 nordic-application = { id = "no.nordicsemi.android.plugin.application", version.ref = "nordicPlugins" }

plugins/build.gradle.kts

@@ -1,5 +1,3 @@
-import org.jetbrains.kotlin.js.translate.context.Namer.kotlin
-
 /*
  * Copyright (c) 2022, Nordic Semiconductor
  * All rights reserved.
@@ -58,6 +56,7 @@ dependencies {
     compileOnly(libs.android.gradlePlugin)
     compileOnly(libs.kotlin.gradlePlugin)
     compileOnly(libs.compose.gradlePlugin)
+    compileOnly(libs.dokka.gradlePlugin)
 }
 
 gradlePlugin {

plugins/src/main/kotlin/AndroidNexusRepositoryPlugin.kt

@@ -38,10 +38,15 @@ import org.gradle.api.Plugin
 import org.gradle.api.Project
 import org.gradle.api.publish.PublishingExtension
 import org.gradle.api.publish.maven.MavenPublication
+import org.gradle.api.tasks.bundling.Jar
 import org.gradle.kotlin.dsl.extra
 import org.gradle.kotlin.dsl.get
 import org.gradle.kotlin.dsl.getByType
+import org.gradle.kotlin.dsl.register
+import org.gradle.kotlin.dsl.withType
 import org.gradle.plugins.signing.SigningExtension
+import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.kotlin.gradle.tasks.Kapt
 
 class AndroidNexusRepositoryPlugin : Plugin<Project> {
 
@@ -51,6 +56,7 @@ class AndroidNexusRepositoryPlugin : Plugin<Project> {
                 apply("com.android.library")
                 apply("maven-publish")
                 apply("signing")
+                apply("org.jetbrains.dokka")
             }
 
             // Default Nordic group.
@@ -69,10 +75,27 @@ class AndroidNexusRepositoryPlugin : Plugin<Project> {
             library.publishing {
                 singleVariant("release") {
                     withSourcesJar()
-                    withJavadocJar()
+                    // Javadoc fails with Java 17:
+                    // https://github.com/Kotlin/dokka/issues/2956
+                    // withJavadocJar()
                 }
             }
 
+            // Instead, configure Dokka to generate HTML docs.
+            tasks.withType<DokkaTask>().configureEach {
+                dependsOn(tasks.withType<Kapt>())
+                dokkaSourceSets.configureEach {
+                    noAndroidSdkLink.set(false)
+                }
+            }
+
+            tasks.register<Jar>("dokkaHtmlJar").configure {
+                val dokkaHtml = tasks.named("dokkaHtml", DokkaTask::class.java)
+                dependsOn(dokkaHtml)
+                from(dokkaHtml.flatMap { it.outputDirectory })
+                archiveClassifier.set("html-docs")
+            }
+
             afterEvaluate {
                 publishing {
                     repositories {
@@ -100,6 +123,8 @@ class AndroidNexusRepositoryPlugin : Plugin<Project> {
                                 from(nexusPluginExt)
                                 packaging = "aar"
                             }
+                            // Add Dokka HTML docs.
+                            artifact(tasks.named("dokkaHtmlJar"))
                         }
                         // This task will add *.asc files to the publication for all artifacts.
                         signing.sign(publication)

plugins/src/main/kotlin/JvmNexusRepositoryPlugin.kt

@@ -38,10 +38,15 @@ import org.gradle.api.Project
 import org.gradle.api.plugins.JavaPluginExtension
 import org.gradle.api.publish.PublishingExtension
 import org.gradle.api.publish.maven.MavenPublication
+import org.gradle.api.tasks.bundling.Jar
 import org.gradle.kotlin.dsl.extra
 import org.gradle.kotlin.dsl.get
 import org.gradle.kotlin.dsl.getByType
+import org.gradle.kotlin.dsl.register
+import org.gradle.kotlin.dsl.withType
 import org.gradle.plugins.signing.SigningExtension
+import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.kotlin.gradle.tasks.Kapt
 
 class JvmNexusRepositoryPlugin : Plugin<Project> {
 
@@ -51,6 +56,7 @@ class JvmNexusRepositoryPlugin : Plugin<Project> {
                 apply("org.jetbrains.kotlin.jvm")
                 apply("maven-publish")
                 apply("signing")
+                apply("org.jetbrains.dokka")
             }
 
             // Default Nordic group.
@@ -67,7 +73,24 @@ class JvmNexusRepositoryPlugin : Plugin<Project> {
 
             // Create a software component with the release variant.
             library.withSourcesJar()
-            library.withJavadocJar()
+            // Javadoc fails with Java 17:
+            // https://github.com/Kotlin/dokka/issues/2956
+            // library.withJavadocJar()
+
+            // Instead, configure Dokka to generate HTML docs.
+            tasks.withType<DokkaTask>().configureEach {
+                dependsOn(tasks.withType<Kapt>())
+                dokkaSourceSets.configureEach {
+                    noAndroidSdkLink.set(false)
+                }
+            }
+
+            tasks.register<Jar>("dokkaHtmlJar").configure {
+                val dokkaHtml = tasks.named("dokkaHtml", DokkaTask::class.java)
+                dependsOn(dokkaHtml)
+                from(dokkaHtml.flatMap { it.outputDirectory })
+                archiveClassifier.set("html-docs")
+            }
 
             afterEvaluate {
                 publishing {
@@ -96,6 +119,8 @@ class JvmNexusRepositoryPlugin : Plugin<Project> {
                                 from(nexusPluginExt)
                                 packaging = "jar"
                             }
+                            // Add Dokka HTML docs.
+                            artifact(tasks.named("dokkaHtmlJar"))
                         }
                         // This task will add *.asc files to the publication for all artifacts.
                         signing.sign(publication)