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>

6 files changed, 469 insertions, 0 deletions

diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandResolutionTest.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandResolutionTest.kt
new file mode 100644
index 00000000..8492fba1
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToNavigationCommandResolutionTest.kt
@@ -0,0 +1,143 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.templates
+
+import kotlinx.html.a
+import kotlinx.html.div
+import kotlinx.html.id
+import kotlinx.html.span
+import kotlinx.html.stream.createHTML
+import org.jetbrains.dokka.DokkaModuleDescriptionImpl
+import org.jetbrains.dokka.base.renderers.html.templateCommand
+import org.jetbrains.dokka.base.templating.AddToNavigationCommand
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.junit.jupiter.api.io.TempDir
+import org.junit.jupiter.params.ParameterizedTest
+import org.junit.jupiter.params.provider.ValueSource
+import utils.assertHtmlEqualsIgnoringWhitespace
+import java.io.File
+import kotlin.test.Test
+
+class AddToNavigationCommandResolutionTest : TemplatingAbstractTest() {
+
+    @Test
+    fun `should substitute AddToNavigationCommand in root directory`(@TempDir outputDirectory: File) {
+        addToNavigationTest(outputDirectory) {
+            val output = outputDirectory.resolve("navigation.html").readText()
+            val expected = expectedOutput(
+                ModuleWithPrefix("module1"),
+                ModuleWithPrefix("module2")
+            )
+            assertHtmlEqualsIgnoringWhitespace(expected, output)
+        }
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = ["module1", "module2"])
+    fun `should substitute AddToNavigationCommand in modules directory`(
+        moduleName: String,
+        @TempDir outputDirectory: File
+    ) {
+        addToNavigationTest(outputDirectory) {
+            val output = outputDirectory.resolve(moduleName).resolve("navigation.html").readText()
+            val expected = expectedOutput(
+                ModuleWithPrefix("module1", ".."),
+                ModuleWithPrefix("module2", "..")
+            )
+            assertHtmlEqualsIgnoringWhitespace(expected, output)
+        }
+    }
+
+    private fun expectedOutput(vararg modulesWithPrefix: ModuleWithPrefix) = createHTML(prettyPrint = true)
+        .div("sideMenu") {
+            modulesWithPrefix.forEach { (moduleName, prefix) ->
+                val relativePrefix = prefix?.let { "$it/" } ?: ""
+                div("sideMenuPart") {
+                    id = "$moduleName-nav-submenu"
+                    div("overview") {
+                        a {
+                            href = "$relativePrefix$moduleName/module-page.html"
+                            span {
+                                +"module-$moduleName"
+                            }
+                        }
+                    }
+                    div("sideMenuPart") {
+                        id = "$moduleName-nav-submenu-0"
+                        div("overview") {
+                            a {
+                                href = "$relativePrefix$moduleName/$moduleName/package-page.html"
+                                span {
+                                    +"package-$moduleName"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+    private fun inputForModule(moduleName: String) = createHTML()
+        .templateCommand(AddToNavigationCommand(moduleName)) {
+            div("sideMenuPart") {
+                id = "$moduleName-nav-submenu"
+                div("overview") {
+                    a {
+                        href = "module-page.html"
+                        span {
+                            +"module-$moduleName"
+                        }
+                    }
+                }
+                div("sideMenuPart") {
+                    id = "$moduleName-nav-submenu-0"
+                    div("overview") {
+                        a {
+                            href = "$moduleName/package-page.html"
+                            span {
+                                +"package-$moduleName"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+    private fun addToNavigationTest(outputDirectory: File, test: (DokkaContext) -> Unit) {
+        val module1 = outputDirectory.resolve("module1").also { it.mkdirs() }
+        val module2 = outputDirectory.resolve("module2").also { it.mkdirs() }
+
+        val configuration = dokkaConfiguration {
+            modules = listOf(
+                DokkaModuleDescriptionImpl(
+                    name = "module1",
+                    relativePathToOutputDirectory = module1,
+                    includes = emptySet(),
+                    sourceOutputDirectory = module1,
+                ),
+                DokkaModuleDescriptionImpl(
+                    name = "module2",
+                    relativePathToOutputDirectory = module2,
+                    includes = emptySet(),
+                    sourceOutputDirectory = module2,
+                ),
+            )
+            this.outputDir = outputDirectory
+        }
+
+        val module1Navigation = module1.resolve("navigation.html")
+        module1Navigation.writeText(inputForModule("module1"))
+        val module2Navigation = module2.resolve("navigation.html")
+        module2Navigation.writeText(inputForModule("module2"))
+
+        testFromData(configuration, useOutputLocationFromConfig = true) {
+            finishProcessingSubmodules = { ctx ->
+                test(ctx)
+            }
+        }
+    }
+
+    private data class ModuleWithPrefix(val moduleName: String, val prefix: String? = null)
+}
diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToSearchCommandResolutionTest.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToSearchCommandResolutionTest.kt
new file mode 100644
index 00000000..ae8ab941
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/AddToSearchCommandResolutionTest.kt
@@ -0,0 +1,82 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.DokkaModuleDescriptionImpl
+import org.jetbrains.dokka.base.renderers.html.SearchRecord
+import org.jetbrains.dokka.base.templating.AddToSearch
+import org.jetbrains.dokka.base.templating.parseJson
+import org.jetbrains.dokka.base.templating.toJsonString
+import org.junit.jupiter.api.io.TempDir
+import org.junit.jupiter.params.ParameterizedTest
+import org.junit.jupiter.params.provider.ValueSource
+import java.io.File
+import kotlin.test.assertEquals
+
+class AddToSearchCommandResolutionTest : TemplatingAbstractTest() {
+
+    @ParameterizedTest
+    @ValueSource(strings = ["pages.json"])
+    fun `should merge navigation templates`(fileName: String, @TempDir outputDirectory: File) {
+        setupTestDirectoriesWithContent(outputDirectory, fileName)
+
+        val configuration = dokkaConfiguration {
+            modules = listOf(
+                DokkaModuleDescriptionImpl(
+                    name = "module1",
+                    relativePathToOutputDirectory = outputDirectory.resolve("module1"),
+                    includes = emptySet(),
+                    sourceOutputDirectory = outputDirectory.resolve("module1"),
+                ),
+                DokkaModuleDescriptionImpl(
+                    name = "module2",
+                    relativePathToOutputDirectory = outputDirectory.resolve("module2"),
+                    includes = emptySet(),
+                    sourceOutputDirectory = outputDirectory.resolve("module2"),
+                ),
+            )
+            this.outputDir = outputDirectory
+        }
+
+        testFromData(configuration, useOutputLocationFromConfig = true) {
+            finishProcessingSubmodules = { _ ->
+                val expected = elements.map { it.copy(location = "module1/${it.location}") } +
+                        elements.map { it.copy(location = "module2/${it.location}") }
+
+                val output =
+                    parseJson<List<SearchRecord>>(outputDirectory.resolve("scripts/${fileName}").readText())
+                assertEquals(expected, output.sortedBy { it.location })
+            }
+        }
+    }
+
+    private fun setupTestDirectoriesWithContent(outputDirectory: File, fileName: String): List<File> {
+        val scriptsForModule1 = outputDirectory.resolve("module1/scripts").also { it.mkdirs() }
+        val scriptsForModule2 = outputDirectory.resolve("module2/scripts").also { it.mkdirs() }
+        outputDirectory.resolve("scripts").also { it.mkdirs() }
+
+        val module1Navigation = scriptsForModule1.resolve(fileName)
+        module1Navigation.writeText(toJsonString(fromModule1))
+        val module2Navigation = scriptsForModule2.resolve(fileName)
+        module2Navigation.writeText(toJsonString(fromModule2))
+
+        return listOf(module1Navigation, module2Navigation)
+    }
+
+    companion object {
+        val elements = listOf(
+            SearchRecord(name = "name1", location = "location1"),
+            SearchRecord(name = "name2", location = "location2")
+        )
+        val fromModule1 = AddToSearch(
+            moduleName = "module1",
+            elements = elements
+        )
+        val fromModule2 = AddToSearch(
+            moduleName = "module2",
+            elements = elements
+        )
+    }
+}
diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandResolutionTest.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandResolutionTest.kt
new file mode 100644
index 00000000..b619afbb
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/SubstitutionCommandResolutionTest.kt
@@ -0,0 +1,110 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.templates
+
+import kotlinx.html.a
+import kotlinx.html.div
+import kotlinx.html.id
+import kotlinx.html.span
+import kotlinx.html.stream.createHTML
+import org.jetbrains.dokka.DokkaModuleDescriptionImpl
+import org.jetbrains.dokka.base.renderers.html.templateCommand
+import org.jetbrains.dokka.base.renderers.html.templateCommandAsHtmlComment
+import org.jetbrains.dokka.base.templating.PathToRootSubstitutionCommand
+import org.junit.jupiter.api.io.TempDir
+import utils.assertHtmlEqualsIgnoringWhitespace
+import java.io.File
+import kotlin.test.Test
+
+class SubstitutionCommandResolutionTest : TemplatingAbstractTest() {
+
+    @Test
+    fun `should handle PathToRootCommand`(@TempDir outputDirectory: File) {
+        val template = createHTML()
+            .templateCommand(PathToRootSubstitutionCommand(pattern = "###", default = "default")) {
+                a {
+                    href = "###index.html"
+                    div {
+                        id = "logo"
+                    }
+                }
+            }
+
+        val expected = createHTML().a {
+            href = "../index.html"
+            div {
+                id = "logo"
+            }
+        }
+        checkSubstitutedResult(outputDirectory, template, expected)
+    }
+
+    @Test
+    fun `should handle PathToRootCommand as HTML comment`(@TempDir outputDirectory: File) {
+        val template = createHTML().span {
+            templateCommandAsHtmlComment(PathToRootSubstitutionCommand(pattern = "###", default = "default")) {
+                this@span.a {
+                    href = "###index.html"
+                    div {
+                        id = "logo"
+                    }
+                }
+                templateCommandAsHtmlComment(PathToRootSubstitutionCommand(pattern = "####", default = "default")) {
+                    this@span.a {
+                        href = "####index.html"
+                        div {
+                            id = "logo"
+                        }
+                    }
+                }
+            }
+        }
+
+        val expected = createHTML().span {
+            a {
+                href = "../index.html"
+                div {
+                    id = "logo"
+                }
+            }
+            a {
+                href = "../index.html"
+                div {
+                    id = "logo"
+                }
+            }
+        }
+        checkSubstitutedResult(outputDirectory, template, expected)
+    }
+
+    private fun checkSubstitutedResult(outputDirectory: File, template: String, expected:String) {
+        val testedFile = createDirectoriesAndWriteContent(outputDirectory, template)
+
+        val configuration = dokkaConfiguration {
+            modules = listOf(
+                DokkaModuleDescriptionImpl(
+                    name = "module1",
+                    relativePathToOutputDirectory = outputDirectory.resolve("module1"),
+                    includes = emptySet(),
+                    sourceOutputDirectory = outputDirectory.resolve("module1"),
+                )
+            )
+            this.outputDir = outputDirectory
+        }
+
+        testFromData(configuration, useOutputLocationFromConfig = true){
+            finishProcessingSubmodules = {
+                assertHtmlEqualsIgnoringWhitespace(expected, testedFile.readText())
+            }
+        }
+    }
+
+    private fun createDirectoriesAndWriteContent(outputDirectory: File, content: String): File {
+        val module1 = outputDirectory.resolve("module1").also { it.mkdirs() }
+        val module1Content = module1.resolve("index.html")
+        module1Content.writeText(content)
+        return module1Content
+    }
+}
diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TemplatingDokkaTestGenerator.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TemplatingDokkaTestGenerator.kt
new file mode 100644
index 00000000..53f0d279
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TemplatingDokkaTestGenerator.kt
@@ -0,0 +1,74 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaGenerator
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.testApi.logger.TestLogger
+import org.jetbrains.dokka.testApi.testRunner.AbstractTest
+import org.jetbrains.dokka.testApi.testRunner.DokkaTestGenerator
+import org.jetbrains.dokka.testApi.testRunner.TestBuilder
+import org.jetbrains.dokka.testApi.testRunner.TestMethods
+import org.jetbrains.dokka.utilities.DokkaConsoleLogger
+import org.jetbrains.dokka.utilities.DokkaLogger
+import org.jetbrains.dokka.utilities.LoggingLevel
+
+class TemplatingDokkaTestGenerator(
+    configuration: DokkaConfiguration,
+    logger: DokkaLogger,
+    testMethods: TemplatingTestMethods,
+    additionalPlugins: List<DokkaPlugin> = emptyList()
+) : DokkaTestGenerator<TemplatingTestMethods>(
+    configuration,
+    logger,
+    testMethods,
+    additionalPlugins + TemplatingPlugin() + TestTemplatingPlugin()
+) {
+    override fun generate() = with(testMethods) {
+        val dokkaGenerator = DokkaGenerator(configuration, logger)
+
+        val context =
+            dokkaGenerator.initializePlugins(configuration, logger, additionalPlugins)
+
+        pluginsSetupStage(context)
+
+        val generation = context.single(CoreExtensions.generation) as TestTemplatingGeneration
+
+        generation.processSubmodules()
+        submoduleProcessingStage(context)
+
+        generation.finishProcessing()
+        finishProcessingSubmodules(context)
+    }
+
+}
+
+open class TemplatingTestMethods(
+    open val pluginsSetupStage: (DokkaContext) -> Unit,
+    open val submoduleProcessingStage: (DokkaContext) -> Unit,
+    open val finishProcessingSubmodules: (DokkaContext) -> Unit,
+) : TestMethods
+
+class TemplatingTestBuilder : TestBuilder<TemplatingTestMethods>() {
+    var pluginsSetupStage: (DokkaContext) -> Unit = {}
+    var submoduleProcessingStage: (DokkaContext) -> Unit = {}
+    var finishProcessingSubmodules: (DokkaContext) -> Unit = {}
+
+    override fun build() = TemplatingTestMethods(
+        pluginsSetupStage,
+        submoduleProcessingStage,
+        finishProcessingSubmodules,
+    )
+}
+
+abstract class TemplatingAbstractTest(logger: TestLogger = TestLogger(DokkaConsoleLogger(LoggingLevel.DEBUG))) :
+    AbstractTest<TemplatingTestMethods, TemplatingTestBuilder, TemplatingDokkaTestGenerator>(
+        ::TemplatingTestBuilder,
+        ::TemplatingDokkaTestGenerator,
+        logger,
+    )
diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingGeneration.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingGeneration.kt
new file mode 100644
index 00000000..0180b2ab
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingGeneration.kt
@@ -0,0 +1,34 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.Timer
+import org.jetbrains.dokka.generation.Generation
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.plugin
+import org.jetbrains.dokka.plugability.query
+import org.jetbrains.dokka.plugability.querySingle
+
+class TestTemplatingGeneration(private val context: DokkaContext) : Generation {
+
+    val templatingPlugin by lazy { context.plugin<TemplatingPlugin>() }
+
+    override fun Timer.generate() {
+        report("Processing submodules")
+        processSubmodules()
+
+        report("Finishing processing")
+        finishProcessing()
+    }
+
+    fun processSubmodules() =
+        templatingPlugin.querySingle { submoduleTemplateProcessor }.process(context.configuration.modules)
+
+    fun finishProcessing() =
+        templatingPlugin.query { templateProcessingStrategy }.forEach { it.finish(context.configuration.outputDir) }
+
+
+    override val generationName = "test template generation"
+}
diff --git a/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingPlugin.kt b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingPlugin.kt
new file mode 100644
index 00000000..f1d5d919
--- /dev/null
+++ b/dokka-subprojects/plugin-templating/src/test/kotlin/org/jetbrains/dokka/templates/TestTemplatingPlugin.kt
@@ -0,0 +1,26 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.templates
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
+
+class TestTemplatingPlugin: DokkaPlugin() {
+
+    val dokkaBase by lazy { plugin<DokkaBase>() }
+
+    val allModulesPageGeneration by extending {
+        (CoreExtensions.generation
+                providing ::TestTemplatingGeneration
+                override dokkaBase.singleGeneration)
+    }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
+}