Tool to generate "Configuration Reference" Table for applications

[wansors]

Description

In large projects there are lots of configuration properties, and is not easy to keep up to date the documentation.
It could be nice to have a tool or maven plugin to autogenerate a "Configuration Reference" Table like the ones on the website (https://quarkus.io/guides/all-config). Adding the property, documentation from the javadoc and default values.

Thanks

Implementation ideas

No response

[famod]

Do you mean some kind of filtered config based on the extensions you are using?

[wansors]

Do you mean some kind of filtered config based on the extensions you are using?

Not of the extensions activated, only for the new config properties added by the user in their project. It has no sense for small applications, but if your application or service has many configuration parameters is a nice way to have docslikecode.

[faermanj]

This would be extremely useful in our projects.

[radcortez]

This is possible by adding the quarkus-extension-processor as a dependency tp the project:

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-extension-processor</artifactId>
  <version>QUARKUS_VERSION</version>
</dependency>

Note that the processor dependency is not managed by the BOM, so it requires to set the version.

The @ConfigMapping interfaces, also require an additional annotation for the processor to discover them, used to define the config phase (unique to Quarkus), but no real impact in the application code:

@ConfigRoot(phase = ConfigPhase.RUN_TIME)
@ConfigMapping(prefix = "my.config")
public interface MyConfig {
}

In this way, the build will start to generate ascidoc in the build tool output folder. Also, it will fail the build if a mapping method is missing the javadoc.

[michalsomora]

Hi
would it be possible to generate documentation for config with internal classes as a flat structure?
So for instance this config mapping generate ascidoc only on 1st level, e.g. my.config.internal but not for my.config.internal.field1
To do so, i need to extract InternalConfig to separate class with its own prefix.
`

@ConfigRoot(phase = ConfigPhase.RUN_TIME)
@ConfigMapping(prefix = "my.config")
public interface MyConfig {
    /**
     * internal doc
     * @return
     */
    @WithName("internal")
    InternalConfig internal();
    interface InternalConfig {
        /**
         * field1 doc
         * @return
         */
        @WithName("field1")
        String field1();
    }
}

`

It would be convenient to have all the configs under one class
Thanks for any advice.

[radcortez]

Which Quarkus version are you using? I believe we had a bug in that case, but it was fixed some time ago. I've tried your example, and I've got the expected result:

[michalsomora]

Hi @radcortez
thanks for the quick reply, i am using 2.16.2.Final, probablly its not fixed there

[radcortez]

Yes, I think it is only fixed in 3. something. You may want to try to annotate the nested group with @ConfigGroup. It may help for that version (but I'm not sure).

[gsmet]

I added that it would be nice to have a plugin specific for doc generation separate from the extension plugin for applications in the issue here: #35439 .

[Athou]

I added that it would be nice to have a plugin specific for doc generation separate from the extension plugin for applications in the issue here: #35439 .

Hi @gsmet,

It looks like #35439 has been completed in Quarkus 3.14. Does that mean there is now a way to generate application configuration documentation?

Thanks!

[gsmet]

This is actually an issue we should probably reopen. The extension annotation processor was never designed to handle applications but it apparently worked by accident and I broke it by making assumptions about it being run in an extension (which doesn't look so far fetched given it's the extension annotation processor :)).

I really think we should have a different annotation processor though, that could share some of the code (we need to make really sure it won't make the extension annotation processor harder to maintain though).

[gsmet]

@Athou were you actually using it before or are you trying to use it now?

[Athou]

@Athou were you actually using it before or are you trying to use it now?

I migrated CommaFeed from Dropwizard to Quarkus last month and I added documentation generation 11 days ago. The output is a little janky (icons are not showing up) but it works and it's way easier than to maintain the documentation manually. It's really helpful for CommaFeed users.

[gsmet]

Ah cool, then I have a project to experiment with. I'll see if I can unblock you.

Where do you consume this output? Because I don't think we use anything special for the icons, you might need font awesome around though.

[gsmet]

@Athou I thought given your message in the PR that it wasn't working for you anymore but it's actually working, right?

[gsmet]

Also I'm wondering if it would help if there was an option to generate Markdown?

[Athou]

@Athou I thought given your message in the PR that it wasn't working for you anymore but it's actually working, right?

Yes, it works with Quarkus 3.14. In addition to the quarkus-extension-processor I had to add

<plugin>
	<groupId>io.quarkus</groupId>
	<artifactId>quarkus-config-doc-maven-plugin</artifactId>
	<version>${quarkus.version}</version>
	<extensions>true</extensions>
	<executions>
		<execution>
			<id>default-generate-asciidoc</id>
			<phase>process-test-resources</phase>
			<goals>
				<goal>generate-asciidoc</goal>
			</goals>
		</execution>
	</executions>
</plugin>

because the processor no longer generates asciidoc. I had to add an execution on another phase because the default phase executes before the processor is invoked.

The only issue I currently have is the one I mentioned in #42561 (comment), I'm no longer able to run my unit tests in IntelliJ but the maven build works fine.

Where do you consume this output? Because I don't think we use anything special for the icons, you might need font awesome around though.

I currently don't. I just version the output of quarkus-config-doc-maven-plugin and I wrote a unit test that verifies that the asciidoc is up to date. Then I just use the asciidoc renderer of Github because it's output is good enough. I should probably transform the asciidoc source to html and publish the result to Github pages though.

Also I'm wondering if it would help if there was an option to generate Markdown?

That would be awesome, yes :)

[gsmet]

Also I'm wondering if it would help if there was an option to generate Markdown?

That would be awesome, yes :)

Would you be interested in collaborating on that?

Basically, we would just need to have a Markdown version of these templates:
https://github.com/quarkusio/quarkus/tree/main/devtools/config-doc-maven-plugin/src/main/resources/templates

And a Markdown version of this class:
https://github.com/quarkusio/quarkus/blob/main/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/AsciidocFormatter.java
(probably with a common parent class)

And then refactor the Mojo to have a parent class and have a second mojo for Markdown.

Even if you just help with translating the templates to Markdown, that would help a lot.

Maybe I could prepare the infrastructure and you could play with the templates to make them work properly?

[gsmet]

As for your issue with Intellij, #42853 should take care of it!

[radcortez]

Also, as a workaround, you may be able to point the processor to the working version (while leaving Quarkus with the new version).

[Athou]

Also I'm wondering if it would help if there was an option to generate Markdown?

That would be awesome, yes :)

Would you be interested in collaborating on that?

Basically, we would just need to have a Markdown version of these templates: https://github.com/quarkusio/quarkus/tree/main/devtools/config-doc-maven-plugin/src/main/resources/templates

And a Markdown version of this class: https://github.com/quarkusio/quarkus/blob/main/devtools/config-doc-maven-plugin/src/main/java/io/quarkus/maven/config/doc/AsciidocFormatter.java (probably with a common parent class)

And then refactor the Mojo to have a parent class and have a second mojo for Markdown.

Even if you just help with translating the templates to Markdown, that would help a lot.

Sure, I can take a crack at it.

Maybe I could prepare the infrastructure and you could play with the templates to make them work properly?

That'd be very helpful, thanks!

As for your issue with Intellij, #42853 should take care of it!

Thank you!

[gsmet]

OK, I'll prepare the necessary infrastructure. In the meantime, you can play with the Qute templates as it will be needed in any case and we can assemble all of this once everything is ready.

[gsmet]

@Athou see #42907 for a good start on this. Ping me in the PR if you need help iterating to get the Markdown templates working.