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>

67 files changed, 4875 insertions, 0 deletions

diff --git a/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/ConfigurationJsonUtils.kt b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/ConfigurationJsonUtils.kt
new file mode 100644
index 00000000..e693f4ef
--- /dev/null
+++ b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/ConfigurationJsonUtils.kt
@@ -0,0 +1,54 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka
+
+import org.jetbrains.dokka.plugability.ConfigurableBlock
+import org.jetbrains.dokka.utilities.parseJson
+import org.jetbrains.dokka.utilities.serializeAsCompactJson
+import org.jetbrains.dokka.utilities.serializeAsPrettyJson
+
+public fun DokkaConfigurationImpl(json: String): DokkaConfigurationImpl = parseJson(json)
+
+public fun GlobalDokkaConfiguration(json: String): GlobalDokkaConfiguration = parseJson(json)
+
+@Deprecated("Renamed to better distinguish between compact/pretty prints", ReplaceWith("this.toCompactJsonString()"))
+public fun DokkaConfiguration.toJsonString(): String = this.toCompactJsonString()
+
+@Deprecated("Renamed to better distinguish between compact/pretty prints", ReplaceWith("this.toCompactJsonString()"))
+public fun <T : ConfigurableBlock> T.toJsonString(): String = this.toCompactJsonString()
+
+/**
+ * Serializes [DokkaConfiguration] as a machine-readable and compact JSON string.
+ *
+ * The returned string is not very human friendly as it will be difficult to parse by eyes due to it
+ * being compact and in one line. If you want to show the output to a human being, see [toPrettyJsonString].
+ */
+public fun DokkaConfiguration.toCompactJsonString(): String = serializeAsCompactJson(this)
+
+/**
+ * Serializes [DokkaConfiguration] as a human-readable (pretty printed) JSON string.
+ *
+ * The returned string will have excessive line breaks and indents, which might not be
+ * desirable when passing this value between API consumers/producers. If you want
+ * a machine-readable and compact json string, see [toCompactJsonString].
+ */
+public fun DokkaConfiguration.toPrettyJsonString(): String = serializeAsPrettyJson(this)
+
+/**
+ * Serializes a [ConfigurableBlock] as a machine-readable and compact JSON string.
+ *
+ * The returned string is not very human friendly as it will be difficult to parse by eyes due to it
+ * being compact and in one line. If you want to show the output to a human being, see [toPrettyJsonString].
+ */
+public fun <T : ConfigurableBlock> T.toCompactJsonString(): String = serializeAsCompactJson(this)
+
+/**
+ * Serializes a [ConfigurableBlock] as a human-readable (pretty printed) JSON string.
+ *
+ * The returned string will have excessive line breaks and indents, which might not be
+ * desirable when passing this value between API consumers/producers. If you want
+ * a machine-readable and compact json string, see [toCompactJsonString].
+ */
+public fun <T : ConfigurableBlock> T.toPrettyJsonString(): String = serializeAsCompactJson(this)
diff --git a/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/CoreExtensions.kt b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/CoreExtensions.kt
new file mode 100644
index 00000000..ca2504e2
--- /dev/null
+++ b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/CoreExtensions.kt
@@ -0,0 +1,43 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka
+
+import org.jetbrains.dokka.generation.Generation
+import org.jetbrains.dokka.plugability.ExtensionPoint
+import org.jetbrains.dokka.renderers.PostAction
+import org.jetbrains.dokka.renderers.Renderer
+import org.jetbrains.dokka.transformers.documentation.DocumentableMerger
+import org.jetbrains.dokka.transformers.documentation.DocumentableToPageTranslator
+import org.jetbrains.dokka.transformers.documentation.DocumentableTransformer
+import org.jetbrains.dokka.transformers.pages.PageTransformer
+import org.jetbrains.dokka.transformers.sources.SourceToDocumentableTranslator
+import org.jetbrains.dokka.validity.PreGenerationChecker
+import kotlin.reflect.KProperty
+
+public object CoreExtensions {
+
+    public val preGenerationCheck: ExtensionPoint<PreGenerationChecker> by coreExtensionPoint<PreGenerationChecker>()
+
+    public val generation: ExtensionPoint<Generation> by coreExtensionPoint<Generation>()
+
+    public val sourceToDocumentableTranslator: ExtensionPoint<SourceToDocumentableTranslator> by coreExtensionPoint<SourceToDocumentableTranslator>()
+
+    public val documentableMerger: ExtensionPoint<DocumentableMerger> by coreExtensionPoint<DocumentableMerger>()
+
+    public val documentableTransformer: ExtensionPoint<DocumentableTransformer> by coreExtensionPoint<DocumentableTransformer>()
+
+    public val documentableToPageTranslator: ExtensionPoint<DocumentableToPageTranslator> by coreExtensionPoint<DocumentableToPageTranslator>()
+
+    public val pageTransformer: ExtensionPoint<PageTransformer> by coreExtensionPoint<PageTransformer>()
+
+    public val renderer: ExtensionPoint<Renderer> by coreExtensionPoint<Renderer>()
+
+    public val postActions: ExtensionPoint<PostAction> by coreExtensionPoint<PostAction>()
+
+    private fun <T : Any> coreExtensionPoint() = object {
+        operator fun provideDelegate(thisRef: CoreExtensions, property: KProperty<*>): Lazy<ExtensionPoint<T>> =
+            lazy { ExtensionPoint(thisRef::class.qualifiedName!!, property.name) }
+    }
+}
diff --git a/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaBootstrap.kt b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaBootstrap.kt
new file mode 100644
index 00000000..d3d82e39
--- /dev/null
+++ b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaBootstrap.kt
@@ -0,0 +1,15 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka
+
+import java.util.function.BiConsumer
+
+public interface DokkaBootstrap {
+    @Throws(Throwable::class)
+    public fun configure(serializedConfigurationJSON: String, logger: BiConsumer<String, String>)
+
+    @Throws(Throwable::class)
+    public fun generate()
+}
diff --git a/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaBootstrapImpl.kt b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaBootstrapImpl.kt
new file mode 100644
index 00000000..65f0ef72
--- /dev/null
+++ b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaBootstrapImpl.kt
@@ -0,0 +1,69 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka
+
+import org.jetbrains.dokka.utilities.DokkaLogger
+import java.util.concurrent.atomic.AtomicInteger
+
+import java.util.function.BiConsumer
+
+/**
+ * Accessed with reflection
+ */
+@Suppress("unused")
+public class DokkaBootstrapImpl : DokkaBootstrap {
+
+    public class DokkaProxyLogger(
+        public val consumer: BiConsumer<String, String>
+    ) : DokkaLogger {
+        private val warningsCounter = AtomicInteger()
+        private val errorsCounter = AtomicInteger()
+
+        override var warningsCount: Int
+            get() = warningsCounter.get()
+            set(value) = warningsCounter.set(value)
+
+        override var errorsCount: Int
+            get() = errorsCounter.get()
+            set(value) = errorsCounter.set(value)
+
+        override fun debug(message: String) {
+            consumer.accept("debug", message)
+        }
+
+        override fun info(message: String) {
+            consumer.accept("info", message)
+        }
+
+        override fun progress(message: String) {
+            consumer.accept("progress", message)
+        }
+
+        override fun warn(message: String) {
+            consumer.accept("warn", message).also { warningsCounter.incrementAndGet() }
+        }
+
+        override fun error(message: String) {
+            consumer.accept("error", message).also { errorsCounter.incrementAndGet() }
+        }
+    }
+
+    private lateinit var generator: DokkaGenerator
+
+    public fun configure(logger: DokkaLogger, configuration: DokkaConfigurationImpl) {
+        generator = DokkaGenerator(configuration, logger)
+    }
+
+    override fun configure(serializedConfigurationJSON: String, logger: BiConsumer<String, String>) {
+        configure(
+            DokkaProxyLogger(logger),
+            DokkaConfigurationImpl(serializedConfigurationJSON)
+        )
+    }
+
+    override fun generate() {
+        generator.generate()
+    }
+}
diff --git a/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaException.kt b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaException.kt
new file mode 100644
index 00000000..f16a2649
--- /dev/null
+++ b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaException.kt
@@ -0,0 +1,7 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka
+
+public open class DokkaException(message: String) : RuntimeException(message)
diff --git a/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaGenerator.kt b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaGenerator.kt
new file mode 100644
index 00000000..9ae3adb4
--- /dev/null
+++ b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaGenerator.kt
@@ -0,0 +1,89 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+@file:Suppress("SameParameterValue")
+
+package org.jetbrains.dokka
+
+import kotlinx.coroutines.DelicateCoroutinesApi
+import kotlinx.coroutines.Dispatchers
+import org.jetbrains.dokka.generation.GracefulGenerationExit
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.plugability.DokkaPlugin
+import org.jetbrains.dokka.utilities.DokkaLogger
+
+/**
+ * DokkaGenerator is the main entry point for generating documentation
+ *
+ * [generate] method has been split into submethods for test reasons
+ */
+public class DokkaGenerator(
+    private val configuration: DokkaConfiguration,
+    private val logger: DokkaLogger
+) {
+
+    public fun generate() {
+        timed(logger) {
+            report("Initializing plugins")
+            val context = initializePlugins(configuration, logger)
+
+            runCatching {
+                context.single(CoreExtensions.generation).run {
+                    logger.progress("Dokka is performing: $generationName")
+                    generate()
+                }
+            }.exceptionOrNull()?.let { e ->
+                finalizeCoroutines()
+                throw e
+            }
+
+            finalizeCoroutines()
+        }.dump("\n\n === TIME MEASUREMENT ===\n")
+    }
+
+    public fun initializePlugins(
+        configuration: DokkaConfiguration,
+        logger: DokkaLogger,
+        additionalPlugins: List<DokkaPlugin> = emptyList()
+    ): DokkaContext = DokkaContext.create(configuration, logger, additionalPlugins)
+
+    @OptIn(DelicateCoroutinesApi::class)
+    private fun finalizeCoroutines() {
+        if (configuration.finalizeCoroutines) {
+            Dispatchers.shutdown()
+        }
+    }
+}
+
+public class Timer internal constructor(startTime: Long, private val logger: DokkaLogger?) {
+    private val steps = mutableListOf("" to startTime)
+
+    public fun report(name: String) {
+        logger?.progress(name)
+        steps += (name to System.currentTimeMillis())
+    }
+
+    public fun dump(prefix: String = "") {
+        logger?.info(prefix)
+        val namePad = steps.map { it.first.length }.maxOrNull() ?: 0
+        val timePad = steps.windowed(2).map { (p1, p2) -> p2.second - p1.second }.maxOrNull()?.toString()?.length ?: 0
+        steps.windowed(2).forEach { (p1, p2) ->
+            if (p1.first.isNotBlank()) {
+                logger?.info("${p1.first.padStart(namePad)}: ${(p2.second - p1.second).toString().padStart(timePad)}")
+            }
+        }
+    }
+}
+
+private fun timed(logger: DokkaLogger? = null, block: Timer.() -> Unit): Timer =
+    Timer(System.currentTimeMillis(), logger).apply {
+        try {
+            block()
+        } catch (exit: GracefulGenerationExit) {
+            report("Exiting Generation: ${exit.reason}")
+        } finally {
+            report("")
+        }
+    }
+
diff --git a/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaVersion.kt b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaVersion.kt
new file mode 100644
index 00000000..d846988b
--- /dev/null
+++ b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/DokkaVersion.kt
@@ -0,0 +1,15 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package org.jetbrains.dokka
+
+import java.util.*
+
+public object DokkaVersion {
+    public val version: String by lazy {
+        javaClass.getResourceAsStream("/META-INF/dokka/dokka-version.properties").use { stream ->
+            Properties().apply { load(stream) }.getProperty("dokka-version")
+        }
+    }
+}
diff --git a/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/InternalDokkaApi.kt b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/InternalDokkaApi.kt
new file mode 100644
index 00000000..65c0427c
--- /dev/null
+++ b/dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/InternalDokkaApi.kt</