Contribute Dokkatoo (#3188)

6 files changed, 545 insertions, 0 deletions

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.