Contribute Dokkatoo (#3188)

11 files changed, 1419 insertions, 0 deletions

diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/CustomFormatExampleTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/CustomFormatExampleTest.kt
new file mode 100644
index 00000000..b2dbdb1e
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/CustomFormatExampleTest.kt
@@ -0,0 +1,197 @@
+package org.jetbrains.dokka.dokkatoo.tests.examples
+
+import org.jetbrains.dokka.dokkatoo.internal.DokkatooConstants.DOKKA_VERSION
+import org.jetbrains.dokka.dokkatoo.utils.*
+import io.kotest.assertions.withClue
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.file.shouldBeAFile
+import io.kotest.matchers.file.shouldHaveSameStructureAndContentAs
+import io.kotest.matchers.file.shouldHaveSameStructureAs
+import io.kotest.matchers.nulls.shouldNotBeNull
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
+import io.kotest.matchers.string.shouldNotContain
+import java.io.File
+
+class CustomFormatExampleTest : FunSpec({
+
+  val dokkaProject = initDokkaProject(
+    GradleProjectTest.projectTestTempDir.resolve("it/examples/custom-format-dokka").toFile()
+  )
+
+  val dokkatooProject = initDokkatooProject(
+    GradleProjectTest.projectTestTempDir.resolve("it/examples/custom-format-dokkatoo").toFile()
+  )
+
+  context("compare dokka and dokkatoo HTML generators") {
+    test("expect dokka can generate HTML") {
+      dokkaProject.runner
+        .addArguments(
+          "clean",
+          "dokkaHtml",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Generation completed successfully"
+        }
+    }
+
+    test("expect dokkatoo can generate HTML") {
+      dokkatooProject.runner
+        .addArguments(
+          "clean",
+          ":dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContain "BUILD SUCCESSFUL"
+
+          dokkatooProject
+            .findFiles { it.name == "dokka-worker.log" }
+            .shouldBeSingleton { dokkaWorkerLog ->
+              dokkaWorkerLog.shouldNotBeNull().shouldBeAFile()
+              dokkaWorkerLog.readText() shouldContain "Generation completed successfully"
+            }
+        }
+    }
+
+    context("expect dokka and dokkatoo HTML is the same") {
+      val dokkaHtmlDir = dokkaProject.projectDir.resolve("build/dokka/html")
+      val dokkatooHtmlDir = dokkatooProject.projectDir.resolve("build/dokka/html")
+
+      test("expect file trees are the same") {
+        val expectedFileTree = dokkaHtmlDir.toTreeString()
+        val actualFileTree = dokkatooHtmlDir.toTreeString()
+        println((actualFileTree to expectedFileTree).sideBySide())
+        // drop the first line from each, since the directory name is different
+        expectedFileTree.substringAfter("\n") shouldBe actualFileTree.substringAfter("\n")
+      }
+
+      test("expect directories are the same") {
+        dokkatooHtmlDir.toFile().shouldHaveSameStructureAs(dokkaHtmlDir.toFile())
+        dokkatooHtmlDir.toFile().shouldHaveSameStructureAndContentAs(dokkaHtmlDir.toFile())
+      }
+    }
+  }
+
+
+  context("Gradle caching") {
+    test("expect Dokkatoo is compatible with Gradle Build Cache") {
+      dokkatooProject.runner
+        .addArguments(
+          "clean",
+          ":dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContain "BUILD SUCCESSFUL"
+
+          dokkatooProject
+            .findFiles { it.name == "dokka-worker.log" }
+            .shouldBeSingleton { dokkaWorkerLog ->
+              dokkaWorkerLog.shouldNotBeNull().shouldBeAFile()
+              dokkaWorkerLog.readText() shouldContain "Generation completed successfully"
+            }
+        }
+
+      dokkatooProject.runner
+        .addArguments(
+          ":dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--build-cache",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContainAll listOf(
+            "> Task :dokkatooGeneratePublicationHtml UP-TO-DATE",
+            "BUILD SUCCESSFUL",
+            "1 actionable task: 1 up-to-date",
+          )
+          withClue("Dokka Generator should not be triggered, so check it doesn't log anything") {
+            output shouldNotContain "Generation completed successfully"
+          }
+        }
+    }
+
+    context("expect Dokkatoo is compatible with Gradle Configuration Cache") {
+      dokkatooProject.file(".gradle/configuration-cache").toFile().deleteRecursively()
+      dokkatooProject.file("build/reports/configuration-cache").toFile().deleteRecursively()
+
+      val configCacheRunner =
+        dokkatooProject.runner
+          .addArguments(
+            "clean",
+            ":dokkatooGeneratePublicationHtml",
+            "--stacktrace",
+            "--no-build-cache",
+            "--configuration-cache",
+          )
+          .forwardOutput()
+
+      test("first build should store the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry stored"
+          output shouldNotContain "problems were found storing the configuration cache"
+        }
+      }
+
+      test("second build should reuse the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry reused"
+        }
+      }
+    }
+  }
+})
+
+private fun initDokkaProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyExampleProject("custom-format-example/dokka")
+
+    buildGradleKts = buildGradleKts
+      .replace(
+        Regex("""id\("org\.jetbrains\.dokka"\) version \("[\d.]+"\)"""),
+        Regex.escapeReplacement("""id("org.jetbrains.dokka") version "$DOKKA_VERSION""""),
+      )
+      .replace(
+        "org.jetbrains.dokka:dokka-base:1.7.10",
+        "org.jetbrains.dokka:dokka-base:1.7.20",
+      )
+
+    settingsGradleKts = settingsGradleKts
+      .replace(
+        """rootProject.name = "dokka-customFormat-example"""",
+        """rootProject.name = "customFormat-example"""",
+      )
+  }
+}
+
+private fun initDokkatooProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyExampleProject("custom-format-example/dokkatoo")
+
+    buildGradleKts += """
+      |
+      |tasks.withType<org.jetbrains.dokka.dokkatoo.tasks.DokkatooGenerateTask>().configureEach {
+      |  generator.dokkaSourceSets.configureEach {
+      |    sourceSetScope.set(":dokkaHtml") // only necessary for testing
+      |  }
+      |}
+      |
+    """.trimMargin()
+  }
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/GradleExampleTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/GradleExampleTest.kt
new file mode 100644
index 00000000..371ac938
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/GradleExampleTest.kt
@@ -0,0 +1,190 @@
+package org.jetbrains.dokka.dokkatoo.tests.examples
+
+import org.jetbrains.dokka.dokkatoo.internal.DokkatooConstants.DOKKA_VERSION
+import org.jetbrains.dokka.dokkatoo.utils.*
+import org.jetbrains.dokka.dokkatoo.utils.GradleProjectTest.Companion.projectTestTempDir
+import io.kotest.assertions.withClue
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.file.shouldBeAFile
+import io.kotest.matchers.file.shouldHaveSameStructureAndContentAs
+import io.kotest.matchers.file.shouldHaveSameStructureAs
+import io.kotest.matchers.nulls.shouldNotBeNull
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
+import io.kotest.matchers.string.shouldNotContain
+import java.io.File
+import kotlin.text.Regex.Companion.escapeReplacement
+
+class GradleExampleTest : FunSpec({
+
+  val dokkaProject = initDokkaProject(
+    projectTestTempDir.resolve("it/examples/gradle-example/dokka").toFile()
+  )
+
+  val dokkatooProject = initDokkatooProject(
+    projectTestTempDir.resolve("it/examples/gradle-example/dokkatoo").toFile()
+  )
+
+  context("compare dokka and dokkatoo HTML generators") {
+    test("expect dokka can generate HTML") {
+      dokkaProject.runner
+        .addArguments(
+          "clean",
+          "dokkaHtml",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Generation completed successfully"
+        }
+    }
+
+    test("expect dokkatoo can generate HTML") {
+      dokkatooProject.runner
+        .addArguments(
+          "clean",
+          ":dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContain "BUILD SUCCESSFUL"
+
+          dokkatooProject
+            .findFiles { it.name == "dokka-worker.log" }
+            .shouldBeSingleton { dokkaWorkerLog ->
+              dokkaWorkerLog.shouldNotBeNull().shouldBeAFile()
+              dokkaWorkerLog.readText() shouldContain "Generation completed successfully"
+            }
+        }
+    }
+
+    context("expect dokka and dokkatoo HTML is the same") {
+      val dokkaHtmlDir = dokkaProject.projectDir.resolve("build/dokka/html")
+      val dokkatooHtmlDir = dokkatooProject.projectDir.resolve("build/dokka/html")
+
+      test("expect file trees are the same") {
+        val expectedFileTree = dokkaHtmlDir.toTreeString()
+        val actualFileTree = dokkatooHtmlDir.toTreeString()
+        println((actualFileTree to expectedFileTree).sideBySide())
+        expectedFileTree shouldBe actualFileTree
+      }
+
+      test("expect directories are the same") {
+        dokkatooHtmlDir.toFile().shouldHaveSameStructureAs(dokkaHtmlDir.toFile())
+        dokkatooHtmlDir.toFile().shouldHaveSameStructureAndContentAs(dokkaHtmlDir.toFile())
+      }
+    }
+  }
+
+
+  context("Gradle caching") {
+    test("expect Dokkatoo is compatible with Gradle Build Cache") {
+      dokkatooProject.runner
+        .addArguments(
+          "clean",
+          ":dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContain "BUILD SUCCESSFUL"
+
+
+          dokkatooProject
+            .findFiles { it.name == "dokka-worker.log" }
+            .shouldBeSingleton { dokkaWorkerLog ->
+              dokkaWorkerLog.shouldNotBeNull().shouldBeAFile()
+              dokkaWorkerLog.readText() shouldContain "Generation completed successfully"
+            }
+        }
+
+      dokkatooProject.runner
+        .addArguments(
+          ":dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--info",
+          "--build-cache",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContainAll listOf(
+            "> Task :dokkatooGeneratePublicationHtml UP-TO-DATE",
+            "BUILD SUCCESSFUL",
+            "1 actionable task: 1 up-to-date",
+          )
+          withClue("Dokka Generator should not be triggered, so check it doesn't log anything") {
+            output shouldNotContain "Generation completed successfully"
+          }
+        }
+    }
+
+    context("expect Dokkatoo is compatible with Gradle Configuration Cache") {
+      dokkatooProject.file(".gradle/configuration-cache").toFile().deleteRecursively()
+      dokkatooProject.file("build/reports/configuration-cache").toFile().deleteRecursively()
+
+      val configCacheRunner =
+        dokkatooProject.runner
+          .addArguments(
+            "clean",
+            ":dokkatooGeneratePublicationHtml",
+            "--stacktrace",
+            "--no-build-cache",
+            "--configuration-cache",
+          )
+          .forwardOutput()
+
+      test("first build should store the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry stored"
+          output shouldNotContain "problems were found storing the configuration cache"
+        }
+      }
+
+      test("second build should reuse the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry reused"
+        }
+      }
+    }
+  }
+})
+
+
+private fun initDokkaProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyExampleProject("gradle-example/dokka")
+
+    buildGradleKts = buildGradleKts
+      .replace(
+        Regex("""id\("org\.jetbrains\.dokka"\) version \("[\d.]+"\)"""),
+        escapeReplacement("""id("org.jetbrains.dokka") version "$DOKKA_VERSION""""),
+      )
+  }
+}
+
+private fun initDokkatooProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyExampleProject("gradle-example/dokkatoo")
+
+    buildGradleKts += """
+      |
+      |tasks.withType<org.jetbrains.dokka.dokkatoo.tasks.DokkatooGenerateTask>().configureEach {
+      |  generator.dokkaSourceSets.configureEach {
+      |    sourceSetScope.set(":dokkaHtml") // only necessary for testing
+      |  }
+      |}
+      |
+    """.trimMargin()
+  }
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/KotlinMultiplatformExampleTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/KotlinMultiplatformExampleTest.kt
new file mode 100644
index 00000000..4a9efaac
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/KotlinMultiplatformExampleTest.kt
@@ -0,0 +1,226 @@
+package org.jetbrains.dokka.dokkatoo.tests.examples
+
+import org.jetbrains.dokka.dokkatoo.utils.*
+import org.jetbrains.dokka.dokkatoo.utils.GradleProjectTest.Companion.projectTestTempDir
+import io.kotest.assertions.withClue
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.file.shouldBeAFile
+import io.kotest.matchers.file.shouldHaveSameStructureAndContentAs
+import io.kotest.matchers.file.shouldHaveSameStructureAs
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
+import io.kotest.matchers.string.shouldNotContain
+import java.io.File
+
+class KotlinMultiplatformExampleTest : FunSpec({
+
+  val dokkaProject = initDokkaProject(
+    projectTestTempDir.resolve("it/examples/multiplatform-example/dokka").toFile()
+  )
+
+  val dokkatooProject = initDokkatooProject(
+    projectTestTempDir.resolve("it/examples/multiplatform-example/dokkatoo").toFile()
+  )
+
+  context("compare dokka and dokkatoo HTML generators") {
+    test("expect dokka can generate HTML") {
+      dokkaProject.runner
+        .addArguments(
+          "clean",
+          "dokkaHtml",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Generation completed successfully"
+        }
+    }
+
+    context("when Dokkatoo generates HTML") {
+      dokkatooProject.runner
+        .addArguments(
+          "clean",
+          ":dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          test("expect build is successful") {
+            output shouldContain "BUILD SUCCESSFUL"
+          }
+
+          test("expect all dokka workers are successful") {
+            dokkatooProject
+              .findFiles { it.name == "dokka-worker.log" }
+              .shouldBeSingleton { dokkaWorkerLog ->
+                dokkaWorkerLog.shouldBeAFile()
+                dokkaWorkerLog.readText().shouldNotContainAnyOf(
+                  "[ERROR]",
+                  "[WARN]",
+                )
+              }
+          }
+        }
+    }
+
+    context("expect dokka and dokkatoo HTML is the same") {
+      val dokkaHtmlDir =
+        dokkaProject.projectDir.resolve("build/dokka/html")
+      val dokkatooHtmlDir = dokkatooProject.projectDir.resolve("build/dokka/html")
+
+      test("expect file trees are the same") {
+        val expectedFileTree = dokkaHtmlDir.toTreeString()
+        val actualFileTree = dokkatooHtmlDir.toTreeString()
+        println((actualFileTree to expectedFileTree).sideBySide())
+        expectedFileTree shouldBe actualFileTree
+      }
+
+      test("expect directories are the same") {
+        dokkatooHtmlDir.toFile().shouldHaveSameStructureAs(dokkaHtmlDir.toFile())
+        dokkatooHtmlDir.toFile().shouldHaveSameStructureAndContentAs(dokkaHtmlDir.toFile())
+      }
+    }
+  }
+
+
+  context("Gradle caching") {
+
+    context("expect Dokkatoo is compatible with Gradle Build Cache") {
+      dokkatooProject.runner
+        .addArguments(
+          "clean",
+          ":dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+        )
+        .forwardOutput()
+        .build {
+          test("expect build is successful") {
+            output shouldContain "BUILD SUCCESSFUL"
+          }
+
+          test("expect all dokka workers are successful") {
+            dokkatooProject
+              .findFiles { it.name == "dokka-worker.log" }
+              .shouldBeSingleton { dokkaWorkerLog ->
+                dokkaWorkerLog.shouldBeAFile()
+                dokkaWorkerLog.readText().shouldNotContainAnyOf(
+                  "[ERROR]",
+                  "[WARN]",
+                )
+              }
+          }
+        }
+
+      test("expect tasks are UP-TO-DATE") {
+        dokkatooProject.runner
+          .addArguments(
+            ":dokkatooGeneratePublicationHtml",
+            "--stacktrace",
+            "--info",
+            "--build-cache",
+          )
+          .forwardOutput()
+          .build {
+
+            output shouldContainAll listOf(
+              "> Task :dokkatooGeneratePublicationHtml UP-TO-DATE",
+              "BUILD SUCCESSFUL",
+              "2 actionable tasks: 2 up-to-date",
+            )
+            withClue("Dokka Generator should not be triggered, so check it doesn't log anything") {
+              output shouldNotContain "Generation completed successfully"
+            }
+          }
+      }
+    }
+
+    context("expect Dokkatoo is compatible with Gradle Configuration Cache") {
+      dokkatooProject.file(".gradle/configuration-cache").toFile().deleteRecursively()
+      dokkatooProject.file("build/reports/configuration-cache").toFile().deleteRecursively()
+
+      val configCacheRunner =
+        dokkatooProject.runner
+          .addArguments(
+            "clean",
+            ":dokkatooGeneratePublicationHtml",
+            "--stacktrace",
+            "--no-build-cache",
+            "--configuration-cache",
+          )
+          .forwardOutput()
+
+      test("first build should store the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry stored"
+          output shouldNotContain "problems were found storing the configuration cache"
+        }
+      }
+
+      test("second build should reuse the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry reused"
+        }
+      }
+    }
+  }
+})
+
+
+private fun initDokkaProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyExampleProject("multiplatform-example/dokka")
+
+    settingsGradleKts = settingsGradleKts
+      .replace(
+        """pluginManagement {""",
+        """
+          |
+          |pluginManagement {
+          |    repositories {
+          |        gradlePluginPortal()
+          |        mavenCentral()
+          |        mavenLocal()
+          |    }
+          |
+        """.trimMargin()
+      ) + """
+        |
+        |dependencyResolutionManagement {
+        |  repositories {
+        |    mavenCentral()
+        |    mavenLocal()
+        |  }
+        |}
+        |
+      """.trimMargin()
+
+    buildGradleKts += """
+        |
+        |val hackDokkaHtmlDir by tasks.registering(Sync::class) {
+        |  // sync directories so the dirs in both dokka and dokkatoo are the same
+        |  from(layout.buildDirectory.dir("dokka/htmlMultiModule"))
+        |  into(layout.buildDirectory.dir("dokka/html"))
+        |}
+        |
+        |tasks.matching { "dokka" in it.name.toLowerCase() && it.name != hackDokkaHtmlDir.name }.configureEach { 
+        |  finalizedBy(hackDokkaHtmlDir)
+        |}
+        |
+      """.trimMargin()
+  }
+}
+
+private fun initDokkatooProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyExampleProject("multiplatform-example/dokkatoo")
+  }
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/MultimoduleExampleTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/MultimoduleExampleTest.kt
new file mode 100644
index 00000000..8e2215c2
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testExamples/kotlin/MultimoduleExampleTest.kt
@@ -0,0 +1,244 @@
+package org.jetbrains.dokka.dokkatoo.tests.examples
+
+import org.jetbrains.dokka.dokkatoo.internal.DokkatooConstants.DOKKA_VERSION
+import org.jetbrains.dokka.dokkatoo.utils.*
+import org.jetbrains.dokka.dokkatoo.utils.GradleProjectTest.Companion.projectTestTempDir
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.inspectors.shouldForAll
+import io.kotest.matchers.collections.shouldHaveSize
+import io.kotest.matchers.file.shouldBeAFile
+import io.kotest.matchers.file.shouldHaveSameStructureAndContentAs
+import io.kotest.matchers.file.shouldHaveSameStructureAs
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
+import io.kotest.matchers.string.shouldNotContain
+import java.io.File
+import org.gradle.testkit.runner.TaskOutcome.UP_TO_DATE
+
+class MultimoduleExampleTest : FunSpec({
+
+  val dokkaProject = initDokkaProject(
+    projectTestTempDir.resolve("it/examples/multimodule-example/dokka").toFile()
+  )
+
+  val dokkatooProject = initDokkatooProject(
+    projectTestTempDir.resolve("it/examples/multimodule-example/dokkatoo").toFile()
+  )
+
+  context("compare dokka and dokkatoo HTML generators") {
+    test("expect dokka can generate HTML") {
+      dokkaProject.runner
+        .addArguments(
+          "clean",
+          "dokkaHtmlMultiModule",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Generation completed successfully"
+        }
+    }
+
+    context("when Dokkatoo generates HTML") {
+      dokkatooProject.runner
+        .addArguments(
+          "clean",
+          ":parentProject:dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--info",
+        )
+        .forwardOutput()
+        .build {
+          test("expect build is successful") {
+            output shouldContain "BUILD SUCCESSFUL"
+          }
+
+          test("expect all dokka workers are successful") {
+            dokkatooProject
+              .findFiles { it.name == "dokka-worker.log" }
+              .shouldForAll { dokkaWorkerLog ->
+                dokkaWorkerLog.shouldBeAFile()
+                dokkaWorkerLog.readText().shouldNotContainAnyOf(
+                  "[ERROR]",
+                  "[WARN]",
+                )
+              }
+          }
+        }
+    }
+
+    context("expect dokka and dokkatoo HTML is the same") {
+      val dokkaHtmlDir =
+        dokkaProject.projectDir.resolve("parentProject/build/dokka/html")
+      val dokkatooHtmlDir = dokkatooProject.projectDir.resolve("parentProject/build/dokka/html")
+
+      test("expect file trees are the same") {
+        val expectedFileTree = dokkaHtmlDir.toTreeString()
+        val actualFileTree = dokkatooHtmlDir.toTreeString()
+        println((actualFileTree to expectedFileTree).sideBySide())
+        expectedFileTree shouldBe actualFileTree
+      }
+
+      test("expect directories are the same") {
+        dokkatooHtmlDir.toFile().shouldHaveSameStructureAs(dokkaHtmlDir.toFile())
+        dokkatooHtmlDir.toFile().shouldHaveSameStructureAndContentAs(dokkaHtmlDir.toFile())
+      }
+    }
+  }
+
+
+  context("Gradle caching") {
+
+    context("expect Dokkatoo is compatible with Gradle Build Cache") {
+      dokkatooProject.runner
+        .addArguments(
+          "clean",
+          ":parentProject:dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+        )
+        .forwardOutput()
+        .build {
+          test("expect build is successful") {
+            output shouldContain "BUILD SUCCESSFUL"
+          }
+
+          test("expect all dokka workers are successful") {
+            dokkatooProject
+              .findFiles { it.name == "dokka-worker.log" }
+              .shouldForAll { dokkaWorkerLog ->
+                dokkaWorkerLog.shouldBeAFile()
+                dokkaWorkerLog.readText().shouldNotContainAnyOf(
+                  "[ERROR]",
+                  "[WARN]",
+                )
+              }
+          }
+        }
+
+      dokkatooProject.runner
+        .addArguments(
+          ":parentProject:dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--info",
+          "--build-cache",
+        )
+        .forwardOutput()
+        .build {
+          test("expect build is successful") {
+            output shouldContain "BUILD SUCCESSFUL"
+          }
+
+          test("expect all tasks are UP-TO-DATE") {
+            val nonLoggingTasks =
+              tasks.filter { it.name != "logLinkDokkatooGeneratePublicationHtml" }
+            nonLoggingTasks.shouldForAll {
+              it shouldHaveOutcome UP_TO_DATE
+            }
+            tasks.shouldHaveSize(6)
+          }
+
+          test("expect Dokka Generator is not triggered") {
+            // Dokka Generator shouldn't run, so check it doesn't log anything
+            output shouldNotContain "Generation completed successfully"
+          }
+        }
+    }
+
+
+    context("expect Dokkatoo is compatible with Gradle Configuration Cache") {
+      dokkatooProject.file(".gradle/configuration-cache").toFile().deleteRecursively()
+      dokkatooProject.file("build/reports/configuration-cache").toFile().deleteRecursively()
+
+      val configCacheRunner =
+        dokkatooProject.runner
+          .addArguments(
+            "clean",
+            ":parentProject:dokkatooGeneratePublicationHtml",
+            "--stacktrace",
+            "--no-build-cache",
+            "--configuration-cache",
+          )
+          .forwardOutput()
+
+      test("first build should store the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry stored"
+          output shouldNotContain "problems were found storing the configuration cache"
+        }
+      }
+
+      test("second build should reuse the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry reused"
+        }
+      }
+    }
+  }
+})
+
+
+private fun initDokkaProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyExampleProject("multimodule-example/dokka")
+
+    gradleProperties = gradleProperties.lines().joinToString("\n") { line ->
+      when {
+        line.startsWith("dokkaVersion=") -> "dokkaVersion=$DOKKA_VERSION"
+        else                             -> line
+      }
+    }
+
+    settingsGradleKts = settingsGradleKts
+      .replace(
+        """pluginManagement {""",
+        """
+          |
+          |pluginManagement {
+          |    repositories {
+          |        mavenCentral()
+          |        gradlePluginPortal()
+          |    }
+          |
+        """.trimMargin()
+      ) + """
+        |
+        |dependencyResolutionManagement {
+        |  repositories {
+        |    mavenCentral()
+        |  }
+        |}
+        |
+      """.trimMargin()
+
+    dir("parentProject") {
+
+      buildGradleKts += """
+        |
+        |val hackDokkaHtmlDir by tasks.registering(Sync::class) {
+        |  // sync directories so the dirs in both dokka and dokkatoo are the same
+        |  from(layout.buildDirectory.dir("dokka/htmlMultiModule"))
+        |  into(layout.buildDirectory.dir("dokka/html"))
+        |}
+        |
+        |tasks.matching { it.name.contains("dokka", ignoreCase = true) && it.name != hackDokkaHtmlDir.name }.configureEach { 
+        |  finalizedBy(hackDokkaHtmlDir)
+        |}
+        |
+      """.trimMargin()
+    }
+  }
+}
+
+private fun initDokkatooProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyExampleProject("multimodule-example/dokkatoo")
+  }
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testFixtures/kotlin/templateProjectUtils.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testFixtures/kotlin/templateProjectUtils.kt
new file mode 100644
index 00000000..93a52564
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testFixtures/kotlin/templateProjectUtils.kt
@@ -0,0 +1,17 @@
+package  org.jetbrains.dokka.dokkatoo.utils
+
+
+fun GradleProjectTest.copyExampleProject(path: String) {
+  GradleProjectTest.exampleProjectsDir
+    .resolve(path)
+    .toFile()
+    .copyRecursively(projectDir.toFile(), overwrite = true) { _, _ -> OnErrorAction.SKIP }
+}
+
+
+fun GradleProjectTest.copyIntegrationTestProject(path: String) {
+  GradleProjectTest.integrationTestProjectsDir
+    .resolve(path)
+    .toFile()
+    .copyRecursively(projectDir.toFile(), overwrite = true) { _, _ -> OnErrorAction.SKIP }
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/kotlin/AndroidProjectIntegrationTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/kotlin/AndroidProjectIntegrationTest.kt
new file mode 100644
index 00000000..9389a798
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/kotlin/AndroidProjectIntegrationTest.kt
@@ -0,0 +1,166 @@
+package org.jetbrains.dokka.dokkatoo.tests.integration
+
+import org.jetbrains.dokka.dokkatoo.utils.*
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.file.shouldBeAFile
+import io.kotest.matchers.file.shouldHaveSameStructureAndContentAs
+import io.kotest.matchers.file.shouldHaveSameStructureAs
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
+import io.kotest.matchers.string.shouldNotContain
+import java.io.File
+import kotlin.io.path.deleteIfExists
+
+/**
+ * Integration test for the `it-android-0` project in Dokka
+ *
+ * Runs Dokka & Dokkatoo, and compares the resulting HTML site.
+ */
+class AndroidProjectIntegrationTest : FunSpec({
+
+  val tempDir = GradleProjectTest.projectTestTempDir.resolve("it/it-android-0").toFile()
+
+  val dokkatooProject = initDokkatooProject(tempDir.resolve("dokkatoo"))
+  val dokkaProject = initDokkaProject(tempDir.resolve("dokka"))
+
+  context("when generating HTML") {
+    context("with Dokka") {
+      dokkaProject.runner
+        .addArguments(
+          "clean",
+          "dokkaHtml",
+          "--stacktrace",
+        )
+        .forwardOutput()
+        .build {
+          test("expect project builds successfully") {
+            output shouldContain "BUILD SUCCESSFUL"
+          }
+        }
+    }
+
+    context("with Dokkatoo") {
+      dokkatooProject.runner
+        .addArguments(
+          "clean",
+          "dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+        )
+        .forwardOutput()
+        .build {
+          test("expect project builds successfully") {
+            output shouldContain "BUILD SUCCESSFUL"
+          }
+
+          test("expect all dokka workers are successful") {
+            dokkatooProject
+              .findFiles { it.name == "dokka-worker.log" }
+              .shouldBeSingleton { dokkaWorkerLog ->
+                dokkaWorkerLog.shouldBeAFile()
+                dokkaWorkerLog.readText().shouldNotContainAnyOf(
+                  "[ERROR]",
+                  "[WARN]",
+                )
+              }
+          }
+        }
+    }
+
+    test("expect the same HTML is generated") {
+
+      val dokkaHtmlDir = dokkaProject.projectDir.resolve("build/dokka/html")
+      val dokkatooHtmlDir = dokkatooProject.projectDir.resolve("build/dokka/html")
+
+      val expectedFileTree = dokkaHtmlDir.toTreeString()
+      val actualFileTree = dokkatooHtmlDir.toTreeString()
+      println((actualFileTree to expectedFileTree).sideBySide())
+      expectedFileTree shouldBe actualFileTree
+
+      dokkatooHtmlDir.toFile().shouldHaveSameStructureAs(dokkaHtmlDir.toFile())
+      dokkatooHtmlDir.toFile().shouldHaveSameStructureAndContentAs(dokkaHtmlDir.toFile())
+    }
+
+    test("Dokkatoo tasks should be cacheable") {
+      dokkatooProject.runner
+        .addArguments(
+          "dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--build-cache",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContainAll listOf(
+            "Task :dokkatooGeneratePublicationHtml UP-TO-DATE",
+          )
+        }
+    }
+
+    context("expect Dokkatoo is compatible with Gradle Configuration Cache") {
+      dokkatooProject.file(".gradle/configuration-cache").toFile().deleteRecursively()
+      dokkatooProject.file("build/reports/configuration-cache").toFile().deleteRecursively()
+
+      val configCacheRunner =
+        dokkatooProject.runner
+          .addArguments(
+            "clean",
+            "dokkatooGeneratePublicationHtml",
+            "--stacktrace",
+            "--no-build-cache",
+            "--configuration-cache",
+          )
+          .forwardOutput()
+
+      test("first build should store the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry stored"
+          output shouldNotContain "problems were found storing the configuration cache"
+        }
+      }
+
+      test("second build should reuse the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry reused"
+        }
+      }
+    }
+  }
+})
+
+private fun initDokkaProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyIntegrationTestProject("it-android-0/dokka")
+
+    gradleProperties = gradleProperties
+      .replace(
+        "dokka_it_android_gradle_plugin_version=4.2.2",
+        "dokka_it_android_gradle_plugin_version=8.0.2",
+      )
+
+    file("src/main/AndroidManifest.xml").deleteIfExists()
+
+    buildGradleKts += """
+      
+      android {
+        namespace = "org.jetbrains.dokka.it.android"
+      }
+      
+      java {
+          toolchain {
+              languageVersion.set(JavaLanguageVersion.of(17))
+          }
+      }
+    """.trimIndent()
+  }
+}
+
+private fun initDokkatooProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyIntegrationTestProject("it-android-0/dokkatoo")
+  }
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/kotlin/BasicProjectIntegrationTest.kt b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/kotlin/BasicProjectIntegrationTest.kt
new file mode 100644
index 00000000..265e7c18
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/kotlin/BasicProjectIntegrationTest.kt
@@ -0,0 +1,153 @@
+package org.jetbrains.dokka.dokkatoo.tests.integration
+
+import org.jetbrains.dokka.dokkatoo.utils.*
+import org.jetbrains.dokka.dokkatoo.utils.GradleProjectTest.Companion.projectTestTempDir
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.file.shouldBeAFile
+import io.kotest.matchers.file.shouldHaveSameStructureAndContentAs
+import io.kotest.matchers.file.shouldHaveSameStructureAs
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
+import io.kotest.matchers.string.shouldNotContain
+import java.io.File
+
+/**
+ * Integration test for the `it-basic` project in Dokka
+ *
+ * Runs Dokka & Dokkatoo, and compares the resulting HTML site.
+ */
+class BasicProjectIntegrationTest : FunSpec({
+
+  val tempDir = projectTestTempDir.resolve("it/it-basic").toFile()
+
+  val dokkatooProject = initDokkatooProject(tempDir.resolve("dokkatoo"))
+  val dokkaProject = initDokkaProject(tempDir.resolve("dokka"))
+
+  context("when generating HTML") {
+    dokkaProject.runner
+      .addArguments(
+        "clean",
+        "dokkaHtml",
+        "--stacktrace",
+      )
+      .forwardOutput()
+      .build {
+        context("with Dokka") {
+          test("expect project builds successfully") {
+            output shouldContain "BUILD SUCCESSFUL"
+          }
+        }
+      }
+
+    dokkatooProject.runner
+      .addArguments(
+        "clean",
+        "dokkatooGeneratePublicationHtml",
+        "--stacktrace",
+      )
+      .forwardOutput()
+      .build {
+        context("with Dokkatoo") {
+          test("expect project builds successfully") {
+            output shouldContain "BUILD SUCCESSFUL"
+          }
+
+          test("expect all dokka workers are successful") {
+            dokkatooProject
+              .findFiles { it.name == "dokka-worker.log" }
+              .shouldBeSingleton { dokkaWorkerLog ->
+                dokkaWorkerLog.shouldBeAFile()
+                dokkaWorkerLog.readText().shouldNotContainAnyOf(
+                  "[ERROR]",
+                  "[WARN]",
+                )
+              }
+          }
+        }
+      }
+
+    test("expect the same HTML is generated") {
+
+      val dokkaHtmlDir = dokkaProject.projectDir.resolve("build/dokka/html")
+      val dokkatooHtmlDir = dokkatooProject.projectDir.resolve("build/dokka/html")
+
+      val expectedFileTree = dokkaHtmlDir.toTreeString()
+      val actualFileTree = dokkatooHtmlDir.toTreeString()
+      println((actualFileTree to expectedFileTree).sideBySide())
+      expectedFileTree shouldBe actualFileTree
+
+      dokkatooHtmlDir.toFile().shouldHaveSameStructureAs(dokkaHtmlDir.toFile())
+      dokkatooHtmlDir.toFile().shouldHaveSameStructureAndContentAs(dokkaHtmlDir.toFile())
+    }
+
+    test("Dokkatoo tasks should be cacheable") {
+      dokkatooProject.runner
+        .addArguments(
+          "dokkatooGeneratePublicationHtml",
+          "--stacktrace",
+          "--build-cache",
+        )
+        .forwardOutput()
+        .build {
+          output shouldContainAll listOf(
+            "Task :dokkatooGeneratePublicationHtml UP-TO-DATE",
+          )
+        }
+    }
+
+    context("expect Dokkatoo is compatible with Gradle Configuration Cache") {
+      dokkatooProject.file(".gradle/configuration-cache").toFile().deleteRecursively()
+      dokkatooProject.file("build/reports/configuration-cache").toFile().deleteRecursively()
+
+      val configCacheRunner =
+        dokkatooProject.runner
+          .addArguments(
+            "clean",
+            "dokkatooGeneratePublicationHtml",
+            "--stacktrace",
+            "--no-build-cache",
+            "--configuration-cache",
+          )
+          .forwardOutput()
+
+      test("first build should store the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry stored"
+          output shouldNotContain "problems were found storing the configuration cache"
+        }
+      }
+
+      test("second build should reuse the configuration cache") {
+        configCacheRunner.build {
+          output shouldContain "BUILD SUCCESSFUL"
+          output shouldContain "Configuration cache entry reused"
+        }
+      }
+    }
+  }
+})
+
+
+private fun initDokkaProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyIntegrationTestProject("it-basic/dokka")
+
+    buildGradleKts = buildGradleKts
+      .replace(
+        // no idea why this needs to be changed
+        """file("../customResources/""",
+        """file("./customResources/""",
+      )
+  }
+}
+
+private fun initDokkatooProject(
+  destinationDir: File,
+): GradleProjectTest {
+  return GradleProjectTest(destinationDir.toPath()).apply {
+    copyIntegrationTestProject("it-basic/dokkatoo")
+  }
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/childProjectA.json b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/childProjectA.json
new file mode 100644
index 00000000..21b8498f
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/childProjectA.json
@@ -0,0 +1,83 @@
+{
+  "moduleName": "childProjectA",
+  "moduleVersion": "unspecified",
+  "outputDir": ".../dokka-multimodule-example/parentProject/childProjectA/build/dokka/htmlPartial",
+  "cacheRoot": null,
+  "offlineMode": false,
+  "sourceSets": [
+    {
+      "displayName": "jvm",
+      "sourceSetID": {
+        "scopeId": ":parentProject:childProjectA:dokkaHtmlPartial",
+        "sourceSetName": "main"
+      },
+      "classpath": [
+        ".../kotlin-stdlib-1.7.20.jar",
+        ".../kotlin-stdlib-common-1.7.20.jar",
+        ".../annotations-13.0.jar"
+      ],
+      "sourceRoots": [
+        ".../dokka-multimodule-example/parentProject/childProjectA/src/main/kotlin"
+      ],
+      "dependentSourceSets": [],
+      "samples": [],
+      "includes": [
+        ".../dokka-multimodule-example/parentProject/childProjectA/Module.md"
+      ],
+      "includeNonPublic": false,
+      "reportUndocumented": false,
+      "skipEmptyPackages": true,
+      "skipDeprecated": false,
+      "jdkVersion": 8,
+      "sourceLinks": [],
+      "perPackageOptions": [],
+      "externalDocumentationLinks": [
+        {
+          "url": "https://kotlinlang.org/api/latest/jvm/stdlib/",
+          "packageListUrl": "https://kotlinlang.org/api/latest/jvm/stdlib/package-list"
+        },
+        {
+          "url": "https://docs.oracle.com/javase/8/docs/api/",
+          "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
+        }
+      ],
+      "languageVersion": null,
+      "apiVersion": null,
+      "noStdlibLink": false,
+      "noJdkLink": false,
+      "suppressedFiles": [],
+      "analysisPlatform": "jvm",
+      "documentedVisibilities": [
+        "PUBLIC"
+      ]
+    }
+  ],
+  "pluginsClasspath": [
+    ".../dokka-analysis-for-integration-tests-SNAPSHOT.jar",
+    ".../dokka-base-for-integration-tests-SNAPSHOT.jar",
+    ".../kotlin-analysis-intellij-for-integration-tests-SNAPSHOT.jar",
+    ".../kotlin-analysis-compiler-for-integration-tests-SNAPSHOT.jar",
+    ".../kotlinx-html-jvm-0.7.5.jar",
+    ".../kotlinx-coroutines-core-jvm-1.6.3.jar",
+    ".../kotlin-stdlib-jdk8-1.7.20.jar",
+    ".../jackson-databind-2.12.7.jar",
+    ".../jackson-annotations-2.12.7.jar",
+    ".../jackson-core-2.12.7.jar",
+    ".../jackson-module-kotlin-2.12.7.jar",
+    ".../kotlin-reflect-1.7.20.jar",
+    ".../kotlin-stdlib-jdk7-1.7.20.jar",
+    ".../kotlin-stdlib-1.7.20.jar",
+    ".../jsoup-1.14.3.jar",
+    ".../freemarker-2.3.31.jar",
+    ".../kotlin-stdlib-common-1.7.20.jar",
+    ".../annotations-13.0.jar"
+  ],
+  "pluginsConfiguration": [],
+  "modules": [],
+  "failOnWarning": false,
+  "delayTemplateSubstitution": true,
+  "suppressObviousFunctions": true,
+  "includes": [],
+  "suppressInheritedMembers": false,
+  "finalizeCoroutines": true
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/childProjectB.json b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/childProjectB.json
new file mode 100644
index 00000000..98d218d3
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/childProjectB.json
@@ -0,0 +1,83 @@
+{
+  "moduleName": "childProjectB",
+  "moduleVersion": "unspecified",
+  "outputDir": ".../dokka-multimodule-example/parentProject/childProjectB/build/dokka/htmlPartial",
+  "cacheRoot": null,
+  "offlineMode": false,
+  "sourceSets": [
+    {
+      "displayName": "jvm",
+      "sourceSetID": {
+        "scopeId": ":parentProject:childProjectB:dokkaHtmlPartial",
+        "sourceSetName": "main"
+      },
+      "classpath": [
+        ".../kotlin-stdlib-1.7.20.jar",
+        ".../kotlin-stdlib-common-1.7.20.jar",
+        ".../annotations-13.0.jar"
+      ],
+      "sourceRoots": [
+        ".../dokka-multimodule-example/parentProject/childProjectB/src/main/kotlin"
+      ],
+      "dependentSourceSets": [],
+      "samples": [],
+      "includes": [
+        ".../dokka-multimodule-example/parentProject/childProjectB/Module.md"
+      ],
+      "includeNonPublic": false,
+      "reportUndocumented": false,
+      "skipEmptyPackages": true,
+      "skipDeprecated": false,
+      "jdkVersion": 8,
+      "sourceLinks": [],
+      "perPackageOptions": [],
+      "externalDocumentationLinks": [
+        {
+          "url": "https://kotlinlang.org/api/latest/jvm/stdlib/",
+          "packageListUrl": "https://kotlinlang.org/api/latest/jvm/stdlib/package-list"
+        },
+        {
+          "url": "https://docs.oracle.com/javase/8/docs/api/",
+          "packageListUrl": "https://docs.oracle.com/javase/8/docs/api/package-list"
+        }
+      ],
+      "languageVersion": null,
+      "apiVersion": null,
+      "noStdlibLink": false,
+      "noJdkLink": false,
+      "suppressedFiles": [],
+      "analysisPlatform": "jvm",
+      "documentedVisibilities": [
+        "PUBLIC"
+      ]
+    }
+  ],
+  "pluginsClasspath": [
+    ".../dokka-analysis-for-integration-tests-SNAPSHOT.jar",
+    ".../dokka-base-for-integration-tests-SNAPSHOT.jar",
+    ".../kotlin-analysis-intellij-for-integration-tests-SNAPSHOT.jar",
+    ".../kotlin-analysis-compiler-for-integration-tests-SNAPSHOT.jar",
+    ".../kotlinx-html-jvm-0.7.5.jar",
+    ".../kotlinx-coroutines-core-jvm-1.6.3.jar",
+    ".../kotlin-stdlib-jdk8-1.7.20.jar",
+    ".../jackson-databind-2.12.7.jar",
+    ".../jackson-annotations-2.12.7.jar",
+    ".../jackson-core-2.12.7.jar",
+    ".../jackson-module-kotlin-2.12.7.jar",
+    ".../kotlin-reflect-1.7.20.jar",
+    ".../kotlin-stdlib-jdk7-1.7.20.jar",
+    ".../kotlin-stdlib-1.7.20.jar",
+    ".../jsoup-1.14.3.jar",
+    ".../freemarker-2.3.31.jar",
+    ".../kotlin-stdlib-common-1.7.20.jar",
+    ".../annotations-13.0.jar"
+  ],
+  "pluginsConfiguration": [],
+  "modules": [],
+  "failOnWarning": false,
+  "delayTemplateSubstitution": true,
+  "suppressObviousFunctions": true,
+  "includes": [],
+  "suppressInheritedMembers": false,
+  "finalizeCoroutines": true
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/parentProject.json b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/parentProject.json
new file mode 100644
index 00000000..fb300e37
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/parentProject.json
@@ -0,0 +1,55 @@
+{
+  "moduleName": "parentProject",
+  "moduleVersion": null,
+  "outputDir": ".../dokka-multimodule-example/parentProject/build/dokka/htmlMultiModule",
+  "cacheRoot": null,
+  "offlineMode": false,
+  "sourceSets": [],
+  "pluginsClasspath": [
+    ".../dokka-analysis-for-integration-tests-SNAPSHOT.jar",
+    ".../all-modules-page-plugin-for-integration-tests-SNAPSHOT.jar",
+    ".../templating-plugin-for-integration-tests-SNAPSHOT.jar",
+    ".../dokka-base-for-integration-tests-SNAPSHOT.jar",
+    ".../kotlin-analysis-intellij-for-integration-tests-SNAPSHOT.jar",
+    ".../kotlin-analysis-compiler-for-integration-tests-SNAPSHOT.jar",
+    "../kotlinx-html-jvm-0.7.5.jar",
+    "../kotlinx-coroutines-core-jvm-1.6.3.jar",
+    "../kotlin-stdlib-jdk8-1.7.20.jar",
+    "../jackson-databind-2.12.7.jar",
+    "../jackson-annotations-2.12.7.jar",
+    "../jackson-core-2.12.7.jar",
+    "../jackson-module-kotlin-2.12.7.jar",
+    "../kotlin-reflect-1.7.20.jar",
+    "../kotlin-stdlib-jdk7-1.7.20.jar",
+    "../kotlin-stdlib-1.7.20.jar",
+    "../jsoup-1.14.3.jar",
+    "../freemarker-2.3.31.jar",
+    "../kotlin-stdlib-common-1.7.20.jar",
+    "../annotations-13.0.jar"
+  ],
+  "pluginsConfiguration": [],
+  "modules": [
+    {
+      "name": "childProjectA",
+      "relativePathToOutputDirectory": "childProjectA",
+      "includes": [
+        ".../dokka-multimodule-example/parentProject/childProjectA/Module.md"
+      ],
+      "sourceOutputDirectory": ".../dokka-multimodule-example/parentProject/childProjectA/build/dokka/htmlPartial"
+    },
+    {
+      "name": "childProjectB",
+      "relativePathToOutputDirectory": "childProjectB",
+      "includes": [
+        ".../dokka-multimodule-example/parentProject/childProjectB/Module.md"
+      ],
+      "sourceOutputDirectory": ".../dokka-multimodule-example/parentProject/childProjectB/build/dokka/htmlPartial"
+    }
+  ],
+  "failOnWarning": false,
+  "delayTemplateSubstitution": false,
+  "suppressObviousFunctions": true,
+  "includes": [],
+  "suppressInheritedMembers": false,
+  "finalizeCoroutines": true
+}
diff --git a/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/readme.md b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/readme.md
new file mode 100644
index 00000000..cffaf26b
--- /dev/null
+++ b/dokka-runners/dokkatoo/modules/dokkatoo-plugin-integration-tests/src/testIntegration/resources/it/example/dokka-multi-module/readme.md
@@ -0,0 +1,5 @@
+This directory contains example JSON that the current Dokka plugin generates
+for the dokka-multi-module example.
+
+It is committed here for development so that I can manually compare and contrast.
+In time, these files can be removed.