Silence logging when running dokkaHtml

[vlsi]

Describe the bug

dokkaHtml produces the following messages with the default logging levels (e.g. lifecycle)

> Task :...:dokkaJavadoc
Initializing plugins
Dokka is performing: documentation for allure-base-plugin
Validity check
Creating documentation models
Transforming documentation model before merging
Merging documentation models
Transforming documentation model after merging
Creating pages
Transforming pages
Rendering

Expected behaviour

The debugging messages should come with debug level or something.
Frankly speaking, it is hard to understand what should the end-users do with the above messages.

Dokka configuration

plugins {
    id("org.jetbrains.dokka") version "1.4.32"
}

tasks.withType<DokkaTask>().configureEach {
    outputDirectory.set(buildDir.resolve("javadoc/$name"))
}

Installation

• Operating system: macOS
• Build tool: Gradle v6.8.3
• Dokka version: 1.4.32

[TWiStErRob]

Is there a workaround for this?

[TWiStErRob]

I tried to find a workaround, but there's no hook. Here are my findings:

• org.jetbrains.dokka.gradle.AbstractDokkaTask#generateDocumentation creates a BiConsumer (proxy logger)
• The BiConsumer is wrapped in a DokkaProxyLogger at DokkaBootstrapImpl.configure.
• This is used for logging the messages on "progress" level.

The problem: all of these are created during task execution, no injection point exists, because they're all just new'd up. Accessing DokkaBootstrapImpl.generator would help to reflectively replace logger, but there's no way to inject code between configure and generate calls.

There is a hack where if we call org.gradle.internal.logging.slf4j.OutputEventListenerBackedLoggerContext#addNoOpLogger reflectively before a logger is created, we can silence a logger altogether, sadly using Task.logger means the logger name is org.gradle.api.Task, which we don't really want to blanket silence.

Theoretically (by design?) it should be possible to replace DokkaBootstrap by making sure there's another DokkaBootstrapImpl.class exists on the runtime configuration of AbstractDokkaTask, but this involves either runtime generating a jar, or pre-compiling that class with a few lines of code.

[TWiStErRob]

To add to OP, these log messages might be meaningful when you debug something, but other than that they're just noise. Imagine if javac, kotlinc, jar all listed the internal steps they are going through, like parsing AST, generating code, writing class files, creating ZIP root entry, etc. that's what Dokka is doing at the moment. This is especially annoying when you are not even building Dokka directly, just want to publish JARs.

Repros on dokkaJavadoc, Gradle 8, Dokka 1.7.20, Windows 10.

[TWiStErRob]

@IgnatBeresnev if removing is not an option, using Task.logger.info() might be a good compromise. Or add a Gradle property to gradle.properties to silence them (with default=true). Do you have any thoughts on which way would be preferable?

[eirnym]

Gradle plugin actually using logger to facilitate the output. For progress points lifecycle level has been used for the progress output, probably based on Gradle documentation. However, a bit below in the Gradle documentation table with when logging levels are visible on screen is shown, which suggests, that lifecycle is basically for Gradle or highly important messages.

Documentation on logging levels: https://docs.gradle.org/current/userguide/logging.html#logLevels

dokka/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/tasks/AbstractDokkaTask.kt

Lines 219 to 227 in 6fcd66a

	private fun createProxyLogger(): BiConsumer<String, String> = BiConsumer { level, message ->
	when (level) {
	"debug" -> logger.debug(message)
	"info" -> logger.info(message)
	"progress" -> logger.lifecycle(message)
	"warn" -> logger.warn(message)
	"error" -> logger.error(message)
	}
	}

[eirnym]

@IgnatBeresnev Coudl you please to look on the PR?

[eirnym]

FYI, info level is used for Maven plugin

[IgnatBeresnev]

@IgnatBeresnev if removing is not an option, using Task.logger.info() might be a good compromise. Or add a Gradle property to gradle.properties to silence them (with default=true). Do you have any thoughts on which way would be preferable?

As I mentioned in #2915, I'm afraid it's not as simple :( A proper solution would require going over all of the messages emitted by Dokka, and then deciding which ones need to be re-written and which ones need a different logging level, as there's also a problem of level priority. In Dokka, info > progress. In Gradle, info < lifecycle. So the existing messages like info("Generation completed successfully") don't actually get logged by the Gradle runner, but they are logged in other runners, which is not consistent.

While this change could be contributed by an external party, we'd need to agree both internally and externally beforehand on what types of messages we want to see in the final output and what should be done with the level inconsistency (and it causes even more work if we break compatibility). I don't mind it, but it can take a significant amount of time to achieve the desired result because our plate is somewhat full at the moment.

I do want to revisit this issue by the stable release though, I'd say it's important.

FYI, info level is used for Maven plugin

There's no other choice - Maven doesn't have a separate level for progress messages, but it does have a trace level that doesn't exist in Dokka. So maybe Dokka's mapping needs to be shifted by one (debug -> trace, info -> debug, progress -> info), but it also needs to be discussed and will most likely need to be addressed when this issue is being researched

[TWiStErRob]

it looks like the proposed solution would silence Dokka overall, no messages will be emitted other than warnings and errors, so for the users it'll look like Dokka is broken all of a sudden.

This is the Gradle way. If you have a proper idiomatic Gradle build, the only output you get is BUILD SUCCESSFUL. Any output is a red flag that identifies a problem. (Unless of course the users asks for more with --info or --console=verbose, etc.

Here are some examples of output that require taking action and therefore is part of the output:

> Configure project :android
Unable to initialize metrics, ensure C:\Users\TWiStEr\.android is writable, details: C:\Users\TWiStEr\.android\analytics.settings (Access is denied)
WARNING:The option setting 'android.r8.failOnMissingClasses=true' is experimental. The current default is 'false'.
WARNING:The option setting 'android.experimental.androidTest.useUnifiedTestPlatform=false' is deprecated. The current default is 'true'.
It will be removed in version 8.0 of the Android Gradle plugin.

> Configure project :libs
The Dependency Analysis plugin is only known to work with versions of AGP between 4.2.2 and 7.4.1. You are using 7.4.2. Proceed at your own risk.

> Configure project :libs:about
Unable to initialize metrics, ensure C:\Users\TWiStEr\.android is writable, details: C:\Users\TWiStEr\.android\analytics.settings (Access is denied)

A proper solution would require going over all of the messages emitted by Dokka, and then deciding which ones need to be re-written and which ones need a different logging level

This sounds like scope creep to me, some users just want to silence dokka, could we at least have #2915 behind a flag while this full revising of logging is happening?

---

I would like to make a note here that these progress messages printed by Dokka are actually what Gradle outputs in the smart output only. Here are some examples:




these disappear after they're done. So they show you what's up, but then they're just done with no problems, so no output.

[IgnatBeresnev]

This is the Gradle way.

It might be, but Dokka is not a Gradle plugin by itself, it's an engine. And the annoying messages are not coming from the Gradle plugin, they're coming from the engine and the (default) plugins.

We have other runners which also have users (CLI, Maven), and we have external contributors and plugin writers who can use the common DokkaLogger to output their own messages (it's part of the public API) - we have to think about them, too:

• Maven runner users not only see the same messages, by default (INFO) they actually see significantly more debug-like messages
• The CLI runner's default logging level was set to DEBUG until recently, so the users saw even more messages.
• There's no documentation for DokkaLogger - when should each level be used, what's the contract? This is probably the reason you're seeing the annoying messages in the first place - someone needed to log something from the engine or a plugin, not thinking about Gradle, and they didn't know which level to use, so they used whatever they thought was more suitable.

Re-routing Dokka#progress to Gradle#info might resolve the annoyance for you personally short-term, but it will raise questions and won't do much better for us long-term, and will have us do double or triple work down the road.

---

could we at least have #2915 behind a flag while this full revising of logging is happening?

We'd have to support this flag, which is (at the moment) unnecessary maintenance burden. Not having any way to relay a message visible to the user with default settings, other than with warn and error, is not ideal to say the least.

If we can register a Gradle logger with a certain name/package/etc that could be configured by the user separately (like log4j.logger.org.jetbrains.dokka=warn) - it'd be a good intermediate solution. This way, the user would be responsible for silencing logging. If there's no way to do that in Gradle, perhaps it's Gradle's shortcoming.

---

There are many annoying things with Dokka, we can't fix them all at once. I understand the annoyance here, but I don't understand why it's annoying you that much that it can't wait for a proper solution that would address it once and for all :)