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>

5 files changed, 374 insertions, 0 deletions

diff --git a/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/MultiModuleDokkaTestGenerator.kt b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/MultiModuleDokkaTestGenerator.kt
new file mode 100644
index 00000000..f3548e4c
--- /dev/null
+++ b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/MultiModuleDokkaTestGenerator.kt
@@ -0,0 +1,98 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.allModulesPage
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaGenerator
+import org.jetbrains.dokka.pages.RootPageNode
+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 MultiModuleDokkaTestGenerator(
+    configuration: DokkaConfiguration,
+    logger: DokkaLogger,
+    testMethods: MultiModuleTestMethods,
+    additionalPlugins: List<DokkaPlugin> = emptyList()
+) : DokkaTestGenerator<MultiModuleTestMethods>(
+    configuration,
+    logger,
+    testMethods,
+    additionalPlugins + AllModulesPagePlugin()
+) {
+    override fun generate() = with(testMethods) {
+        val dokkaGenerator = DokkaGenerator(configuration, logger)
+
+        val context =
+            dokkaGenerator.initializePlugins(configuration, logger, additionalPlugins + AllModulesPagePlugin())
+        pluginsSetupStage(context)
+
+        val generation = context.single(CoreExtensions.generation) as AllModulesPageGeneration
+
+        val generationContext = generation.processSubmodules()
+        submoduleProcessingStage(context)
+
+        val allModulesPage = generation.createAllModulesPage(generationContext)
+        allModulesPageCreationStage(allModulesPage)
+
+        val transformedPages = generation.transformAllModulesPage(allModulesPage)
+        pagesTransformationStage(transformedPages)
+
+        generation.render(transformedPages)
+        renderingStage(transformedPages, context)
+
+        generation.processMultiModule(transformedPages)
+        processMultiModule(transformedPages)
+
+        generation.finishProcessingSubmodules()
+        finishProcessingSubmodules(context)
+    }
+
+}
+
+open class MultiModuleTestMethods(
+    open val pluginsSetupStage: (DokkaContext) -> Unit,
+    open val allModulesPageCreationStage: (RootPageNode) -> Unit,
+    open val pagesTransformationStage: (RootPageNode) -> Unit,
+    open val renderingStage: (RootPageNode, DokkaContext) -> Unit,
+    open val submoduleProcessingStage: (DokkaContext) -> Unit,
+    open val processMultiModule: (RootPageNode) -> Unit,
+    open val finishProcessingSubmodules: (DokkaContext) -> Unit,
+) : TestMethods
+
+class MultiModuleTestBuilder : TestBuilder<MultiModuleTestMethods>() {
+    var pluginsSetupStage: (DokkaContext) -> Unit = {}
+    var allModulesPageCreationStage: (RootPageNode) -> Unit = {}
+    var pagesTransformationStage: (RootPageNode) -> Unit = {}
+    var renderingStage: (RootPageNode, DokkaContext) -> Unit = { _, _ -> }
+    var submoduleProcessingStage: (DokkaContext) -> Unit = {}
+    var processMultiModule: (RootPageNode) -> Unit = {}
+    var finishProcessingSubmodules: (DokkaContext) -> Unit = {}
+
+    override fun build() = MultiModuleTestMethods(
+        pluginsSetupStage,
+        allModulesPageCreationStage,
+        pagesTransformationStage,
+        renderingStage,
+        submoduleProcessingStage,
+        processMultiModule,
+        finishProcessingSubmodules
+    )
+}
+
+abstract class MultiModuleAbstractTest(logger: TestLogger = TestLogger(DokkaConsoleLogger(LoggingLevel.DEBUG))) :
+    AbstractTest<MultiModuleTestMethods, MultiModuleTestBuilder, MultiModuleDokkaTestGenerator>(
+        ::MultiModuleTestBuilder,
+        ::MultiModuleDokkaTestGenerator,
+        logger,
+    )
diff --git a/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/MultiModuleDocumentationTest.kt b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/MultiModuleDocumentationTest.kt
new file mode 100644
index 00000000..3d9636ef
--- /dev/null
+++ b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/MultiModuleDocumentationTest.kt
@@ -0,0 +1,75 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.allModulesPage.templates
+
+import matchers.content.*
+import org.jetbrains.dokka.allModulesPage.MultiModuleAbstractTest
+import org.jetbrains.dokka.model.dfs
+import org.jetbrains.dokka.pages.ContentKind
+import org.jetbrains.dokka.pages.ContentResolvedLink
+import org.jetbrains.dokka.pages.MultimoduleRootPageNode
+import org.junit.jupiter.api.io.TempDir
+import java.io.File
+import kotlin.test.AfterTest
+import kotlin.test.BeforeTest
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+class MultiModuleDocumentationTest : MultiModuleAbstractTest() {
+
+    @field:TempDir
+    lateinit var tempDir: File
+
+    val documentationContent = """
+        # Sample project
+        Sample documentation with [external link](https://www.google.pl)
+    """.trimIndent()
+
+    @BeforeTest
+    fun setup() {
+        tempDir.resolve("README.md").writeText(documentationContent)
+    }
+
+    @AfterTest
+    fun teardown(){
+        tempDir.resolve("README.md").delete()
+    }
+
+    @Test
+    fun `documentation should be included in all modules page`() {
+        val configuration = dokkaConfiguration {
+            includes = listOf(tempDir.resolve("README.md"))
+        }
+
+        testFromData(configuration) {
+            allModulesPageCreationStage = { rootPage ->
+                (rootPage as? MultimoduleRootPageNode)?.content?.dfs { it.dci.kind == ContentKind.Cover }?.children?.firstOrNull()
+                    ?.assertNode {
+                        group {
+                            group {
+                                group {
+                                    header(1) {
+                                        +"Sample project"
+                                    }
+                                    group {
+                                        +"Sample documentation with "
+                                        link {
+                                            +"external link"
+                                            check {
+                                                assertEquals(
+                                                    "https://www.google.pl",
+                                                    (this as ContentResolvedLink).address
+                                                )
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+            }
+        }
+    }
+}
diff --git a/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkCommandResolutionTest.kt b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkCommandResolutionTest.kt
new file mode 100644
index 00000000..32b06a5b
--- /dev/null
+++ b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkCommandResolutionTest.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 org.jetbrains.dokka.allModulesPage.templates
+
+import kotlinx.html.a
+import kotlinx.html.span
+import kotlinx.html.stream.createHTML
+import org.jetbrains.dokka.DokkaModuleDescriptionImpl
+import org.jetbrains.dokka.allModulesPage.MultiModuleAbstractTest
+import org.jetbrains.dokka.base.renderers.html.templateCommand
+import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat
+import org.jetbrains.dokka.base.templating.ResolveLinkCommand
+import org.jetbrains.dokka.links.DRI
+import org.junit.jupiter.api.io.TempDir
+import utils.assertHtmlEqualsIgnoringWhitespace
+import java.io.File
+import kotlin.test.Test
+import kotlin.test.assertTrue
+
+class ResolveLinkCommandResolutionTest : MultiModuleAbstractTest() {
+
+    @Test
+    fun `should resolve link to another module`(@TempDir outputDirectory: File) {
+        val testedDri = DRI(
+            packageName = "package2",
+            classNames = "Sample",
+        )
+        val link = createHTML().templateCommand(ResolveLinkCommand(testedDri)) {
+            span {
+                +"Sample"
+            }
+        }
+
+        val expected = createHTML().a {
+            href = "../module2/package2/-sample/index.html"
+            span {
+                +"Sample"
+            }
+        }
+
+        val contentFile = setup(outputDirectory, link)
+        val configuration = createConfiguration(outputDirectory)
+
+        testFromData(configuration, useOutputLocationFromConfig = true) {
+            finishProcessingSubmodules = {
+                assertHtmlEqualsIgnoringWhitespace(expected, contentFile.readText())
+            }
+        }
+    }
+
+    @Test
+    fun `should produce content when link is not resolvable`(@TempDir outputDirectory: File) {
+        val testedDri = DRI(
+            packageName = "not-resolvable-package",
+            classNames = "Sample",
+        )
+        val link = createHTML().templateCommand(ResolveLinkCommand(testedDri)) {
+            span {
+                +"Sample"
+            }
+        }
+
+        val expected = createHTML().span {
+            attributes["data-unresolved-link"] = testedDri.toString()
+            span {
+                +"Sample"
+            }
+        }
+
+        val contentFile = setup(outputDirectory, link)
+        val configuration = createConfiguration(outputDirectory)
+
+        testFromData(configuration, useOutputLocationFromConfig = true) {
+            finishProcessingSubmodules = {
+                assertHtmlEqualsIgnoringWhitespace(expected, contentFile.readText())
+            }
+        }
+    }
+
+    private fun setup(outputDirectory: File, content: String): File {
+        val innerModule1 = outputDirectory.resolve("module1").also { assertTrue(it.mkdirs()) }
+        val innerModule2 = outputDirectory.resolve("module2").also { assertTrue(it.mkdirs()) }
+        val packageList = innerModule2.resolve("package-list")
+        packageList.writeText(mockedPackageListForPackages(RecognizedLinkFormat.DokkaHtml, "package2"))
+        val contentFile = innerModule1.resolve("index.html")
+        contentFile.writeText(content)
+        return contentFile
+    }
+
+    private fun createConfiguration(outputDirectory: File) = 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
+    }
+}
diff --git a/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkGfmCommandResolutionTest.kt b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkGfmCommandResolutionTest.kt
new file mode 100644
index 00000000..b17d6765
--- /dev/null
+++ b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/ResolveLinkGfmCommandResolutionTest.kt
@@ -0,0 +1,76 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.allModulesPage.templates
+
+import org.jetbrains.dokka.DokkaModuleDescriptionImpl
+import org.jetbrains.dokka.allModulesPage.MultiModuleAbstractTest
+import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat
+import org.jetbrains.dokka.gfm.GfmCommand.Companion.templateCommand
+import org.jetbrains.dokka.gfm.GfmPlugin
+import org.jetbrains.dokka.gfm.ResolveLinkGfmCommand
+import org.jetbrains.dokka.gfm.templateProcessing.GfmTemplateProcessingPlugin
+import org.jetbrains.dokka.links.DRI
+import org.junit.jupiter.api.io.TempDir
+import java.io.File
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class ResolveLinkGfmCommandResolutionTest : MultiModuleAbstractTest() {
+
+    @Test
+    fun `should resolve link to another module`(@TempDir outputDirectory: File) {
+        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"),
+                )
+            )
+            outputDir = outputDirectory
+        }
+
+        val innerModule1 = outputDirectory.resolve("module1").also { assertTrue(it.mkdirs()) }
+        val innerModule2 = outputDirectory.resolve("module2").also { assertTrue(it.mkdirs()) }
+
+        val indexMd = innerModule1.resolve("index.md")
+        val packageList = innerModule2.resolve("package-list")
+
+        val indexMdContent = StringBuilder().apply {
+            templateCommand(
+                ResolveLinkGfmCommand(
+                    dri = DRI(
+                        packageName = "package2",
+                        classNames = "Sample",
+                    )
+                )
+            ) {
+                append("Sample text inside")
+            }
+        }.toString()
+
+        indexMd.writeText(indexMdContent)
+        packageList.writeText(mockedPackageListForPackages(RecognizedLinkFormat.DokkaGFM, "package2"))
+
+        testFromData(
+            configuration,
+            pluginOverrides = listOf(GfmTemplateProcessingPlugin(), GfmPlugin()),
+            useOutputLocationFromConfig = true
+        ) {
+            finishProcessingSubmodules = {
+                val expectedIndexMd = "[Sample text inside](../module2/package2/-sample/index.md)"
+                assertEquals(expectedIndexMd, indexMd.readText().trim())
+            }
+        }
+    }
+}
diff --git a/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/mockedPackageListFactory.kt b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/mockedPackageListFactory.kt
new file mode 100644
index 00000000..e4ee4eaa
--- /dev/null
+++ b/dokka-subprojects/plugin-all-modules-page/src/test/kotlin/org/jetbrains/dokka/allModulesPage/templates/mockedPackageListFactory.kt
@@ -0,0 +1,16 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.allModulesPage.templates
+
+import org.jetbrains.dokka.base.resolvers.shared.PackageList
+import org.jetbrains.dokka.base.resolvers.shared.RecognizedLinkFormat
+
+internal fun mockedPackageListForPackages(format: RecognizedLinkFormat, vararg packages: String): String =
+    """
+       ${PackageList.DOKKA_PARAM_PREFIX}.format:${format.formatName}
+       ${PackageList.DOKKA_PARAM_PREFIX}.linkExtension:${format.linkExtension}
+       
+       ${packages.sorted().joinToString(separator = "\n", postfix = "\n") { it }}
+    """.trimIndent()