Use Dokka instead of Javadoc

buildSrc/build.gradle.kts

@@ -93,6 +93,16 @@ val errorProneVersion = "2.0.2"
  */
 val protobufPluginVersion = "0.8.18"
 
+/**
+ * The version of Dokka Gradle Plugin.
+ *
+ * Please keep in sync. with [io.spine.internal.dependency.Dokka.GradlePlugin.version].
+ *
+ * @see <a href="https://github.com/Kotlin/dokka/releases">
+ *     Dokka Gradle Plugins Releases</a>
+ */
+val dokkaPluginVersion = "1.6.10"
+
 dependencies {
     implementation("com.fasterxml.jackson.core:jackson-databind:$jacksonVersion")
     implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-xml:$jacksonVersion")
@@ -105,4 +115,5 @@ 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:${dokkaPluginVersion}")
+}

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

@@ -0,0 +1,83 @@
+/*
+ * 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 org.gradle.kotlin.dsl.dependencies
+import org.gradle.kotlin.dsl.withType
+import org.jetbrains.dokka.gradle.DokkaTask
+import io.spine.internal.dependency.Dokka
+import java.time.LocalDate
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+/**
+ * To generate the documentation as seen from Java perspective,
+ * the kotlin-as-java plugin was added to the Dokka plugins classpath.
+ *
+ * @see <a href="https://github.com/Kotlin/dokka#output-formats">
+ *     Dokka output formats</a>
+ */
+dependencies {
+    dokkaPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:${Dokka.GradlePlugin.version}")
+}
+
+tasks.withType<DokkaTask>().configureEach {
+    outputDirectory.set(buildDir.resolve("docs/dokka"))
+
+    /**
+     * In order to modify the styles Dokka uses for the generated documentation we provide
+     * a configuration to the Dokka Base Plugin.
+     * @see <a href="https://kotlin.github.io/dokka/1.6.10/user_guide/base-specific/frontend/#prerequisites">
+     * Dokka modifying frontend assets</a>
+     */
+    val dokkaBaseRef = "org.jetbrains.dokka.base.DokkaBase"
+    val dokkaConfDir = rootDir.resolve("buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka")
+
+    /**
+     * Dokka Base configuration provides <code>customStyleSheets</code> property to which we can
+     * pass our css files overriding styles generated by Dokka.
+     * Also, there is a <code>customAssets</code> property to provide resources. We need to
+     * provide an image with the name "logo-icon.svg" to overwrite the default one used by Dokka.
+     */
+    val dokkaConf = """
+        {
+            "customStyleSheets": [
+                "${dokkaConfDir.resolve("styles/custom-styles.css")}"
+             ],
+             "customAssets": [
+                "${dokkaConfDir.resolve("assets/logo-icon.svg")}"
+             ],
+             "footerMessage": "Copyright ${LocalDate.now().year}, TeamDev"
+        }
+        """.trimIndent()
+
+    pluginsMapConfiguration.set(
+        mapOf(
+            dokkaBaseRef to dokkaConf
+        )
+    )
+}

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

@@ -29,6 +29,15 @@ package io.spine.internal.dependency
 // https://github.com/Kotlin/dokka
 @Suppress("unused")
 object Dokka {
-    const val version = "1.5.0"
-    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.
+         *
+         * When changing the version, also change the version used in the `buildSrc/build.gradle.kts`.
+         */
+        const val version = "1.6.10"
+    }
 }

buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/styles/custom-styles.css

@@ -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.
+ */
+
+:root,
+:root.theme-dark {
+    --color-dark: #007bff;
+}
+
+.library-name a::before {
+    background-image: url('https://spine.io/img/spine-sign-white.svg')
+}
+
+.cover a,
+.main-subrow.keyValue a {
+    font-family: monospace;
+}
+
+:root.theme-dark dt {
+    color: #fff;
+}

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

@@ -35,5 +35,6 @@ package io.spine.internal.gradle.publish
 internal enum class ArtifactTaskName {
     sourceJar,
     testOutputJar,
-    javadocJar;
+    javadocJar,
+    dokkaJar;
 }

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

@@ -128,12 +128,19 @@ private fun Project.setUpDefaultArtifacts() {
         classifier = "javadoc",
         dependencies = setOf("javadoc")
     )
+    val dokkaJar = tasks.createIfAbsent(
+        artifactTask = ArtifactTaskName.dokkaJar,
+        from = files("$buildDir/docs/dokka"),
+        classifier = "dokka",
+        dependencies = setOf("dokkaHtml")
+    )
 
     artifacts {
         val archives = ConfigurationName.archives
         add(archives, sourceJar)
         add(archives, testOutputJar)
         add(archives, javadocJar)
+        add(archives, dokkaJar)
     }
 }