refactor examples and integration tests (#7)

* refactor examples and integration tests

- example and integration test projects are automatically copied from Dokka src
- integration tests will use the example and integration tests projects

* prep dokkatoo example projects

* updating integration tests and test projects

* git ignore gradle.properties in dokkatoo examples

* add code for includeBuild-ing the example projects

* setup dokkatoo gradle-example

* a bit of integration-test refactoring

* add remoteUrl util function

* rm setting null into dokkatooCacheDirectory (it's not necessary)

* update a couple of build script comments

* implement GradleExampleTest

* update .gitignore to be more comprehensive

* add options for increasing DokkaGenerator memory, and also increase the memory

* increase Gradle memory

* fix BasicProjectIntegrationTest

* try fixing task updateGradlePropertiesInDokkatooExamples

* move the integration tests into separate sourceSets

* the integration tests keep running out of memory, so fork on every test

* try fixing testMavenRepo on Windows

* try fixing testMavenRepo on Windows

* try fixing testMavenRepo on Windows

* try fixing testMavenRepo on Windows

* try increases MaxMetaspace Kotlin/dokka#1405

* try fixing updateTestReportCss task output warnings

* more memory increasing

.gitattributes

@@ -9,4 +9,7 @@
 
 
 # Exclude external libs from GitHub language stats https://github.com/github/linguist/blob/v7.24.1/docs/overrides.md
-externals/*/**        linguist-vendored
+examples/**                                                       linguist-documentation
+examples/*/dokka                                                  linguist-vendored
+modules/dokkatoo-plugin-integration-tests/projects/**dokka/       linguist-vendored
+modules/dokkatoo-plugin-integration-tests/projects/**dokkatoo/    linguist-documentation

.gitignore

@@ -1,7 +1,69 @@
-# Ignore Gradle project-specific cache directory
+### Gradle ###
 .gradle
+build/
 
-# Ignore Gradle build output directory
-build
+!gradle/wrapper/gradle-wrapper.jar
+!gradle/wrapper/gradle-wrapper.properties
 
+
+### Kotlin/JVM ###
+*.class
+*.log
+
+hs_err_pid*
+replay_pid*
+*.hprof
+
+*.jar
+*.war
+*.nar
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+
+### IntelliJ ###
 .idea
+
+
+### Eclipse ###
+.metadata
+bin/
+tmp/
+*.tmp
+*.bak
+*.swp
+*~.nib
+.settings/
+.loadpath
+.recommenders
+.classpath
+
+.apt_generated/
+.apt_generated_test/
+.project
+
+
+### Linux ###
+*~
+.fuse_hidden*
+.Trash-*
+.nfs*
+
+
+### Windows ###
+[Dd]esktop.ini
+$RECYCLE.BIN/
+*.lnk
+
+
+### macOS ###
+.DS_Store
+._*
+
+# Icon must end with two \r
+Icon
+
+
+###########################

buildSrc/settings.gradle.kts

@@ -7,7 +7,7 @@ pluginManagement {
   }
 }
 
-@Suppress("UnstableApiUsage") // Central declaration of repositories is an incubating feature
+@Suppress("UnstableApiUsage")
 dependencyResolutionManagement {
 
   repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)

buildSrc/src/main/kotlin/buildsrc/conventions/base.gradle.kts

@@ -1,7 +1,5 @@
 package buildsrc.conventions
 
-import buildsrc.conventions.utils.asConsumer
-import buildsrc.conventions.utils.asProvider
 import java.time.Duration
 import org.gradle.api.tasks.testing.logging.TestLogEvent
 
@@ -45,20 +43,6 @@ tasks.withType<AbstractCopyTask>().configureEach {
   includeEmptyDirs = false
 }
 
-val kotlinDokkaSource by configurations.registering {
-  asConsumer()
-  attributes {
-    attribute(Usage.USAGE_ATTRIBUTE, objects.named("externals-dokka-src"))
-  }
-}
-
-val kotlinDokkaSourceElements by configurations.registering {
-  asProvider()
-  attributes {
-    attribute(Usage.USAGE_ATTRIBUTE, objects.named("externals-dokka-src"))
-  }
-}
-
 val updateTestReportCss by tasks.registering {
   description = "Hack so the Gradle test reports have dark mode"
   // the CSS is based on https://github.com/gradle/gradle/pull/12177
@@ -71,7 +55,7 @@ val updateTestReportCss by tasks.registering {
     include("reports/**/css/style.css")
   }
 
-  outputs.files(cssFiles)
+  outputs.files(cssFiles.files)
 
   doLast {
     cssFiles.forEach { cssFile ->

buildSrc/src/main/kotlin/buildsrc/conventions/dokka-source-downloader.gradle.kts

@@ -0,0 +1,54 @@
+package buildsrc.conventions
+
+import buildsrc.conventions.utils.asConsumer
+import buildsrc.conventions.utils.asProvider
+import buildsrc.conventions.utils.dropDirectories
+
+plugins {
+  id("buildsrc.conventions.base")
+}
+
+val kotlinDokkaSource by configurations.creating {
+  asConsumer()
+  attributes {
+    attribute(Usage.USAGE_ATTRIBUTE, objects.named("externals-dokka-src"))
+  }
+}
+
+val kotlinDokkaSourceElements by configurations.registering {
+  asProvider()
+  attributes {
+    attribute(Usage.USAGE_ATTRIBUTE, objects.named("externals-dokka-src"))
+  }
+}
+
+dependencies {
+  kotlinDokkaSource("kotlin:dokka:1.7.20@zip")
+}
+
+val prepareDokkaSource by tasks.registering(Sync::class) {
+  group = "dokka setup"
+  description = "Download & unpack Kotlin Dokka source code"
+  from(
+    kotlinDokkaSource.incoming
+      .artifactView { lenient(true) }
+      .artifacts
+      .resolvedArtifacts.map { artifacts ->
+        artifacts.map { zipTree(it.file) }
+      }
+  ) {
+    // drop the first dir (dokka-$version)
+    eachFile {
+      relativePath = relativePath.dropDirectories(1)
+    }
+  }
+  into(temporaryDir)
+  exclude(
+    "*.github",
+    "*.gradle",
+    "**/gradlew",
+    "**/gradlew.bat",
+    "**/gradle/wrapper/gradle-wrapper.jar",
+    "**/gradle/wrapper/gradle-wrapper.properties",
+  )
+}

buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects-base.gradle.kts

@@ -0,0 +1,29 @@
+package buildsrc.conventions
+
+import buildsrc.conventions.Maven_publish_test_gradle.MavenPublishTest
+import buildsrc.conventions.utils.asConsumer
+import buildsrc.conventions.utils.asProvider
+import buildsrc.tasks.SetupDokkaProjects
+
+plugins {
+  id("buildsrc.conventions.base")
+}
+
+
+val exampleProjectsAttribute = Attribute.of("example-projects", String::class.java)
+dependencies.attributesSchema {
+  attribute(exampleProjectsAttribute)
+}
+
+
+val exampleProjects by configurations.registering {
+  asConsumer()
+  isVisible = false
+  attributes { attribute(exampleProjectsAttribute, "dokka") }
+}
+
+val exampleProjectsElements by configurations.registering {
+  asProvider()
+  isVisible = true
+  attributes { attribute(exampleProjectsAttribute, "dokka") }
+}

buildSrc/src/main/kotlin/buildsrc/conventions/dokkatoo-example-projects.gradle.kts

@@ -0,0 +1,70 @@
+package buildsrc.conventions
+
+import buildsrc.conventions.Maven_publish_test_gradle.MavenPublishTest
+import buildsrc.tasks.SetupDokkaProjects
+
+plugins {
+  id("buildsrc.conventions.base")
+  id("buildsrc.conventions.dokka-source-downloader")
+  id("buildsrc.conventions.maven-publish-test")
+  id("buildsrc.conventions.dokkatoo-example-projects-base")
+}
+
+
+val prepareDokkaSourceTask = tasks.named<Sync>("prepareDokkaSource")
+
+val setupDokkaTemplateProjects by tasks.registering(SetupDokkaProjects::class) {
+  dependsOn(prepareDokkaSourceTask)
+  destinationToSources.convention(emptyMap())
+  dokkaSourceDir.set(
+    layout.dir(
+      prepareDokkaSourceTask.map { it.destinationDir }
+    )
+  )
+}
+
+val mavenPublishTestExtension = extensions.getByType<MavenPublishTest>()
+
+val updateGradlePropertiesInDokkatooExamples by tasks.registering {
+  group = "dokkatoo examples"
+
+  mustRunAfter(tasks.withType<SetupDokkaProjects>())
+
+  val gradlePropertiesFiles =
+    layout.projectDirectory.asFileTree
+      .matching {
+        include(
+          "**/*dokkatoo*/settings.gradle.kts",
+          "**/*dokkatoo*/settings.gradle",
+        )
+      }.elements.map { settingsFiles ->
+        settingsFiles.map {
+          it.asFile.resolveSibling("gradle.properties")
+        }
+      }
+
+  outputs.files(gradlePropertiesFiles)
+
+  val testMavenRepoPath = mavenPublishTestExtension.testMavenRepo.map {
+    it.asFile.invariantSeparatorsPath
+  }
+  inputs.property("testMavenRepoPath", testMavenRepoPath)
+
+  doLast task@{
+    gradlePropertiesFiles.get().forEach {
+      it.writeText(
+        """
+          |# DO NOT EDIT - Generated by ${this@task.path}
+          |
+          |testMavenRepo=${testMavenRepoPath.get()}
+          |
+        """.trimMargin()
+      )
+    }
+  }
+}
+
+tasks.assemble {
+  dependsOn(setupDokkaTemplateProjects)
+  dependsOn(updateGradlePropertiesInDokkatooExamples)
+}

buildSrc/src/main/kotlin/buildsrc/conventions/maven-publish-test.gradle.kts

@@ -1,5 +1,8 @@
 package buildsrc.conventions
 
+import buildsrc.conventions.utils.asConsumer
+import buildsrc.conventions.utils.asProvider
+
 
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
@@ -9,26 +12,28 @@ Utility for publishing a project to a local Maven directory for use in integrati
 
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-abstract class MavenPublishTest {
-  abstract val testMavenRepo: DirectoryProperty
-  internal abstract val testMavenRepoTemp: DirectoryProperty
+abstract class MavenPublishTest(
+  val testMavenRepo: Provider<Directory>
+) {
+  companion object {
+    val attribute = Attribute.of("maven-publish-test", String::class.java)
+  }
 }
 
-val mavenPublishTest = extensions.create<MavenPublishTest>("mavenPublishTest").apply {
-  testMavenRepo.convention(layout.buildDirectory.dir("test-maven-repo"))
-  testMavenRepoTemp.convention(layout.buildDirectory.dir("tmp/test-maven-repo"))
-}
+val Gradle.rootGradle: Gradle get() = generateSequence(gradle) { it.parent }.last()
+
+val mavenPublishTestExtension = extensions.create<MavenPublishTest>(
+  "mavenPublishTest",
+  gradle.rootGradle.rootProject.layout.buildDirectory.dir("test-maven-repo"),
+)
 
 
-val publishToTestMavenRepo by tasks.registering(Sync::class) {
+val publishToTestMavenRepo by tasks.registering {
   group = PublishingPlugin.PUBLISH_TASK_GROUP
   description = "Publishes all Maven publications to the test Maven repository."
-  from(mavenPublishTest.testMavenRepoTemp)
-  into(mavenPublishTest.testMavenRepo)
 }
 
 
-
 plugins.withType<MavenPublishPlugin>().all {
   extensions
     .getByType<PublishingExtension>()
@@ -46,15 +51,15 @@ plugins.withType<MavenPublishPlugin>().all {
         group = PublishingPlugin.PUBLISH_TASK_GROUP
         outputs.cacheIf { true }
         publication = this@publication
-        val destinationDir = mavenPublishTest.testMavenRepoTemp.asFile
-        inputs.property("testMavenRepoTempDir", destinationDir.map { it.invariantSeparatorsPath })
+        val destinationDir = mavenPublishTestExtension.testMavenRepo.get().asFile
+        inputs.property("testMavenRepoTempDir", destinationDir.invariantSeparatorsPath)
         doFirst {
           /**
-           * `maven.repo.local` will set the destination directry
+           * `maven.repo.local` will set the destination directory for this [PublishToMavenLocal] task.
            *
            * @see org.gradle.api.internal.artifacts.mvnsettings.DefaultLocalMavenRepositoryLocator.getLocalMavenRepository
            */
-          System.setProperty("maven.repo.local", destinationDir.get().absolutePath)
+          System.setProperty("maven.repo.local", destinationDir.absolutePath)
         }
       }
 
@@ -63,3 +68,32 @@ plugins.withType<MavenPublishPlugin>().all {
       }
     }
 }
+
+
+val testMavenPublication by configurations.registering {
+  asConsumer()
+  isVisible = false
+  attributes {
+    attribute(MavenPublishTest.attribute, "testMavenRepo")
+  }
+}
+
+val testMavenPublicationElements by configurations.registering {
+  asProvider()
+  isVisible = true
+  extendsFrom(testMavenPublication.get())
+  attributes {
+    attribute(MavenPublishTest.attribute, "testMavenRepo")
+  }
+  outgoing {
+    artifact(mavenPublishTestExtension.testMavenRepo) {
+      builtBy(publishToTestMavenRepo)
+    }
+  }
+}
+
+dependencies {
+  attributesSchema {
+    attribute(MavenPublishTest.attribute)
+  }
+}