From 8e5c63d035ef44a269b8c43430f43f5c8eebfb63 Mon Sep 17 00:00:00 2001
From: Ignat Beresnev <ignat.beresnev@jetbrains.com>
Date: Fri, 10 Nov 2023 11:46:54 +0100
Subject: 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>
---
 .../testApi/renderers/RenderingOnlyTestBase.kt     |  12 ++
 .../dokka/base/testApi/renderers/TestPage.kt       |  59 ++++++++++
 .../base/testApi/signatures/SignatureUtils.kt      |  23 ++++
 .../dokka/base/testApi/testRunner/baseTestApi.kt   | 124 +++++++++++++++++++++
 .../dokka/base/testApi/utils/JsoupUtils.kt         |  79 +++++++++++++
 .../dokka/base/testApi/utils/TestOutputWriter.kt   |  47 ++++++++
 .../utils/assertHtmlEqualsIgnoringWhitespace.kt    |  24 ++++
 7 files changed, 368 insertions(+)
 create mode 100644 dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/renderers/RenderingOnlyTestBase.kt
 create mode 100644 dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/renderers/TestPage.kt
 create mode 100644 dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/signatures/SignatureUtils.kt
 create mode 100644 dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/testRunner/baseTestApi.kt
 create mode 100644 dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/JsoupUtils.kt
 create mode 100644 dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/TestOutputWriter.kt
 create mode 100644 dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/assertHtmlEqualsIgnoringWhitespace.kt

(limited to 'dokka-subprojects/plugin-base-test-utils/src')

diff --git a/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/renderers/RenderingOnlyTestBase.kt b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/renderers/RenderingOnlyTestBase.kt
new file mode 100644
index 00000000..d2ff3ad4
--- /dev/null
+++ b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/renderers/RenderingOnlyTestBase.kt
@@ -0,0 +1,12 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package renderers
+
+import org.jetbrains.dokka.testApi.context.MockContext
+
+public abstract class RenderingOnlyTestBase<T> {
+    public abstract val context: MockContext
+    public abstract val renderedContent: T
+}
diff --git a/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/renderers/TestPage.kt b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/renderers/TestPage.kt
new file mode 100644
index 00000000..6fb484bf
--- /dev/null
+++ b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/renderers/TestPage.kt
@@ -0,0 +1,59 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package renderers
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.signatures.KotlinSignatureProvider
+import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter
+import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.doc.DocTag
+import org.jetbrains.dokka.model.properties.PropertyContainer
+import org.jetbrains.dokka.pages.*
+import org.jetbrains.dokka.utilities.DokkaConsoleLogger
+import org.jetbrains.dokka.utilities.LoggingLevel
+
+public fun testPage(callback: PageContentBuilder.DocumentableContentBuilder.() -> Unit): RawTestPage {
+    val content = PageContentBuilder(
+        EmptyCommentConverter,
+        KotlinSignatureProvider(EmptyCommentConverter, DokkaConsoleLogger(LoggingLevel.DEBUG)),
+        DokkaConsoleLogger(LoggingLevel.DEBUG)
+    ).contentFor(
+        DRI.topLevel,
+        emptySet(),
+        block = callback
+    )
+
+    return RawTestPage(content)
+}
+
+public class RawTestPage(
+    override val content: ContentNode,
+    override val name: String = "testPage",
+    override val dri: Set<DRI> = setOf(DRI.topLevel),
+    override val embeddedResources: List<String> = emptyList(),
+    override val children: List<PageNode> = emptyList(),
+): RootPageNode(), ContentPage {
+    override fun modified(
+        name: String,
+        content: ContentNode,
+        dri: Set<DRI>,
+        embeddedResources: List<String>,
+        children: List<PageNode>
+    ): ContentPage = this
+
+    override fun modified(name: String, children: List<PageNode>): RootPageNode = this
+
+}
+
+internal object EmptyCommentConverter : CommentsToContentConverter {
+    override fun buildContent(
+        docTag: DocTag,
+        dci: DCI,
+        sourceSets: Set<DokkaConfiguration.DokkaSourceSet>,
+        styles: Set<Style>,
+        extras: PropertyContainer<ContentNode>
+    ): List<ContentNode> = emptyList()
+}
diff --git a/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/signatures/SignatureUtils.kt b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/signatures/SignatureUtils.kt
new file mode 100644
index 00000000..ecbe809b
--- /dev/null
+++ b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/signatures/SignatureUtils.kt
@@ -0,0 +1,23 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package signatures
+
+import org.jsoup.Jsoup
+import org.jsoup.nodes.Element
+import org.jsoup.select.Elements
+import utils.Tag
+import utils.TestOutputWriter
+
+public fun TestOutputWriter.renderedContent(path: String = "root/example.html"): Element =
+    contents.getValue(path).let { Jsoup.parse(it) }.select("#content")
+        .single()
+
+public fun Element.signature(): Elements = select("div.symbol.monospace")
+public fun Element.tab(tabName: String): Elements = select("div[data-togglable=\"$tabName\"]")
+public fun Element.firstSignature(): Element = signature().first() ?: throw NoSuchElementException("No signature found")
+public fun Element.lastSignature(): Element = signature().last() ?: throw NoSuchElementException("No signature found")
+
+public class Parameters(vararg matchers: Any) : Tag("span", *matchers, expectedClasses = listOf("parameters"))
+public class Parameter(vararg matchers: Any) : Tag("span", *matchers, expectedClasses = listOf("parameter"))
diff --git a/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/testRunner/baseTestApi.kt b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/testRunner/baseTestApi.kt
new file mode 100644
index 00000000..3dc0e54b
--- /dev/null
+++ b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/testRunner/baseTestApi.kt
@@ -0,0 +1,124 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka.base.testApi.testRunner
+
+import org.jetbrains.dokka.CoreExtensions
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaGenerator
+import org.jetbrains.dokka.base.generation.SingleModuleGeneration
+import org.jetbrains.dokka.model.DModule
+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.CoreTestMethods
+import org.jetbrains.dokka.testApi.testRunner.DokkaTestGenerator
+import org.jetbrains.dokka.testApi.testRunner.TestBuilder
+import org.jetbrains.dokka.utilities.DokkaConsoleLogger
+import org.jetbrains.dokka.utilities.DokkaLogger
+import org.jetbrains.dokka.utilities.LoggingLevel
+
+public class BaseDokkaTestGenerator(
+    configuration: DokkaConfiguration,
+    logger: DokkaLogger,
+    testMethods: BaseTestMethods,
+    additionalPlugins: List<DokkaPlugin> = emptyList()
+) : DokkaTestGenerator<BaseTestMethods>(configuration, logger, testMethods, additionalPlugins) {
+
+    override fun generate() {
+        with(testMethods) {
+            val dokkaGenerator = DokkaGenerator(configuration, logger)
+
+            val context =
+                dokkaGenerator.initializePlugins(configuration, logger, additionalPlugins)
+            pluginsSetupStage(context)
+
+            val singleModuleGeneration = context.single(CoreExtensions.generation) as SingleModuleGeneration
+
+            val modulesFromPlatforms = singleModuleGeneration.createDocumentationModels()
+            documentablesCreationStage(modulesFromPlatforms)
+
+            verificationStage { singleModuleGeneration.validityCheck(context) }
+
+            val filteredModules = singleModuleGeneration.transformDocumentationModelBeforeMerge(modulesFromPlatforms)
+            documentablesFirstTransformationStep(filteredModules)
+
+            val documentationModel = singleModuleGeneration.mergeDocumentationModels(filteredModules)
+            documentablesMergingStage(documentationModel!!)
+
+            val transformedDocumentation = singleModuleGeneration.transformDocumentationModelAfterMerge(documentationModel)
+            documentablesTransformationStage(transformedDocumentation)
+
+            val pages = singleModuleGeneration.createPages(transformedDocumentation)
+            pagesGenerationStage(pages)
+
+            val transformedPages = singleModuleGeneration.transformPages(pages)
+            pagesTransformationStage(transformedPages)
+
+            singleModuleGeneration.render(transformedPages)
+            renderingStage(transformedPages, context)
+
+            singleModuleGeneration.runPostActions()
+
+            singleModuleGeneration.reportAfterRendering()
+        }
+    }
+}
+
+public data class BaseTestMethods(
+    override val pluginsSetupStage: (DokkaContext) -> Unit,
+    override val verificationStage: (() -> Unit) -> Unit,
+    override val documentablesCreationStage: (List<DModule>) -> Unit,
+    val documentablesFirstTransformationStep: (List<DModule>) -> Unit,
+    override val documentablesMergingStage: (DModule) -> Unit,
+    override val documentablesTransformationStage: (DModule) -> Unit,
+    override val pagesGenerationStage: (RootPageNode) -> Unit,
+    override val pagesTransformationStage: (RootPageNode) -> Unit,
+    override val renderingStage: (RootPageNode, DokkaContext) -> Unit
+) : CoreTestMethods(
+    pluginsSetupStage,
+    verificationStage,
+    documentablesCreationStage,
+    documentablesMergingStage,
+    documentablesTransformationStage,
+    pagesGenerationStage,
+    pagesTransformationStage,
+    renderingStage,
+)
+
+public class BaseTestBuilder : TestBuilder<BaseTestMethods>() {
+    public var pluginsSetupStage: (DokkaContext) -> Unit = {}
+    public var verificationStage: (() -> Unit) -> Unit = {}
+    public var documentablesCreationStage: (List<DModule>) -> Unit = {}
+    public var preMergeDocumentablesTransformationStage: (List<DModule>) -> Unit = {}
+    public var documentablesMergingStage: (DModule) -> Unit = {}
+    public var documentablesTransformationStage: (DModule) -> Unit = {}
+    public var pagesGenerationStage: (RootPageNode) -> Unit = {}
+    public var pagesTransformationStage: (RootPageNode) -> Unit = {}
+    public var renderingStage: (RootPageNode, DokkaContext) -> Unit = { _, _ -> }
+
+    override fun build(): BaseTestMethods {
+        return BaseTestMethods(
+            pluginsSetupStage,
+            verificationStage,
+            documentablesCreationStage,
+            preMergeDocumentablesTransformationStage,
+            documentablesMergingStage,
+            documentablesTransformationStage,
+            pagesGenerationStage,
+            pagesTransformationStage,
+            renderingStage
+        )
+    }
+}
+
+public abstract class BaseAbstractTest(
+    logger: TestLogger = TestLogger(DokkaConsoleLogger(LoggingLevel.DEBUG))
+) : AbstractTest<BaseTestMethods, BaseTestBuilder, BaseDokkaTestGenerator>(
+    ::BaseTestBuilder,
+    ::BaseDokkaTestGenerator,
+    logger,
+)
diff --git a/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/JsoupUtils.kt b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/JsoupUtils.kt
new file mode 100644
index 00000000..fcd73ff0
--- /dev/null
+++ b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/JsoupUtils.kt
@@ -0,0 +1,79 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package utils
+
+import org.jsoup.nodes.Element
+import org.jsoup.nodes.Node
+import org.jsoup.nodes.TextNode
+
+public fun Element.match(vararg matchers: Any, ignoreSpanWithTokenStyle:Boolean = false): Unit =
+    childNodes()
+        .let { list ->
+            if(ignoreSpanWithTokenStyle) {
+                list
+                    .filterNot { it is Element && it.tagName() == "span" && it.attr("class").startsWith("token ") &&  it.childNodeSize() == 0}
+                    .map { if(it is Element && it.tagName() == "span"
+                        && it.attr("class").startsWith("token ")
+                        && it.childNodeSize() == 1) it.childNode(0) else it }
+                    .uniteConsecutiveTextNodes()
+            } else list
+        }
+        .filter { (it !is TextNode || it.text().isNotBlank())}
+        .let { it.drop(it.size - matchers.size) }
+        .zip(matchers)
+        .forEach { (n, m) -> m.accepts(n, ignoreSpan = ignoreSpanWithTokenStyle) }
+
+public open class Tag(
+    public val name: String,
+    public vararg val matchers: Any,
+    public val expectedClasses: List<String> = emptyList()
+)
+public class Div(vararg matchers: Any) : Tag("div", *matchers)
+public class P(vararg matchers: Any) : Tag("p", *matchers)
+public class Span(vararg matchers: Any) : Tag("span", *matchers)
+public class A(vararg matchers: Any) : Tag("a", *matchers)
+public class B(vararg matchers: Any) : Tag("b", *matchers)
+public class I(vararg matchers: Any) : Tag("i", *matchers)
+public class STRIKE(vararg matchers: Any) : Tag("strike", *matchers)
+public class BlockQuote(vararg matchers: Any) : Tag("blockquote", *matchers)
+public class Dl(vararg matchers: Any) : Tag("dl", *matchers)
+public class Dt(vararg matchers: Any) : Tag("dt", *matchers)
+public class Dd(vararg matchers: Any) : Tag("dd", *matchers)
+public class Var(vararg matchers: Any) : Tag("var", *matchers)
+public class U(vararg matchers: Any) : Tag("u", *matchers)
+public object Wbr : Tag("wbr")
+public object Br : Tag("br")
+
+public fun Tag.withClasses(vararg classes: String): Tag = Tag(name, *matchers, expectedClasses = classes.toList())
+
+private fun Any.accepts(n: Node, ignoreSpan:Boolean = true) {
+    when (this) {
+        is String -> assert(n is TextNode && n.text().trim() == this.trim()) { "\"$this\" expected but found: $n" }
+        is Tag -> {
+            check(n is Element) { "Expected node to be Element: $n" }
+            assert(n.tagName() == name) { "Tag \"$name\" expected but found: \"$n\"" }
+            expectedClasses.forEach {
+                assert(n.hasClass(it)) { "Expected to find class \"$it\" for tag \"$name\", found: ${n.classNames()}" }
+            }
+            if (matchers.isNotEmpty()) n.match(*matchers, ignoreSpanWithTokenStyle = ignoreSpan)
+        }
+        else -> throw IllegalArgumentException("$this is not proper matcher")
+    }
+}
+
+private fun List<Node>.uniteConsecutiveTextNodes(): MutableList<Node> {
+    val resList = mutableListOf<Node>()
+    var acc = StringBuilder()
+    forEachIndexed { index, item ->
+        if (item is TextNode) {
+            acc.append(item.text())
+            if (!(index + 1 < size && this[index + 1] is TextNode)) {
+                resList.add(TextNode(acc.toString()))
+                acc = StringBuilder()
+            }
+        } else resList.add(item)
+    }
+    return resList
+ }
diff --git a/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/TestOutputWriter.kt b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/TestOutputWriter.kt
new file mode 100644
index 00000000..089a94ca
--- /dev/null
+++ b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/TestOutputWriter.kt
@@ -0,0 +1,47 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package utils
+
+import org.jetbrains.dokka.base.DokkaBase
+import org.jetbrains.dokka.base.renderers.OutputWriter
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.plugability.DokkaPluginApiPreview
+import org.jetbrains.dokka.plugability.Extension
+import org.jetbrains.dokka.plugability.PluginApiPreviewAcknowledgement
+import java.util.*
+
+public class TestOutputWriterPlugin(failOnOverwrite: Boolean = true) : DokkaPlugin() {
+    public val writer: TestOutputWriter = TestOutputWriter(failOnOverwrite)
+
+    private val dokkaBase by lazy { plugin<DokkaBase>() }
+
+    public val testWriter: Extension<OutputWriter, *, *> by extending {
+        (dokkaBase.outputWriter
+                with writer
+                override dokkaBase.fileWriter)
+    }
+
+    @OptIn(DokkaPluginApiPreview::class)
+    override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement =
+        PluginApiPreviewAcknowledgement
+}
+
+public class TestOutputWriter(
+    private val failOnOverwrite: Boolean = true
+) : OutputWriter {
+    public val contents: Map<String, String> get() = _contents
+    private val _contents = Collections.synchronizedMap(mutableMapOf<String, String>())
+
+    override suspend fun write(path: String, text: String, ext: String) {
+        val fullPath = "$path$ext"
+        _contents.putIfAbsent(fullPath, text)?.also {
+            if (failOnOverwrite) throw AssertionError("File $fullPath is being overwritten.")
+        }
+    }
+
+    override suspend fun writeResources(pathFrom: String, pathTo: String) {
+        write(pathTo, "*** content of $pathFrom ***", "")
+    }
+}
diff --git a/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/assertHtmlEqualsIgnoringWhitespace.kt b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/assertHtmlEqualsIgnoringWhitespace.kt
new file mode 100644
index 00000000..207ebb8a
--- /dev/null
+++ b/dokka-subprojects/plugin-base-test-utils/src/main/kotlin/org/jetbrains/dokka/base/testApi/utils/assertHtmlEqualsIgnoringWhitespace.kt
@@ -0,0 +1,24 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package utils
+
+import org.jsoup.Jsoup
+import org.jsoup.nodes.Document
+import kotlin.test.assertEquals
+
+/**
+ * Parses it using JSOUP, trims whitespace at the end of the line and asserts if they are equal
+ * parsing is required to unify the formatting
+ */
+public fun assertHtmlEqualsIgnoringWhitespace(expected: String, actual: String) {
+    val ignoreFormattingSettings = Document.OutputSettings().indentAmount(0).outline(true)
+    assertEquals(
+        Jsoup.parse(expected).outputSettings(ignoreFormattingSettings).outerHtml().trimSpacesAtTheEndOfLine(),
+        Jsoup.parse(actual).outputSettings(ignoreFormattingSettings).outerHtml().trimSpacesAtTheEndOfLine()
+    )
+}
+
+private fun String.trimSpacesAtTheEndOfLine(): String =
+    replace(" \n", "\n")
-- 
cgit