👷 Support Kotlin/JVM projects in Kotools Samples Gradle plugin

This plugin is available through the following identifier: `org.kotools.samples.jvm`.

gradle/libs.versions.toml

@@ -28,6 +28,9 @@ version.ref = "kotlinx-binary-compatibility-validator"
 id = "org.jetbrains.kotlin.plugin.serialization"
 version.ref = "kotlin"
 
+[plugins.kotools-samples-jvm]
+id = "org.kotools.samples.jvm"
+
 [plugins.kotools-samples-multiplatform]
 id = "org.kotools.samples.multiplatform"
 

gradle/plugins/src/main/kotlin/org/kotools/samples/InlineSamples.kt

@@ -34,7 +34,7 @@ public abstract class InlineSamples : DefaultTask() {
     @TaskAction
     private fun execute(): Unit = this.sourceDirectory.asFileTree.asSequence()
         .filterNotNull()
-        .filter { "Main/" in it.path }
+        .filter { "Main/" in it.path || "main/" in it.path }
         .filter { it.name.endsWith(".kt") }
         .forEach(this::inlineSamples)
 

gradle/plugins/src/main/kotlin/org/kotools/samples/internal/SampleSourceFile.kt

@@ -4,7 +4,7 @@ import java.io.File
 
 internal class SampleSourceFile private constructor(private val file: File) {
     init {
-        require("Sample/" in this.file.path) {
+        require("Sample/" in this.file.path || "sample/" in this.file.path) {
             "'${this.file.name}' file should be in a sample source set."
         }
     }

gradle/plugins/src/main/kotlin/org/kotools/samples/jvm.gradle.kts

@@ -0,0 +1,104 @@
+package org.kotools.samples
+
+import org.jetbrains.dokka.gradle.AbstractDokkaLeafTask
+import org.jetbrains.dokka.gradle.DokkaMultiModuleTask
+import org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension
+import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
+
+// ----------------------------- Script properties -----------------------------
+
+private val projectSources: Directory = layout.projectDirectory.dir("src")
+private val samplesBuildDirectory: Provider<Directory> =
+    layout.buildDirectory.dir("samples")
+private val sourcesBackupBuildDirectory: Provider<Directory> =
+    samplesBuildDirectory.map { it.dir("sources-backup") }
+
+// ----------------------------- Plugin extensions -----------------------------
+
+private val kotlin: KotlinJvmProjectExtension = extensions.findByType()
+    ?: error("Kotlin/JVM plugin wasn't applied to ${project}.")
+
+private val mainSourceSet: KotlinSourceSet = kotlin.sourceSets.getByName("main")
+private val testSourceSet: KotlinSourceSet = kotlin.sourceSets.getByName("test")
+private val sampleSourceSet: KotlinSourceSet =
+    kotlin.sourceSets.create("sample") { this.dependsOn(mainSourceSet) }
+testSourceSet.dependsOn(sampleSourceSet)
+
+// ----------------------------------- Tasks -----------------------------------
+
+private val checkSampleSources: TaskProvider<CheckSampleSources>
+        by tasks.registering(CheckSampleSources::class)
+checkSampleSources.configure {
+    this.description = "Checks the content of sample sources."
+    this.sourceDirectory = projectSources
+}
+
+private val extractSamples: TaskProvider<ExtractSamples>
+        by tasks.registering(ExtractSamples::class)
+extractSamples.configure {
+    this.description = "Extracts samples for KDoc."
+    this.dependsOn(checkSampleSources)
+    this.sourceDirectory = projectSources
+    this.outputDirectory = samplesBuildDirectory.map { it.dir("extracted") }
+}
+
+private val checkSampleReferences: TaskProvider<CheckSampleReferences>
+        by tasks.registering(CheckSampleReferences::class)
+checkSampleReferences.configure {
+    this.description = "Checks sample references from KDoc."
+    this.sourceDirectory = projectSources
+    this.extractedSamplesDirectory =
+        extractSamples.flatMap(ExtractSamples::outputDirectory)
+}
+
+private val backupMainSources: TaskProvider<Copy>
+        by tasks.registering(Copy::class)
+backupMainSources.configure {
+    this.description = "Copies main sources into the build directory."
+    this.dependsOn(checkSampleReferences)
+    this.from(projectSources) { exclude("api", "sample", "test") }
+    this.into(sourcesBackupBuildDirectory)
+}
+
+private val inlineSamples: TaskProvider<InlineSamples>
+        by tasks.registering(InlineSamples::class)
+inlineSamples.configure {
+    this.description = "Inlines KDoc samples."
+    this.dependsOn(backupMainSources)
+    this.sourceDirectory = projectSources
+    this.extractedSamplesDirectory =
+        extractSamples.flatMap(ExtractSamples::outputDirectory)
+}
+
+private val restoreMainSources: TaskProvider<Copy>
+        by tasks.registering(Copy::class)
+restoreMainSources.configure {
+    this.description = "Restores main sources backup from the build directory."
+    this.from(sourcesBackupBuildDirectory)
+    this.into(projectSources)
+}
+
+// ----------------------------- Dokka integration -----------------------------
+
+tasks.withType<AbstractDokkaLeafTask>().configureEach {
+    this.dependsOn(inlineSamples)
+    this.finalizedBy(restoreMainSources)
+}
+
+rootProject.tasks.withType<DokkaMultiModuleTask>().configureEach {
+    this.dependsOn(restoreMainSources)
+}
+
+// ---------------------------- Kotlin integration -----------------------------
+
+tasks.named("check").configure { this.dependsOn(checkSampleReferences) }
+
+tasks.named("kotlinSourcesJar").configure {
+    this.dependsOn(inlineSamples)
+    this.finalizedBy(restoreMainSources)
+}
+
+private val kotlinCompilationTasks: TaskCollection<KotlinCompilationTask<*>> =
+    tasks.withType(KotlinCompilationTask::class)
+restoreMainSources.configure { this.mustRunAfter(kotlinCompilationTasks) }

subprojects/samples-demo-jvm/build.gradle.kts

@@ -2,6 +2,7 @@ plugins {
     alias(libs.plugins.kotlin.jvm)
     alias(libs.plugins.dokka)
     alias(libs.plugins.kotools.types.documentation)
+    alias(libs.plugins.kotools.samples.jvm)
 }
 
 // ----------------------------- Plugin extensions -----------------------------
@@ -15,7 +16,7 @@ kotlin.explicitApi()
 dependencies {
     implementation(platform(libs.kotlin.bom))
 
-    testImplementation(libs.kotlin.test.junit5)
+    sampleImplementation(libs.kotlin.test.junit5)
 }
 
 // ----------------------------------- Tasks -----------------------------------

subprojects/samples-demo-jvm/src/main/kotlin/Hello.kt

@@ -9,7 +9,7 @@
  *
  * Here's an example of calling this function from Kotlin code:
  *
- * TODO: Add Kotlin code sample.
+ * SAMPLE: [HelloKotlinSample.greet]
  * </details>
  *
  * <br>

subprojects/samples-demo-jvm/src/sample/kotlin/HelloKotlinSample.kt

@@ -0,0 +1,12 @@
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class HelloKotlinSample {
+    @Test
+    fun greet() {
+        val name = "Sample"
+        val greeting: String = greet(name)
+        val expected = "Hello $name!"
+        assertEquals(expected, greeting)
+    }
+}