Add debug utility for manually overriding the Dokka configuration JSON (

#3915)

* Add debug utility for manually overriding the Dokka configuration JSON

Being able to make minor manual modifications to the Dokka configuration is exceptionally useful for local debugging.

dokka-runners/dokka-gradle-plugin/src/main/kotlin/tasks/DokkaGenerateTask.kt

@@ -15,11 +15,12 @@ import org.gradle.kotlin.dsl.newInstance
 import org.gradle.kotlin.dsl.submit
 import org.gradle.workers.WorkerExecutor
 import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.DokkaConfigurationImpl
 import org.jetbrains.dokka.gradle.DokkaBasePlugin.Companion.jsonMapper
 import org.jetbrains.dokka.gradle.engine.parameters.DokkaGeneratorParametersSpec
 import org.jetbrains.dokka.gradle.engine.parameters.builders.DokkaParametersBuilder
-import org.jetbrains.dokka.gradle.internal.InternalDokkaGradlePluginApi
 import org.jetbrains.dokka.gradle.internal.DokkaPluginParametersContainer
+import org.jetbrains.dokka.gradle.internal.InternalDokkaGradlePluginApi
 import org.jetbrains.dokka.gradle.workers.ClassLoaderIsolation
 import org.jetbrains.dokka.gradle.workers.DokkaGeneratorWorker
 import org.jetbrains.dokka.gradle.workers.ProcessIsolation
@@ -103,6 +104,17 @@ constructor(
     @get:Internal
     abstract val dokkaConfigurationJsonFile: RegularFileProperty
 
+    /**
+     * Completely override the default Dokka configuration with JSON encoded
+     * Dokka Configuration.
+     *
+     * This should only be used for local debugging.
+     */
+    @get:Input
+    @get:Optional
+    @InternalDokkaGradlePluginApi
+    abstract val overrideJsonConfig: Property<String>
+
     @InternalDokkaGradlePluginApi
     enum class GeneratorMode {
         Module,
@@ -114,7 +126,13 @@ constructor(
         generationType: GeneratorMode,
         outputDirectory: File,
     ) {
-        val dokkaConfiguration = createDokkaConfiguration(generationType, outputDirectory)
+        val dokkaConfiguration =
+            if (overrideJsonConfig.isPresent) {
+                logger.warn("w: [$path] Overriding DokkaConfiguration with overrideJsonConfig")
+                DokkaConfigurationImpl(overrideJsonConfig.get())
+            } else {
+                createDokkaConfiguration(generationType, outputDirectory)
+            }
 
         logger.info("dokkaConfiguration: $dokkaConfiguration")
         verifyDokkaConfiguration(dokkaConfiguration)

dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/OverrideJsonConfigTest.kt

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package org.jetbrains.dokka.gradle
+
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.paths.shouldExist
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.string.shouldContain
+import org.intellij.lang.annotations.Language
+import org.jetbrains.dokka.gradle.internal.DokkaConstants.DOKKA_VERSION
+import org.jetbrains.dokka.gradle.utils.*
+import kotlin.io.path.readText
+
+/**
+ * Test [org.jetbrains.dokka.gradle.tasks.DokkaGenerateTask.overrideJsonConfig].
+ */
+class OverrideJsonConfigTest : FunSpec({
+
+    context("Json Config Override:") {
+        val project = createProject()
+
+        test("override works") {
+
+            project.runner
+                .addArguments(
+                    ":dokkaGenerateModuleHtml",
+                    "--rerun",
+                )
+                .build {
+                    output shouldContain "w: [:dokkaGenerateModuleHtml] Overriding DokkaConfiguration with manualJsonConfig"
+
+                    val actualDokkaConfigJson =
+                        project.file("build/tmp/dokkaGenerateModuleHtml/dokka-configuration.json")
+
+                    actualDokkaConfigJson.shouldExist()
+                    actualDokkaConfigJson.readText() shouldBe dokkaConfOverrideJson
+                }
+        }
+    }
+})
+
+private fun createProject(): GradleProjectTest = gradleKtsProjectTest("OverrideJsonConfigTest") {
+
+    buildGradleKts = """
+        |plugins {
+        |    kotlin("jvm") version embeddedKotlinVersion
+        |    id("org.jetbrains.dokka") version "$DOKKA_VERSION"
+        |}
+        |
+        |tasks.dokkaGenerateModuleHtml {
+        |    overrideJsonConfig.set(
+        |        providers.fileContents(layout.projectDirectory.file("dokka-config.json")).asText
+        |    )
+        |}
+        |
+        """.trimMargin()
+
+    createKotlinFile("src/main/kotlin/Foo.kt", "class Foo")
+
+    createFile("dokka-config.json", dokkaConfOverrideJson)
+}
+
+@Language("json")
+private val dokkaConfOverrideJson = """
+    |{
+    |  "moduleName": "Overridden",
+    |  "moduleVersion": null,
+    |  "outputDir": "blah-blah-override-output",
+    |  "cacheRoot": null,
+    |  "offlineMode": false,
+    |  "sourceSets": [
+    |  ],
+    |  "pluginsClasspath": [
+    |  ],
+    |  "pluginsConfiguration": [
+    |  ],
+    |  "modules": [
+    |  ],
+    |  "failOnWarning": false,
+    |  "delayTemplateSubstitution": false,
+    |  "suppressObviousFunctions": true,
+    |  "includes": [
+    |  ],
+    |  "suppressInheritedMembers": false,
+    |  "finalizeCoroutines": false
+    |}
+    """.trimMargin()