Add example to demonstrate how to configure a custom Dokka plugin (#3871)

#3869

Author: adam-enko

build-logic/src/main/kotlin/dokkabuild/utils/DokkaGradleExampleDirectoriesSource.kt

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package dokkabuild.utils
+
+import org.gradle.api.file.DirectoryProperty
+import org.gradle.api.provider.ValueSource
+import org.gradle.api.provider.ValueSourceParameters
+import java.io.File
+import kotlin.io.path.isDirectory
+import kotlin.io.path.listDirectoryEntries
+import kotlin.io.path.name
+
+/**
+ * Fetch the example directories in `dokka/examples/gradle-v2` using a [ValueSource].
+ *
+ * A [ValueSource] is necessary to ensure that Gradle registers the directory values as Configuration Cache inputs,
+ * but doesn't become overly sensitive to the contents of the directories.
+ */
+abstract class DokkaGradleExampleDirectoriesSource :
+    ValueSource<List<File>, DokkaGradleExampleDirectoriesSource.Parameters> {
+
+    interface Parameters : ValueSourceParameters {
+        /**
+         * The directory containing the Dokka Gradle v2 examples: `dokka/examples/gradle-v2`
+         */
+        val exampleGradleProjectsDir: DirectoryProperty
+    }
+
+    override fun obtain(): List<File> {
+        return parameters.exampleGradleProjectsDir.get().asFile.toPath()
+            .listDirectoryEntries()
+            .filter { it.isDirectory() && it.name.endsWith("-example") }
+            .map { it.toFile() }
+    }
+}

build-logic/src/main/kotlin/dokkabuild/utils/SystemPropertyAdder.kt

@@ -153,6 +153,16 @@ abstract class SystemPropertyAdder @Inject internal constructor(
         return task.inputs.property("SystemProperty input property $key", value)
     }
 
+    fun inputProperty(
+        key: String,
+        value: String,
+    ): TaskInputPropertyBuilder {
+        task.jvmArgumentProviders.add(
+            SystemPropertyArgumentProvider(key, value) { it }
+        )
+        return task.inputs.property("SystemProperty input property $key", value)
+    }
+
     @JvmName("inputBooleanProperty")
     fun inputProperty(
         key: String,

build-logic/src/main/kotlin/dokkabuild/utils/strings.kt

@@ -0,0 +1,7 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package dokkabuild.utils
+
+/** Title case the first char of a string */
+fun String.uppercaseFirstChar(): String = replaceFirstChar(Char::uppercaseChar)

dokka-integration-tests/gradle/build.gradle.kts

@@ -4,9 +4,10 @@
 @file:Suppress("UnstableApiUsage")
 
 import dokkabuild.tasks.GitCheckoutTask
+import dokkabuild.utils.DokkaGradleExampleDirectoriesSource
 import dokkabuild.utils.systemProperty
-import org.gradle.api.tasks.PathSensitivity.NAME_ONLY
-import org.gradle.api.tasks.PathSensitivity.RELATIVE
+import dokkabuild.utils.uppercaseFirstChar
+import org.gradle.api.tasks.PathSensitivity.*
 
 plugins {
     id("dokkabuild.kotlin-jvm")
@@ -226,10 +227,10 @@ testing {
         }
     }
     val testExampleProjects by suites.registering(JvmTestSuite::class) {
-        targets.configureEach {
-            testTask.configure {
+        val exampleGradleProjectsDir = projectDir.resolve("../../examples/gradle-v2")
 
-                val exampleGradleProjectsDir = projectDir.resolve("../../examples/gradle-v2")
+        targets.configureEach {
+            testTask {
                 systemProperty
                     .inputDirectory("exampleGradleProjectsDir", exampleGradleProjectsDir)
                     .withPathSensitivity(RELATIVE)
@@ -244,5 +245,28 @@ testing {
                 systemProperty("junit.jupiter.execution.parallel.mode.default", "CONCURRENT")
             }
         }
+
+        val exampleProjectDirs = providers.of(DokkaGradleExampleDirectoriesSource::class) {
+            parameters.exampleGradleProjectsDir = exampleGradleProjectsDir
+        }.get()
+
+        exampleProjectDirs.forEach { exampleProjectDir ->
+            val exampleProjectName = exampleProjectDir.name
+            val prettyName = exampleProjectName
+                .split("-")
+                .joinToString("") { it.uppercaseFirstChar() }
+
+            targets.register("test$prettyName") {
+                testTask {
+                    description = "Only test $exampleProjectName"
+                    group = "verification - example projects"
+                    systemProperty.inputProperty("exampleProjectFilter", exampleProjectName)
+
+                    systemProperty
+                        .inputDirectory("exampleGradleProjectDir $exampleProjectName", exampleProjectDir)
+                        .withPathSensitivity(NONE)
+                }
+            }
+        }
     }
 }