diff --git a/buildSrc/build.gradle.kts b/buildSrc/build.gradle.kts
index 591c5ae3..3456d522 100644
--- a/buildSrc/build.gradle.kts
+++ b/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.version].
+ *
+ * @see
+ * Dokka Gradle Plugins Releases
+ */
+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}")
+}
\ No newline at end of file
diff --git a/buildSrc/src/main/kotlin/dokka-for-java.gradle.kts b/buildSrc/src/main/kotlin/dokka-for-java.gradle.kts
new file mode 100644
index 00000000..144c3a51
--- /dev/null
+++ b/buildSrc/src/main/kotlin/dokka-for-java.gradle.kts
@@ -0,0 +1,73 @@
+/*
+ * 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")
+}
+
+/**
+ * To generate the documentation as seen from Java perspective,
+ * the kotlin-as-java plugin was added to the Dokka plugins classpath.
+ *
+ * @see
+ * Dokka output formats
+ */
+dependencies {
+ dokkaPlugin(Dokka.KotlinAsJava.lib)
+}
+
+tasks.withType().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
+ * Dokka modifying frontend assets
+ */
+ val dokkaConfDir = rootDir.resolve("buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka")
+
+ /**
+ * Dokka Base configuration provides `customStyleSheets` property to which we can
+ * pass our css files overriding styles generated by Dokka.
+ *
+ * Also, there is a `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.
+ */
+ pluginConfiguration {
+ customStyleSheets = listOf(file("${dokkaConfDir.resolve("styles/custom-styles.css")}"))
+ customAssets = listOf(file("${dokkaConfDir.resolve("assets/logo-icon.svg")}"))
+ footerMessage = "Copyright ${LocalDate.now().year}, TeamDev"
+ }
+}
+
diff --git a/buildSrc/src/main/kotlin/io/spine/internal/dependency/Dokka.kt b/buildSrc/src/main/kotlin/io/spine/internal/dependency/Dokka.kt
index 95cf018f..740d6ebb 100644
--- a/buildSrc/src/main/kotlin/io/spine/internal/dependency/Dokka.kt
+++ b/buildSrc/src/main/kotlin/io/spine/internal/dependency/Dokka.kt
@@ -29,6 +29,29 @@ 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"
+ 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"
+
+ 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 Base {
+ const val lib = "${group}:dokka-base:${version}"
+ }
+
+ object KotlinAsJava {
+ const val lib = "${group}:kotlin-as-java-plugin:${version}"
+ }
}
diff --git a/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/ExcludeInternalPlugin.kt b/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/ExcludeInternalPlugin.kt
new file mode 100644
index 00000000..8339d82a
--- /dev/null
+++ b/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/ExcludeInternalPlugin.kt
@@ -0,0 +1,47 @@
+/*
+ * 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.dokka
+
+import org.gradle.kotlin.dsl.provideDelegate
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.plugability.DokkaPlugin
+
+/**
+ * Dokka has several extensions points at different stages of generating documentation.
+ * The plugin below is injected at stage when the source code of a project is already collected and
+ * translated to Dokka internal representation Documentable.
+ *
+ * @see
+ * Dokka "Pr-merge documentation transform" extension point
+ */
+class ExcludeInternalPlugin : DokkaPlugin() {
+ private val dokkaBase by lazy { plugin() }
+
+ val excludeInternalTransformer by extending {
+ dokkaBase.preMergeDocumentableTransformer providing ::ExcludeInternalTransformer
+ }
+}
\ No newline at end of file
diff --git a/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/ExcludeInternalTransformer.kt b/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/ExcludeInternalTransformer.kt
new file mode 100644
index 00000000..cf70b7f5
--- /dev/null
+++ b/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/ExcludeInternalTransformer.kt
@@ -0,0 +1,48 @@
+/*
+ * 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.dokka
+
+import org.jetbrains.dokka.base.transformers.documentables.SuppressedByConditionDocumentableFilterTransformer
+import org.jetbrains.dokka.model.Documentable
+import org.jetbrains.dokka.model.dfs
+import org.jetbrains.dokka.model.doc.CustomTagWrapper
+import org.jetbrains.dokka.plugability.DokkaContext
+
+/**
+ * @see
+ * Can classes or methods be dropped from documentation based on annotation
+ */
+class ExcludeInternalTransformer(val dokkaContext: DokkaContext) :
+ SuppressedByConditionDocumentableFilterTransformer(dokkaContext) {
+ override fun shouldBeSuppressed(d: Documentable): Boolean {
+ return d.documentation.any { (_, docs) ->
+ docs.dfs {
+ it is CustomTagWrapper && it.name.trim() == "Internal"
+ } != null
+ }
+ }
+}
\ No newline at end of file
diff --git a/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/assets/logo-icon.svg b/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/assets/logo-icon.svg
new file mode 100644
index 00000000..471d65e1
--- /dev/null
+++ b/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/assets/logo-icon.svg
@@ -0,0 +1,17 @@
+
+
+
diff --git a/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/styles/custom-styles.css b/buildSrc/src/main/kotlin/io/spine/internal/gradle/dokka/styles/custom-styles.css
new file mode 100644
index 00000000..72e9c618
--- /dev/null
+++ b/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;
+}
diff --git a/buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/ArtifactTaskName.kt b/buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/ArtifactTaskName.kt
index a3ed1255..6d477cb7 100644
--- a/buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/ArtifactTaskName.kt
+++ b/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;
}
diff --git a/buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/ProjectExtensions.kt b/buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/ProjectExtensions.kt
index 3b866617..7df22901 100644
--- a/buildSrc/src/main/kotlin/io/spine/internal/gradle/publish/ProjectExtensions.kt
+++ b/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)
}
}
diff --git a/buildSrc/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin b/buildSrc/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
new file mode 100644
index 00000000..d4a5cef3
--- /dev/null
+++ b/buildSrc/src/main/resources/META-INF/services/org.jetbrains.dokka.plugability.DokkaPlugin
@@ -0,0 +1 @@
+io.spine.internal.gradle.dokka.ExcludeInternalPlugin