Add composite build example (#200)

* Add composite build example

* add 'clue' to flaky test

* add DuplicateModulePathWarningTest test

* bump MultiModuleProject.kt KGP to embeddedKotlinVersion so it's more likely to stay up to date

* skip empty dirs in test (empty dirs can't be committed to git, so this is an easy workaround)

* fix dir comparison assertions to optionally filter out empty files

* tidy

.gitattributes

@@ -44,6 +44,7 @@ examples/*/dokka                                                      linguist-v
 examples/versioning-multimodule-example/dokka/previousDocVersions     linguist-generated
 examples/versioning-multimodule-example/dokkatoo/previousDocVersions  linguist-generated
 modules/docs/**                                                       linguist-documentation
+modules/dokkatoo-plugin-integration-tests/example-project-data        linguist-generated
 modules/dokkatoo-plugin-integration-tests/projects/**dokka/           linguist-vendored
 modules/dokkatoo-plugin-integration-tests/projects/**dokkatoo/        linguist-documentation
 

build.gradle.kts

@@ -26,6 +26,7 @@ idea {
         "ANDROID_SDK",
         "examples/versioning-multimodule-example/dokkatoo/previousDocVersions",
         "examples/versioning-multimodule-example/dokka/previousDocVersions",
+        "modules/dokkatoo-plugin-integration-tests/example-project-data",
       )
       addAll(
         projectDir.walk().filter { file ->

examples/README.md

@@ -8,11 +8,16 @@ The examples are copied from the Dokka project.
 
 The Dokka examples are synced automatically from the Dokka source code.
 
+### Run locally
+
+To run locally the examples locally you must first run `./gradlew assemble`
+in the root Dokkatoo repository project directory.
+
 ### Tests
 
 The projects are tested in the
 [`:modules:dokkatoo-plugin-integration-tests`](./../modules/dokkatoo-plugin-integration-tests/)
 project.
 
-The Dokka Publications generated by the Dokka examples are compared against the Dokka 
+The Dokka Publications generated by the Dokka examples are compared against the Dokka
 Publications generated by the Dokkatoo projects.

examples/composite-build-example/dokkatoo/README.md

@@ -0,0 +1,38 @@
+# Dokkatoo Composite Build Example
+
+This project demonstrates how to use Dokkatoo to aggregate modules across a
+[composite build projects](https://docs.gradle.org/current/userguide/composite_builds.html).
+
+> [!WARN]
+> HTML is the only format that correctly supports multimodule aggregation.
+> This is a limitation of Dokka.
+
+### Summary
+
+There are 4 included builds.
+
+* [`build-logic`](./build-logic) contains Kotlin/JVM and Dokkatoo convention plugins.
+* [`module-kakapo`](./module-kakapo) and [`module-kea`](./module-kea)
+  (named after [New Zealand birds](https://en.wikipedia.org/wiki/Birds_of_New_Zealand))
+  represent regular Kotlin/JVM projects.
+* [`docs`](./docs) aggregates the modules.
+
+### Run locally
+
+To run locally, follow these steps.
+
+1. In the root Dokkatoo project directory, run `./gradlew assemble`.
+2. Either open the example project in an IDE, or `cd` into it.
+3. In the example project, run `gradle build`.
+
+The docs will be generated into [`./docs/build/dokka/`](./docs/build/dokka/).
+
+> [!IMPORTANT]
+> When Dokkatoo aggregates modules, each module **must** have a distinct `modulePath`.
+> By default, this path is set to be the project path. With composite builds these
+> paths may not be distinct, causing Dokkatoo to overwrite modules.
+>
+> When using composite builds, project paths may clash, so make sure to set a distinct `modulePath`.
+>
+> This can be achieved in a convention plugin.
+> [build-logic/src/main/kotlin/dokka-convention.gradle.kts](./build-logic/src/main/kotlin/dokka-convention.gradle.kts). 

examples/composite-build-example/dokkatoo/build-logic/build.gradle.kts

@@ -0,0 +1,8 @@
+plugins {
+  `kotlin-dsl`
+}
+
+dependencies {
+  implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:$embeddedKotlinVersion")
+  implementation("dev.adamko.dokkatoo:dokkatoo-plugin:2.3.0-SNAPSHOT")
+}

examples/composite-build-example/dokkatoo/build-logic/settings.gradle.kts

@@ -0,0 +1,47 @@
+rootProject.name = "build-logic"
+
+pluginManagement {
+  repositories {
+    mavenCentral()
+    gradlePluginPortal()
+    exclusiveContent {
+      forRepository {
+        maven(providers.gradleProperty("testMavenRepo")) {
+          name = "DokkatooTestMavenRepo"
+        }
+      }
+      filter {
+        includeGroup("dev.adamko.dokkatoo")
+        includeGroup("dev.adamko.dokkatoo-html")
+        includeGroup("dev.adamko.dokkatoo-javadoc")
+        includeGroup("dev.adamko.dokkatoo-jekyll")
+        includeGroup("dev.adamko.dokkatoo-gfm")
+      }
+    }
+  }
+}
+
+@Suppress("UnstableApiUsage")
+dependencyResolutionManagement {
+
+  repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
+
+  repositories {
+    mavenCentral()
+    gradlePluginPortal()
+    exclusiveContent {
+      forRepository {
+        maven(providers.gradleProperty("testMavenRepo")) {
+          name = "DokkatooTestMavenRepo"
+        }
+      }
+      filter {
+        includeGroup("dev.adamko.dokkatoo")
+        includeGroup("dev.adamko.dokkatoo-html")
+        includeGroup("dev.adamko.dokkatoo-javadoc")
+        includeGroup("dev.adamko.dokkatoo-jekyll")
+        includeGroup("dev.adamko.dokkatoo-gfm")
+      }
+    }
+  }
+}

examples/composite-build-example/dokkatoo/build-logic/src/main/kotlin/dokka-convention.gradle.kts

@@ -0,0 +1,13 @@
+/**
+ * Common conventions for generating documentation with Dokkatoo.
+ */
+
+plugins {
+  id("dev.adamko.dokkatoo-html")
+}
+
+dokkatoo {
+  // Important! Ensure that each project has a distinct module path.
+  // See the example README for more information.
+  modulePath = rootProject.name + project.path.replace(":", "/")
+}

examples/composite-build-example/dokkatoo/build-logic/src/main/kotlin/kotlin-jvm-convention.gradle.kts

@@ -0,0 +1,7 @@
+plugins {
+  kotlin("jvm")
+}
+
+kotlin {
+  jvmToolchain(11)
+}

examples/composite-build-example/dokkatoo/build.gradle.kts

@@ -0,0 +1,19 @@
+plugins {
+  base
+}
+
+tasks.build {
+  dependsOn(gradle.includedBuild("docs").task(":dokkatooGenerate"))
+}
+
+group = "foo.example.composite.builds"
+version = "1.0.1"
+
+
+tasks.clean {
+  dependsOn(
+    gradle.includedBuild("docs").task(":clean"),
+    gradle.includedBuild("module-kakapo").task(":clean"),
+    gradle.includedBuild("module-kea").task(":clean"),
+  )
+}

examples/composite-build-example/dokkatoo/docs/build.gradle.kts

@@ -0,0 +1,12 @@
+plugins {
+  id("dokka-convention")
+}
+
+dependencies {
+  dokkatoo("foo.example:module-kakapo")
+  dokkatoo("foo.example:module-kea")
+}
+
+dokkatoo {
+  moduleName = "Dokkatoo Composite Builds Example"
+}

examples/composite-build-example/dokkatoo/docs/settings.gradle.kts

@@ -0,0 +1,47 @@
+rootProject.name = "docs"
+
+pluginManagement {
+  includeBuild("../build-logic")
+  repositories {
+    mavenCentral()
+    gradlePluginPortal()
+    exclusiveContent {
+      forRepository {
+        maven(providers.gradleProperty("testMavenRepo")) {
+          name = "DokkatooTestMavenRepo"
+        }
+      }
+      filter {
+        includeGroup("dev.adamko.dokkatoo")
+        includeGroup("dev.adamko.dokkatoo-html")
+        includeGroup("dev.adamko.dokkatoo-javadoc")
+        includeGroup("dev.adamko.dokkatoo-jekyll")
+        includeGroup("dev.adamko.dokkatoo-gfm")
+      }
+    }
+  }
+}
+
+@Suppress("UnstableApiUsage")
+dependencyResolutionManagement {
+  repositories {
+    mavenCentral()
+    exclusiveContent {
+      forRepository {
+        maven(providers.gradleProperty("testMavenRepo")) {
+          name = "DokkatooTestMavenRepo"
+        }
+      }
+      filter {
+        includeGroup("dev.adamko.dokkatoo")
+        includeGroup("dev.adamko.dokkatoo-html")
+        includeGroup("dev.adamko.dokkatoo-javadoc")
+        includeGroup("dev.adamko.dokkatoo-jekyll")
+        includeGroup("dev.adamko.dokkatoo-gfm")
+      }
+    }
+  }
+}
+
+includeBuild("../module-kakapo")
+includeBuild("../module-kea")

examples/composite-build-example/dokkatoo/module-kakapo/build.gradle.kts

@@ -0,0 +1,12 @@
+plugins {
+  id("kotlin-jvm-convention")
+  id("dokka-convention")
+}
+
+group = "foo.example"
+version = "1.2.3"
+
+dokkatoo {
+  moduleName = "Kakapo Module"
+  modulePath = "kakakpo"
+}

examples/composite-build-example/dokkatoo/module-kakapo/settings.gradle.kts

@@ -0,0 +1,44 @@
+rootProject.name = "module-kakapo"
+
+pluginManagement {
+  includeBuild("../build-logic")
+  repositories {
+    mavenCentral()
+    gradlePluginPortal()
+    exclusiveContent {
+      forRepository {
+        maven(providers.gradleProperty("testMavenRepo")) {
+          name = "DokkatooTestMavenRepo"
+        }
+      }
+      filter {
+        includeGroup("dev.adamko.dokkatoo")
+        includeGroup("dev.adamko.dokkatoo-html")
+        includeGroup("dev.adamko.dokkatoo-javadoc")
+        includeGroup("dev.adamko.dokkatoo-jekyll")
+        includeGroup("dev.adamko.dokkatoo-gfm")
+      }
+    }
+  }
+}
+
+@Suppress("UnstableApiUsage")
+dependencyResolutionManagement {
+  repositories {
+    mavenCentral()
+    exclusiveContent {
+      forRepository {
+        maven(providers.gradleProperty("testMavenRepo")) {
+          name = "DokkatooTestMavenRepo"
+        }
+      }
+      filter {
+        includeGroup("dev.adamko.dokkatoo")
+        includeGroup("dev.adamko.dokkatoo-html")
+        includeGroup("dev.adamko.dokkatoo-javadoc")
+        includeGroup("dev.adamko.dokkatoo-jekyll")
+        includeGroup("dev.adamko.dokkatoo-gfm")
+      }
+    }
+  }
+}

examples/composite-build-example/dokkatoo/module-kakapo/src/main/kotlin/Kakapo.kt

@@ -0,0 +1,12 @@
+package foo.example.module.kakapo
+
+class Kakapo {
+  val description = """
+    The Kakapo (Strigops habroptilus) is the only parrot which cannot fly.
+    
+    It lives in grassland, scrubland and coastal regions of New Zealand, but is now so rare they can only be seen
+    on protected offshore islands.
+    
+    Kakapo means 'night parrot' in the Māori language.
+  """.trimIndent()
+}

examples/composite-build-example/dokkatoo/module-kea/build.gradle.kts

@@ -0,0 +1,12 @@
+plugins {
+  id("kotlin-jvm-convention")
+  id("dokka-convention")
+}
+
+group = "foo.example"
+version = "4.5.6"
+
+dokkatoo {
+  moduleName = "Kea Module"
+  modulePath = "kea"
+}

examples/composite-build-example/dokkatoo/module-kea/settings.gradle.kts

@@ -0,0 +1,44 @@
+rootProject.name = "module-kea"
+
+pluginManagement {
+  includeBuild("../build-logic")
+  repositories {
+    mavenCentral()
+    gradlePluginPortal()
+    exclusiveContent {
+      forRepository {
+        maven(providers.gradleProperty("testMavenRepo")) {
+          name = "DokkatooTestMavenRepo"
+        }
+      }
+      filter {
+        includeGroup("dev.adamko.dokkatoo")
+        includeGroup("dev.adamko.dokkatoo-html")
+        includeGroup("dev.adamko.dokkatoo-javadoc")
+        includeGroup("dev.adamko.dokkatoo-jekyll")
+        includeGroup("dev.adamko.dokkatoo-gfm")
+      }
+    }
+  }
+}
+
+@Suppress("UnstableApiUsage")
+dependencyResolutionManagement {
+  repositories {
+    mavenCentral()
+    exclusiveContent {
+      forRepository {
+        maven(providers.gradleProperty("testMavenRepo")) {
+          name = "DokkatooTestMavenRepo"
+        }
+      }
+      filter {
+        includeGroup("dev.adamko.dokkatoo")
+        includeGroup("dev.adamko.dokkatoo-html")
+        includeGroup("dev.adamko.dokkatoo-javadoc")
+        includeGroup("dev.adamko.dokkatoo-jekyll")
+        includeGroup("dev.adamko.dokkatoo-gfm")
+      }
+    }
+  }
+}

examples/composite-build-example/dokkatoo/module-kea/src/main/kotlin/Kea.kt

@@ -0,0 +1,10 @@
+package foo.example.module.kea
+
+class Kea {
+  val description = """
+    The kea (Nestor notabilis) is a large parrot.
+    
+    It lives in forests and high rocky hills on the South Island of New Zealand. It is mostly olive-green in color.
+    It has a large, narrow, curved, grey-brown upper beak. The kea is the only parrot in the world that lives in alpine habitats.
+  """.trimIndent()
+}