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