feat: Dokka improvements

- Parse module and package docs. We'll need to update these markdown files to follow the specs.
- Parse snippets for sample code
- Configure source link (currently broken, Kotlin/dokka#2876)

build-logic/src/main/kotlin/com/adevinta/spark/SparkDokkaPlugin.kt

@@ -29,31 +29,49 @@ import org.gradle.kotlin.dsl.named
 import org.gradle.kotlin.dsl.withType
 import org.jetbrains.dokka.gradle.DokkaMultiModuleTask
 import org.jetbrains.dokka.gradle.DokkaTask
+import org.jetbrains.dokka.gradle.DokkaTaskPartial
+import java.net.URL
 
 internal class SparkDokkaPlugin : Plugin<Project> {
     override fun apply(target: Project) {
         with(target) {
             apply(plugin = "org.jetbrains.dokka")
 
-            if (this === rootProject) {
-                tasks.named<DokkaMultiModuleTask>("dokkaHtmlMultiModule") {
+            when {
+                this === rootProject -> tasks.named<DokkaMultiModuleTask>("dokkaHtmlMultiModule") {
                     moduleName.set("✨ Spark")
                     outputDirectory.set(buildDir.resolve("dokka"))
                 }
+
+                else -> tasks.withType<DokkaTaskPartial> {
+                    dokkaSourceSets.configureEach {
+                        // Parse Module and Package docs
+                        // https://kotlinlang.org/docs/dokka-module-and-package-docs.html
+                        projectDir.resolve("src").walk()
+                            .filter { it.isFile && it.extension == "md" }.toList()
+                            .let { includes.from(project.files(), it) }
+
+                        // List of files or directories containing sample code (referenced with @sample tags)
+                        projectDir.resolve("samples").walk()
+                            .filter { it.isFile && it.extension == "kt" }.toList()
+                            .let { samples.from(it) }
+
+                        // https://kotlinlang.org/docs/dokka-gradle.html#source-link-configuration
+                        // FIXME(android): https://github.com/Kotlin/dokka/issues/2876
+                        @Suppress("ktlint:max-line-length", "ktlint:trailing-comma-on-call-site")
+                        sourceLink {
+                            localDirectory.set(projectDir.resolve("src"))
+                            remoteUrl.set(URL("https://github.com/Adevinta/spark-android/tree/main/${project.name}/src/main/kotlin"))
+                            remoteLineSuffix.set("#L")
+                        }
+                    }
+                }
             }
 
             tasks.withType<DokkaTask> {
                 notCompatibleWithConfigurationCache("https://github.com/Kotlin/dokka/issues/1217")
             }
 
-            tasks.named<DokkaTask>("dokkaHtml").configure {
-                moduleName.set("Spark")
-                dokkaSourceSets.configureEach {
-                    // List of files or directories containing sample code (referenced with @sample tags)
-                    // samples.from("samples/basic.kt", "samples/advanced.kt")
-                }
-            }
-
             dependencies {
                 add("dokkaHtmlPlugin", spark().libraries.`dokka-android-documentation-plugin`)
             }

spark-icons/src/spark-icons.md

@@ -0,0 +1,3 @@
+# Module spark-icons
+
+Icons library module.

spark/src/main/kotlin/com/adevinta/spark/components/badge/Badge.md

@@ -1,4 +1,4 @@
-# Badge components
+# Package com.adevinta.spark.components.badge
 
 ## Badge design specs
 

spark/src/main/kotlin/com/adevinta/spark/components/buttons/Buttons.md

@@ -1,4 +1,4 @@
-# Button components
+# Package com.adevinta.spark.components.buttons
 
 ## Button design specs
 

spark/src/main/kotlin/com/adevinta/spark/components/chips/Chip.md

@@ -1,4 +1,4 @@
-# Chip components
+# Package com.adevinta.spark.components.chips
 
 ## Chip design specs
 

spark/src/main/kotlin/com/adevinta/spark/components/icons/Icon.md

@@ -1,4 +1,4 @@
-# Icon components
+# Package com.adevinta.spark.components.icons
 
 ## Icon design specs
 

spark/src/main/kotlin/com/adevinta/spark/components/progress/Spinner.md

@@ -1,4 +1,4 @@
-# Spinner component
+# Package com.adevinta.spark.components.progress
 
 ## Spinner design specs
 

spark/src/main/kotlin/com/adevinta/spark/components/toggles/CheckBox.md

@@ -1,4 +1,4 @@
-# CheckBox components
+# Package com.adevinta.spark.components.toggles
 
 ## CheckBox design specs
 

spark/src/main/kotlin/com/adevinta/spark/components/toggles/RadioButton.md

@@ -1,4 +1,4 @@
-# RadioButton components
+# Package com.adevinta.spark.components.toggles
 
 ## RadioButton design specs
 

spark/src/main/kotlin/com/adevinta/spark/components/toggles/Switch.md

@@ -1,4 +1,4 @@
-# Switch components
+# Package com.adevinta.spark.components.toggles
 
 ## Switch design specs
 

spark/src/spark.md

@@ -0,0 +1,3 @@
+# Module spark
+
+Main library module.