Restructure the project to utilize included builds (#3174)

* Refactor and simplify artifact publishing
* Update Gradle to 8.4
* Refactor and simplify convention plugins and build scripts

Fixes #3132

---------

Co-authored-by: Adam <897017+aSemy@users.noreply.github.com>
Co-authored-by: Oleg Yukhnevich <whyoleg@gmail.com>

4 files changed, 186 insertions, 0 deletions

diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/expect/AbstractExpectTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/expect/AbstractExpectTest.kt
new file mode 100644
index 00000000..7f187127
--- /dev/null
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/expect/AbstractExpectTest.kt
@@ -0,0 +1,109 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package expect
+
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.Paths
+import java.util.concurrent.TimeUnit
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+abstract class AbstractExpectTest(
+    val testDir: Path? = Paths.get("src/test", "resources", "expect"),
+    val formats: List<String> = listOf("html")
+) : BaseAbstractTest() {
+
+    protected fun generateOutput(path: Path, outFormat: String): Path? {
+        val config = dokkaConfiguration {
+            format = outFormat
+            sourceSets {
+                sourceSet {
+                    sourceRoots = listOf(path.toAbsolutePath().asString())
+                }
+            }
+        }
+
+        var result: Path? = null
+        testFromData(config, cleanupOutput = false) {
+            renderingStage = { _, context -> result = context.configuration.outputDir.toPath() }
+        }
+        return result
+    }
+
+    protected fun compareOutput(expected: Path, obtained: Path?, gitTimeout: Long = 500) {
+        obtained?.let { path ->
+            val gitCompare = ProcessBuilder(
+                "git",
+                "--no-pager",
+                "diff",
+                expected.asString(),
+                path.asString()
+            ).also { logger.info("git diff command: ${it.command().joinToString(" ")}") }
+                .also { it.redirectErrorStream() }.start()
+
+            assertTrue(gitCompare.waitFor(gitTimeout, TimeUnit.MILLISECONDS), "Git timed out after $gitTimeout")
+            gitCompare.inputStream.bufferedReader().lines().forEach { logger.info(it) }
+            assertEquals(0, gitCompare.exitValue(), "${path.fileName}: outputs don't match")
+        } ?: throw AssertionError("obtained path is null")
+    }
+
+    protected fun compareOutputWithExcludes(
+        expected: Path,
+        obtained: Path?,
+        excludes: List<String>,
+        timeout: Long = 500
+    ) {
+        obtained?.let { _ ->
+            val (res, out, err) = runDiff(expected, obtained, excludes, timeout)
+            assertEquals(0, res, "Outputs differ:\nstdout - $out\n\nstderr - ${err ?: ""}")
+        } ?: throw AssertionError("obtained path is null")
+    }
+
+    protected fun runDiff(exp: Path, obt: Path, excludes: List<String>, timeout: Long): ProcessResult =
+        ProcessBuilder().command(
+            listOf("diff", "-ru") + excludes.flatMap { listOf("-x", it) } + listOf("--", exp.asString(), obt.asString())
+        ).also {
+            it.redirectErrorStream()
+        }.start().also { assertTrue(it.waitFor(timeout, TimeUnit.MILLISECONDS), "diff timed out") }.let {
+            ProcessResult(it.exitValue(), it.inputStream.bufferResult())
+        }
+
+
+    protected fun testOutput(p: Path, outFormat: String) {
+        val expectOut = p.resolve("out/$outFormat")
+        val testOut = generateOutput(p.resolve("src"), outFormat)
+            .also { logger.info("Test out: ${it?.asString()}") }
+
+        compareOutput(expectOut.toAbsolutePath(), testOut?.toAbsolutePath())
+        testOut?.deleteRecursively()
+    }
+
+    protected fun testOutputWithExcludes(
+        p: Path,
+        outFormat: String,
+        ignores: List<String> = emptyList(),
+        timeout: Long = 500
+    ) {
+        val expected = p.resolve("out/$outFormat")
+        generateOutput(p.resolve("src"), outFormat)
+            ?.let { obtained ->
+                compareOutputWithExcludes(expected, obtained, ignores, timeout)
+
+                obtained.deleteRecursively()
+            } ?: throw AssertionError("Output not generated for ${p.fileName}")
+    }
+
+    protected fun generateExpect(p: Path, outFormat: String) {
+        val out = p.resolve("out/$outFormat/")
+        Files.createDirectories(out)
+
+        val ret = generateOutput(p.resolve("src"), outFormat)
+        Files.list(out).forEach { it.deleteRecursively() }
+        ret?.let { Files.list(it).forEach { f -> f.copyRecursively(out.resolve(f.fileName)) } }
+    }
+
+}
diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/expect/ExpectGenerator.kt b/dokka-subprojects/plugin-base/src/test/kotlin/expect/ExpectGenerator.kt
new file mode 100644
index 00000000..0568ba74
--- /dev/null
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/expect/ExpectGenerator.kt
@@ -0,0 +1,17 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package expect
+
+import kotlin.test.Ignore
+import kotlin.test.Test
+
+class ExpectGenerator : AbstractExpectTest() {
+
+    @Ignore
+    @Test
+    fun generateAll() = testDir?.dirsWithFormats(formats).orEmpty().forEach { (p, f) ->
+        generateExpect(p, f)
+    }
+}
diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/expect/ExpectTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/expect/ExpectTest.kt
new file mode 100644
index 00000000..f1eb2a77
--- /dev/null
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/expect/ExpectTest.kt
@@ -0,0 +1,28 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package expect
+
+import org.junit.jupiter.api.DynamicTest.dynamicTest
+import org.junit.jupiter.api.TestFactory
+import kotlin.test.Ignore
+
+class ExpectTest : AbstractExpectTest() {
+    private val ignores: List<String> = listOf(
+        "images",
+        "scripts",
+        "images",
+        "styles",
+        "*.js",
+        "*.css",
+        "*.svg",
+        "*.map"
+    )
+    
+    @Ignore
+    @TestFactory
+    fun expectTest() = testDir?.dirsWithFormats(formats).orEmpty().map { (p, f) ->
+        dynamicTest("${p.fileName}-$f") { testOutputWithExcludes(p, f, ignores) }
+    }
+}
diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/expect/ExpectUtils.kt b/dokka-subprojects/plugin-base/src/test/kotlin/expect/ExpectUtils.kt
new file mode 100644
index 00000000..a8b1b187
--- /dev/null
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/expect/ExpectUtils.kt
@@ -0,0 +1,32 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package expect
+
+import java.io.InputStream
+import java.nio.file.Files
+import java.nio.file.Path
+import kotlin.streams.toList
+
+data class ProcessResult(val code: Int, val out: String, val err: String? = null)
+
+internal fun Path.dirsWithFormats(formats: List<String>): List<Pair<Path, String>> =
+    Files.list(this).toList().filter { Files.isDirectory(it) }.flatMap { p -> formats.map { p to it } }
+
+internal fun Path.asString() = normalize().toString()
+internal fun Path.deleteRecursively() = toFile().deleteRecursively()
+
+internal fun Path.copyRecursively(target: Path) = toFile().copyRecursively(target.toFile())
+
+internal fun Path.listRecursively(filter: (Path) -> Boolean): List<Path> = when {
+        Files.isDirectory(this) -> listOfNotNull(takeIf(filter)) + Files.list(this).toList().flatMap {
+            it.listRecursively(
+                filter
+            )
+        }
+        Files.isRegularFile(this) -> listOfNotNull(this.takeIf(filter))
+        else -> emptyList()
+    }
+
+internal fun InputStream.bufferResult(): String = this.bufferedReader().lines().toList().joinToString("\n")