Merge pull request #57 from SpineEventEngine/migrate-to-reaction-api

Adopt new documentation build scripts

Author: alexander-yevsyukov

README.md

@@ -7,10 +7,19 @@
 This repository hosts the plugins to the Spine Compiler that the Core JVM library offers for
 building a client or a server application.
 
-### Environment
+## Environment
 
 The modules in this repository are built with Java 17.
 
+For the versions of other dependencies, refer to the Kotlin source code under
+[io.spine.dependency](./buildSrc/src/main/kotlin/io/spine/dependency).
+
+## Testing modules in the project structure
+
+### Integration testing
+
+Please refer to [TESTING.md](./TESTING.md).
+
 ### Performance testing
 
 This repo includes the `BuildSpeed` submodule with the performance tests for the Spine tools.

base/src/main/kotlin/io/spine/tools/core/jvm/settings/Patterns.kt

@@ -53,7 +53,7 @@ public fun Pattern.matches(type: MessageType): Boolean {
  * Tells if this type pattern matches the given type.
  *
  * @see Pattern.matches
- * @see io.spine.protodata.ast.FilePattern.matches
+ * @see io.spine.tools.compiler.ast.FilePattern.matches
  */
 public fun TypePattern.matches(type: MessageType): Boolean {
     val qualifiedName = type.qualifiedName

buildSrc/build.gradle.kts

@@ -113,7 +113,7 @@ val protobufPluginVersion = "0.9.5"
  * @see <a href="https://github.com/Kotlin/dokka/releases">
  *     Dokka Releases</a>
  */
-val dokkaVersion = "2.0.0"
+val dokkaVersion = "2.1.0"
 
 /**
  * The version of Detekt Gradle Plugin.
@@ -122,6 +122,11 @@ val dokkaVersion = "2.0.0"
  */
 val detektVersion = "1.23.8"
 
+/**
+ * @see [io.spine.dependency.test.Kotest]
+ */
+val kotestJvmPluginVersion = "0.4.10"
+
 /**
  * @see [io.spine.dependency.test.Kover]
  */
@@ -174,6 +179,7 @@ dependencies {
         "com.google.protobuf:protobuf-gradle-plugin:$protobufPluginVersion",
         "com.gradleup.shadow:shadow-gradle-plugin:$shadowVersion",
         "io.gitlab.arturbosch.detekt:detekt-gradle-plugin:$detektVersion",
+        "io.kotest:kotest-gradle-plugin:$kotestJvmPluginVersion",
         // https://github.com/srikanth-lingala/zip4j
         "net.lingala.zip4j:zip4j:2.10.0",
         "net.ltgt.gradle:gradle-errorprone-plugin:$errorPronePluginVersion",

buildSrc/src/main/kotlin/BuildExtensions.kt

@@ -199,43 +199,34 @@ fun Project.configureTaskDependencies() {
     }
 
     afterEvaluate {
-        val launchProtoData = "launchProtoData"
-        val launchTestProtoData = "launchTestProtoData"
         val generateProto = "generateProto"
         val createVersionFile = "createVersionFile"
         val compileKotlin = "compileKotlin"
         compileKotlin.run {
             dependOn(generateProto)
-            dependOn(launchProtoData)
         }
         val compileTestKotlin = "compileTestKotlin"
-        compileTestKotlin.dependOn(launchTestProtoData)
         val sourcesJar = "sourcesJar"
         val kspKotlin = "kspKotlin"
         sourcesJar.run {
             dependOn(generateProto)
-            dependOn(launchProtoData)
             dependOn(kspKotlin)
             dependOn(createVersionFile)
             dependOn("prepareProtocConfigVersions")
         }
-        val dokkaHtml = "dokkaHtml"
-        dokkaHtml.run {
+        val dokkaGenerate = "dokkaGenerate"
+        dokkaGenerate.run {
             dependOn(generateProto)
-            dependOn(launchProtoData)
-            dependOn(kspKotlin)
-        }
-        val dokkaJavadoc = "dokkaJavadoc"
-        dokkaJavadoc.run {
-            dependOn(launchProtoData)
             dependOn(kspKotlin)
         }
+        val dokkaGeneratePublicationJavadoc = "dokkaGeneratePublicationJavadoc"
+        dokkaGeneratePublicationJavadoc.dependOn(kspKotlin)
         "publishPluginJar".dependOn(createVersionFile)
         compileKotlin.dependOn(kspKotlin)
         compileTestKotlin.dependOn("kspTestKotlin")
         "compileTestFixturesKotlin".dependOn("kspTestFixturesKotlin")
-        "javadocJar".dependOn(dokkaHtml)
-        "dokkaKotlinJar".dependOn(dokkaJavadoc)
+        "javadocJar".dependOn(dokkaGeneratePublicationJavadoc)
+        "htmlDocsJar".dependOn(dokkaGenerate)
     }
 }
 

buildSrc/src/main/kotlin/DocumentationSettings.kt

@@ -24,6 +24,8 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+import org.gradle.api.Project
+
 /**
  * The documentation settings specific to this project.
  *
@@ -33,6 +35,36 @@
 @Suppress("ConstPropertyName")
 object DocumentationSettings {
 
+    /**
+     * The organization infix for the Spine SDK.
+     */
+    private const val orgPath = "github.com/SpineEventEngine"
+
+    /**
+     * The organization URL of the Spine SDK.
+     */
+    private const val orgUrl = "https://$orgPath"
+
+    /**
+     * Obtains the repository URL for the given project.
+     */
+    fun repoUrl(project: Project) = "https://${repoPath(project)}"
+
+    /**
+     * Obtains the repository path for the given project.
+     */
+    private fun repoPath(project: Project) = "$orgPath/${project.rootProject.name}"
+
+    /**
+     * Obtains the connection URL for the given project.
+     */
+    fun connectionUrl(project: Project) = "scm:git:git://${repoPath(project)}.git"
+
+    /**
+     * Obtains the developer connection URL for the given project.
+     */
+    fun developerConnectionUrl(project: Project) = "scm:git:ssh://${repoPath(project)}.git"
+
     /**
      * Settings passed to Dokka for
      * [sourceLink][[org.jetbrains.dokka.gradle.engine.parameters.DokkaSourceLinkSpec]
@@ -43,12 +75,16 @@ object DocumentationSettings {
          * The URL of the remote source code
          * [location][org.jetbrains.dokka.gradle.engine.parameters.DokkaSourceLinkSpec.remoteUrl].
          */
-        const val url: String = "https://github.com/SpineEventEngine/base/tree/master/src"
+        fun url(project: Project): String {
+            val root = project.rootProject.name
+            val module = project.name
+            return "$orgUrl/$root/tree/master/$module/src/main/kotlin"
+        }
 
         /**
          * The suffix used to append the source code line number to the URL.
          *
-         * The suffix depends on the online code repository.
+         * The value depends on the online code repository and is set for GitHub (`#L`).
          *
          * @see <a href="https://kotlinlang.org/docs/dokka-gradle.html#fwor0d_534">
          *     remoteLineSuffix</a>

buildSrc/src/main/kotlin/DokkaExts.kt

@@ -29,32 +29,18 @@ import io.spine.gradle.publish.getOrCreate
 import java.io.File
 import java.time.LocalDate
 import org.gradle.api.Project
+import org.gradle.api.Task
 import org.gradle.api.artifacts.Dependency
 import org.gradle.api.artifacts.dsl.DependencyHandler
-import org.gradle.api.file.FileCollection
 import org.gradle.api.tasks.TaskContainer
 import org.gradle.api.tasks.TaskProvider
 import org.gradle.api.tasks.bundling.Jar
 import org.gradle.kotlin.dsl.DependencyHandlerScope
-import org.jetbrains.dokka.gradle.AbstractDokkaTask
 import org.jetbrains.dokka.gradle.DokkaExtension
-import org.jetbrains.dokka.gradle.DokkaTask
-import org.jetbrains.dokka.gradle.GradleDokkaSourceSetBuilder
 import org.jetbrains.dokka.gradle.engine.parameters.DokkaSourceSetSpec
 import org.jetbrains.dokka.gradle.engine.parameters.VisibilityModifier
 import org.jetbrains.dokka.gradle.engine.plugins.DokkaHtmlPluginParameters
 
-/**
- * To generate the documentation as seen from Java perspective, the `kotlin-as-java`
- * plugin was added to the Dokka classpath.
- *
- * @see <a href="https://github.com/Kotlin/dokka#output-formats">
- *     Dokka output formats</a>
- */
-fun DependencyHandlerScope.useDokkaForKotlinAsJava() {
-    dokkaPlugin(Dokka.KotlinAsJavaPlugin.lib)
-}
-
 /**
  * To exclude pieces of code annotated with `@Internal` from the documentation
  * a custom plugin is added to the Dokka classpath.
@@ -72,9 +58,8 @@ private fun DependencyHandler.dokkaPlugin(dependencyNotation: Any): Dependency?
 /**
  * Resolves the directory where Dokka outputs HTML documentation for the given language.
  */
-internal fun Project.dokkaOutput(language: String): File {
-    val lng = language.titleCaseFirstChar()
-    return layout.buildDirectory.dir("docs/dokka$lng").get().asFile
+internal fun Project.dokkaHtmlOutput(): File {
+    return layout.buildDirectory.dir("dokka/html").get().asFile
 }
 
 /**
@@ -187,54 +172,42 @@ private fun DokkaSourceSetSpec.configureSourceSet(config: SourceSetConfig) {
 }
 
 /**
- * Configures this [DokkaTask] to accept only Kotlin files.
+ * Configures this [DokkaExtension] to accept only Kotlin files.
  */
 fun DokkaExtension.configureForKotlin(project: Project, sourceLinkRemoteUrl: String) {
     configureFor(project, "kotlin", sourceLinkRemoteUrl)
 }
 
 /**
- * Configures this [DokkaTask] to accept only Java files.
+ * Configures this [DokkaExtension] to accept only Java files.
  */
 @Suppress("unused")
 fun DokkaExtension.configureForJava(project: Project, sourceLinkRemoteUrl: String) {
     configureFor(project, "java", sourceLinkRemoteUrl)
 }
 
 /**
- * Finds the `dokkaHtml` Gradle task.
+ * Finds the `dokkaGenerateHtml` Gradle task.
  */
-fun TaskContainer.dokkaHtmlTask(): DokkaTask? = this.findByName("dokkaHtml") as DokkaTask?
+fun TaskContainer.dokkaHtmlTask(): Task? = this.findByName("dokkaGeneratePublicationHtml")
 
 /**
- * Returns only Java source roots out of all present in the source set.
- *
- * It is a helper method for generating documentation by Dokka only for Java code.
- * It is helpful when both Java and Kotlin source files are present in a source set.
- * Dokka can properly generate documentation for either Kotlin or Java depending on
- * the configuration, but not both.
+ * Finds the `dokkaGeneratePublicationJavadoc` Gradle task.
  */
-@Suppress("unused")
-internal fun GradleDokkaSourceSetBuilder.onlyJavaSources(): FileCollection {
-    return sourceRoots.filter(File::isJavaSourceDirectory)
-}
-
-private fun File.isJavaSourceDirectory(): Boolean {
-    return isDirectory && name == "java"
-}
+fun TaskContainer.dokkaJavadocTask(): Task? = this.findByName("dokkaGeneratePublicationJavadoc")
 
 /**
- * Locates or creates `dokkaKotlinJar` task in this [Project].
+ * Locates or creates `htmlDocsJar` task in this [Project].
  *
  * The output of this task is a `jar` archive. The archive contains the Dokka output, generated upon
  * Kotlin sources from `main` source set. Requires Dokka to be configured in the target project by
- * applying `dokka-for-kotlin` plugin.
+ * applying `dokka-setup` plugin.
  */
-fun Project.dokkaKotlinJar(): TaskProvider<Jar> = tasks.getOrCreate("dokkaKotlinJar") {
-    archiveClassifier.set("dokka")
-    from(files(dokkaOutput("kotlin")))
+fun Project.htmlDocsJar(): TaskProvider<Jar> = tasks.getOrCreate("htmlDocsJar") {
+    archiveClassifier.set("html-docs")
+    from(files(dokkaHtmlOutput()))
 
-    tasks.dokkaHtmlTask()?.let{ dokkaTask ->
+    tasks.dokkaHtmlTask()?.let { dokkaTask ->
         this@getOrCreate.dependsOn(dokkaTask)
     }
 }
@@ -246,29 +219,13 @@ fun Project.dokkaKotlinJar(): TaskProvider<Jar> = tasks.getOrCreate("dokkaKotlin
  * This predicate could be useful for disabling publishing tasks
  * when doing, e.g., `publishToMavenLocal` for the purpose of the
  * integration tests that (of course) do not test the documentation
- * generation proces and its resuults.
+ * generation process and its results.
  */
-fun AbstractDokkaTask.isInPublishingGraph(): Boolean =
+fun Task.isInPublishingGraph(): Boolean =
     project.gradle.taskGraph.allTasks.any {
         it.name == "publish" || it.name.contains("dokkaGenerate")
     }
 
-/**
- * Locates or creates `dokkaJavaJar` task in this [Project].
- *
- * The output of this task is a `jar` archive. The archive contains the Dokka output, generated upon
- * Kotlin sources from `main` source set. Requires Dokka to be configured in the target project by
- * applying `dokka-for-java` and/or `dokka-for-kotlin` script plugin.
- */
-fun Project.dokkaJavaJar(): TaskProvider<Jar> = tasks.getOrCreate("dokkaJavaJar") {
-    archiveClassifier.set("dokka-java")
-    from(files(dokkaOutput("java")))
-
-    tasks.dokkaHtmlTask()?.let{ dokkaTask ->
-        this@getOrCreate.dependsOn(dokkaTask)
-    }
-}
-
 /**
  * Disables Dokka and Javadoc tasks in this `Project`.
  *