Dump DokkaConfiguration as JSON when running with the debug logging level

[IgnatBeresnev]

When Dokka is run with the debug logging level via Gradle/Maven/CLI runners, it should dump a pretty-printed JSON string of the used DokkaConfiguration.

This would be very helpful when debugging various user problems as a lot of the times bugs occur due to invalid configuration.

This would also help with comparing configurations across projects/versions and allow us to manually check the compatibility on configuration level.

[aSemy]

Could this be done at a runner level? I have a couple of suggestions for dumping the config file in the Gradle plugin.

1. make fun buildDokkaConfiguration() public, but guarded with @InternalDokkaApi

   @InternalDokkaApi
   abstract fun buildDokkaConfiguration(): DokkaConfigurationImpl

   This would allow users to add some custom config to dump the file:

   tasks.withType<AbstractDokkaTask>().configureEach {
       val configJsonFile = temporaryDir.resolve("dokka-config.json")
       outputs.file(configJsonFile).withPropertyName("configJsonFile")
       
       doLast {
           @OptIn(InternalDokkaApi::class)
           val dokkaConfig = buildDokkaConfiguration()
           configJsonFile.parentFile.mkdirs()
           configJsonFile.createNewFile()
           configJsonFile.writeText(dokkaConfig.toJsonString())
           logger.lifecycle("$path Dokka Config JSON: ${configJsonFile.toURI()}")
       }
   }

2. Formalise the above with a custom property in AbstractDokkaTask

   /**
    * For debugging purposes, the [DokkaConfiguration] JSON used to run [DokkaGenerator] can be
    * dumped to a file.
    *
    * To disable this behaviour, set the value of this property to `null`.
    */
   @get:Optional
   @get:OutputDirectory
   @InternalDokkaApi
   abstract val dokkaConfigurationJson: RegularFileProperty

   and then create a new function that will dump the JSON to file, if the property has a value

   @TaskAction
   internal open fun generateDocumentation() {
       val dokkaConfig = buildDokkaConfiguration()
   
       outputDokkaConfigJson(dokkaConfig)
   
       DokkaBootstrap(runtime, DokkaBootstrapImpl::class).apply {
           configure(dokkaConfig.toCompactJsonString(), createProxyLogger())
           // ...
       }
   }
   
   private fun outputDokkaConfigJson(
       dokkaConfig: DokkaConfiguration
   ) {
       @OptIn(InternalDokkaApi::class)
       val jsonFile = dokkaConfigurationJson.asFile.orNull ?: return
   
       val prettyJson = dokkaConfig.toPrettyJsonString()
   
       jsonFile.parentFile.mkdirs()
       jsonFile.createNewFile()
       jsonFile.writeText(prettyJson)
   
       logger.info("Dokka Configuration JSON for task $path: ${jsonFile.toURI()}")
   }

[IgnatBeresnev]

@aSemy something like that could indeed be implemented as an intermediate solution 👍 The simplest way I can think of is #3008, please have a look if it's enough for now, I'll be able to cherry-pick it into 1.8.20

Opening up buildDokkaConfiguration() sounds a bit scary, someone will definitely abuse it for changing the configuration by extending DokkaTask or something... And adding an additional configuration property, I think, would look more like a "permanent" solution from the user's perspective (i.e they'll add it alongside a bunch of other options, and forget to delete). An extension function from an .internal package would have to be used separately (like in your examples) and shouldn't expose anything new to the user, so it looks good to me

I'd still like a better way to be added when we have time, so that there's no need to add custom tasks or build logic as not everyone is proficient with Gradle. Ideally, it should be as simple as "add this one line/env property, run Dokka and attach all files from that directory" - would help with diffs, too (everyone will "the same" files as opposed to slightly differently configured tasks).