Merge pull request #352 from SpineEventEngine/extend-dokka-support

Extend Dokka support

buildSrc/build.gradle.kts

@@ -93,6 +93,16 @@ val errorProneVersion = "2.0.2"
  */
 val protobufPluginVersion = "0.8.18"
 
+/**
+ * The version of Dokka Gradle Plugins.
+ *
+ * Please keep in sync with [io.spine.internal.dependency.Dokka.version].
+ *
+ * @see <a href="https://github.com/Kotlin/dokka/releases">
+ *     Dokka Releases</a>
+ */
+val dokkaVersion = "1.6.10"
+
 dependencies {
     implementation("com.fasterxml.jackson.core:jackson-databind:$jacksonVersion")
     implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-xml:$jacksonVersion")
@@ -105,4 +115,6 @@ dependencies {
     implementation("net.ltgt.gradle:gradle-errorprone-plugin:${errorProneVersion}")
     implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:${kotlinVersion}")
     implementation("gradle.plugin.com.google.protobuf:protobuf-gradle-plugin:$protobufPluginVersion")
+    implementation("org.jetbrains.dokka:dokka-gradle-plugin:${dokkaVersion}")
+    implementation("org.jetbrains.dokka:dokka-base:${dokkaVersion}")
 }

buildSrc/src/main/kotlin/dokka-for-java.gradle.kts

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2022, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+import io.spine.internal.dependency.Dokka
+import java.time.LocalDate
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.DokkaBaseConfiguration
+import org.jetbrains.dokka.gradle.DokkaTask
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+dependencies {
+    /**
+     * To generate the documentation as seen from Java perspective, the kotlin-as-java plugin was
+     * added to the Dokka's classpath.
+     *
+     * @see <a href="https://github.com/Kotlin/dokka#output-formats">
+     *     Dokka output formats</a>
+     */
+    dokkaPlugin(Dokka.KotlinAsJavaPlugin.lib)
+
+    /**
+     * To exclude pieces of code annotated with `@Internal` from the documentation a custom plugin
+     * is added to the Dokka's classpath.
+     *
+     * @see <a href="https://github.com/SpineEventEngine/dokka-tools/tree/master/dokka-extensions">
+     *     Custom Dokka Plugins</a>
+     */
+    dokkaPlugin(Dokka.SpineExtensions.lib)
+}
+
+tasks.withType<DokkaTask>().configureEach {
+    dokkaSourceSets.configureEach {
+        skipEmptyPackages.set(true)
+    }
+
+    outputDirectory.set(buildDir.resolve("docs/dokka"))
+
+    val dokkaConfDir = rootDir.resolve("buildSrc/src/main/resources/dokka")
+
+    /**
+     * Dokka Base plugin allows to set a few properties to customize the output:
+     *
+     * - `customStyleSheets` property to which we can pass our css files overriding styles generated
+     * by Dokka;
+     * - `customAssets` property to provide resources. We need to provide an image with the name
+     * "logo-icon.svg" to overwrite the default one used by Dokka;
+     * - `separateInheritedMembers` when set to `true`, creates a separate tab in type-documentation
+     * for inherited members.
+     *
+     * @see <a href="https://kotlin.github.io/dokka/1.6.10/user_guide/base-specific/frontend/#prerequisites">
+     * Dokka modifying frontend assets</a>
+     */
+    pluginConfiguration<DokkaBase, DokkaBaseConfiguration> {
+        customStyleSheets = listOf(file("${dokkaConfDir.resolve("styles/custom-styles.css")}"))
+        customAssets = listOf(file("${dokkaConfDir.resolve("assets/logo-icon.svg")}"))
+        separateInheritedMembers = true
+        footerMessage = "Copyright ${LocalDate.now().year}, TeamDev"
+    }
+}

buildSrc/src/main/kotlin/io/spine/internal/dependency/Dokka.kt

@@ -29,6 +29,48 @@ package io.spine.internal.dependency
 // https://github.com/Kotlin/dokka
 @Suppress("unused")
 object Dokka {
+    private const val group = "org.jetbrains.dokka"
+
+    /**
+    When changing the version, also change the version used in the `buildSrc/build.gradle.kts`.
+     */
     const val version = "1.6.10"
-    const val pluginId = "org.jetbrains.dokka"
+
+    object GradlePlugin {
+        const val id = "org.jetbrains.dokka"
+
+        /**
+         * The version of this plugin is already specified in `buildSrc/build.gradle.kts` file.
+         * Thus, when applying the plugin in project's build files, only the [id] should be used.
+         */
+        const val lib = "${group}:dokka-gradle-plugin:${version}"
+    }
+
+    object BasePlugin {
+        const val lib = "${group}:dokka-base:${version}"
+    }
+
+    /**
+     * To generate the documentation as seen from Java perspective use this plugin.
+     *
+     * @see <a href="https://github.com/Kotlin/dokka#output-formats">
+     *     Dokka output formats</a>
+     */
+    object KotlinAsJavaPlugin {
+        const val lib = "${group}:kotlin-as-java-plugin:${version}"
+    }
+
+    /**
+     * Custom Dokka plugins developed for Spine-specific needs like excluding by `@Internal`
+     * annotation.
+     *
+     * @see <a href="https://github.com/SpineEventEngine/dokka-tools/tree/master/dokka-extensions">
+     *     Custom Dokka Plugins</a>
+     */
+    object SpineExtensions {
+        private const val group = "io.spine.tools"
+
+        const val version = "2.0.0-SNAPSHOT.2"
+        const val lib = "${group}:spine-dokka-extensions:${version}"
+    }
 }

buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/Artifacts.kt

@@ -112,6 +112,19 @@ internal fun Project.javadocJar() = tasks.getOrCreate("javadocJar") {
     dependsOn("javadoc")
 }
 
+/**
+ * Locates or creates `dokkaJar` task in this [Project].
+ *
+ * The output of this task is a `jar` archive. The archive contains the Dokka output, generated upon
+ * Java sources from `main` source set. Requires Dokka to be configured in the target project by
+ * applying `dokka-for-java` plugin.
+ */
+internal fun Project.dokkaJar() = tasks.getOrCreate("dokkaJar") {
+    archiveClassifier.set("dokka")
+    from(files("$buildDir/docs/dokka"))
+    dependsOn("dokkaHtml")
+}
+
 private fun TaskContainer.getOrCreate(name: String, init: Jar.() -> Unit): TaskProvider<Jar> =
     if (names.contains(name)) {
         named<Jar>(name)

buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/DokkaJar.kt

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2022, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.internal.gradle.publish
+
+/**
+ * A DSL element of [SpinePublishing] extension which configures publishing of [dokkaJar] artifact.
+ *
+ * This artifact contains Dokka-generated documentation. By default, it is not published.
+ *
+ * Take a look at the [SpinePublishing.dokkaJar] for a usage example.
+ *
+ * @see [registerArtifacts]
+ */
+class DokkaJar {
+    /**
+     * Enables publishing `JAR`s with Dokka-generated documentation for all published modules.
+     */
+    var enabled = false
+}

buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/PublishingConfig.kt

@@ -39,12 +39,14 @@ import org.gradle.kotlin.dsl.apply
  * @param destinations set of repositories, to which the resulting artifacts will be sent.
  * @param includeProtoJar tells whether [protoJar] artifact should be published.
  * @param includeTestJar tells whether [testJar] artifact should be published.
+ * @param includeDokkaJar tells whether [dokkaJar] artifact should be published.
  */
 internal class PublishingConfig(
     val artifactId: String,
     val destinations: Set<Repository>,
     val includeProtoJar: Boolean = true,
     val includeTestJar: Boolean = false,
+    val includeDokkaJar: Boolean = false
 )
 
 /**
@@ -65,7 +67,7 @@ internal fun PublishingConfig.apply(project: Project) = with(project) {
 }
 
 private fun PublishingConfig.createPublication(project: Project) {
-    val artifacts = project.registerArtifacts(includeProtoJar, includeTestJar)
+    val artifacts = project.registerArtifacts(includeProtoJar, includeTestJar, includeDokkaJar)
     val publication = MavenJavaPublication(
         artifactId = artifactId,
         jars = artifacts,
@@ -86,15 +88,17 @@ private fun PublishingConfig.createPublication(project: Project) {
  *  2. [protoJar] – only Proto source files.
  *  3. [javadocJar] – documentation, generated upon Java files.
  *  4. [testJar] – compilation output of "test" source set.
+ *  5. [dokkaJar] - documentation generated by Dokka.
  *
- * Registration of [protoJar] and [testJar] is optional. It can be controlled by the method's
- * parameters.
+ * Registration of [protoJar], [testJar] and [dokkaJar] is optional. It can be controlled by the
+ * method's parameters.
  *
  * @return the list of the registered tasks.
  */
 private fun Project.registerArtifacts(
     includeProtoJar: Boolean = true,
-    includeTestJar: Boolean = false
+    includeTestJar: Boolean = false,
+    includeDokkaJar: Boolean = false
 ): Set<TaskProvider<Jar>> {
 
     val artifacts = mutableSetOf(
@@ -113,5 +117,9 @@ private fun Project.registerArtifacts(
         artifacts.add(testJar())
     }
 
+    if(includeDokkaJar) {
+        artifacts.add(dokkaJar())
+    }
+
     return artifacts
 }

buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/SpinePublishing.kt

@@ -125,6 +125,7 @@ open class SpinePublishing(private val project: Project) {
 
     private val protoJar = ProtoJar()
     private val testJar = TestJar()
+    private val dokkaJar = DokkaJar()
 
     /**
      * Set of modules to be published.
@@ -242,6 +243,30 @@ open class SpinePublishing(private val project: Project) {
      */
     fun testJar(configuration: TestJar.() -> Unit)  = testJar.run(configuration)
 
+
+    /**
+     * Configures publishing of [dokkaJar] artifact, containing Dokka-generated documentation. By
+     * default, publishing of the artifact is disabled.
+     *
+     * Remember that the Dokka Gradle plugin should be applied to publish this artifact as it is
+     * produced by the `dokkaHtml` task. It can be done by using the
+     * [io.spine.internal.dependency.Dokka] dependency object or by applying the
+     * `buildSrc/src/main/kotlin/dokka-for-java` script plugin for Java projects.
+     *
+     * Here's an example of how to use this option:
+     *
+     * ```
+     * spinePublishing {
+     *     dokkaJar {
+     *         enabled = true
+     *     }
+     * }
+     * ```
+     *
+     * The resulting artifact is available under "dokka" classifier.
+     */
+    fun dokkaJar(configuration: DokkaJar.() -> Unit)  = dokkaJar.run(configuration)
+
     /**
      * Called to notify the extension that its configuration is completed.
      *
@@ -262,7 +287,7 @@ open class SpinePublishing(private val project: Project) {
             val name = project.name
             val includeProtoJar = (protoJarExclusions.contains(name) || protoJar.disabled).not()
             val includeTestJar = (testJarInclusions.contains(name) || testJar.enabled)
-            setUpPublishing(project, includeProtoJar, includeTestJar)
+            setUpPublishing(project, includeProtoJar, includeTestJar, dokkaJar.enabled)
         }
     }
 
@@ -303,13 +328,19 @@ open class SpinePublishing(private val project: Project) {
      * `project.afterEvaluate` in order to guarantee that a module will be configured by the time
      * we configure publishing for it.
      */
-    private fun setUpPublishing(project: Project, includeProtoJar: Boolean, includeTestJar: Boolean) {
+    private fun setUpPublishing(
+        project: Project,
+        includeProtoJar: Boolean,
+        includeTestJar: Boolean,
+        includeDokkaJar: Boolean
+    ) {
         val artifactId = artifactId(project)
         val publishingConfig = PublishingConfig(
             artifactId,
             destinations,
             includeProtoJar,
             includeTestJar,
+            includeDokkaJar
         )
         project.afterEvaluate {
             publishingConfig.apply(project)
@@ -376,4 +407,3 @@ open class SpinePublishing(private val project: Project) {
         }
     }
 }
-