Introduce @ConfigDocAttribute to inject asciidoc attributes in config root documentation

[yrodiere]

The problem is the following:

1. I have a config group defined in extension A.
2. Extensions B and C each have a config root, which uses the config group from extension A.
3. The documentation of that config group needs to link to a section of a guide.
4. The link to the guide of extension B and C would be different, since each has its own guide.

You can take the example of #39416.

Ideally, I'd just use xref:#someanchor and all would be fine: the link would be to the same page, no need to alter it based on context.

But... we allow listing the documentation of configuration properties in other contexts than the extensions' main guide; for example in all-config.adoc. In such context, a link to the same page would not work.

In this PR I tried to solve the problem by adding a @ConfigDocAttribute annotation. The idea would be that the config group in extension A references an AsciiDoc attribute (variable) to build its links, and each config root in extensions B and C would assign a different value to that attribute. You can see how it's used in practice in the last commit of #39416: 44d8359

It worked well... until I noticed that you can only ever assign values to attributes outside of an asciidoc block. Critically, you cannot change attribute values in the middle of a table, which completely breaks the approach for all-config.adoc.

So, submitting this for discussion... how would you rather we solve it, @gsmet?

At this point the only viable option seems to be some custom variable definition/replacement in the Quarkus tool suite: we'd still use something similar to @ConfigDocAttribute, but would substitute attribute references ourselves, either when rendering the Qute templates (e.g. in io.quarkus.maven.config.doc.generator.AbstractFormatter#formatDescription), or (even better) when we generate quarkus-config-javadoc.yaml.

Alternatively we could have something less flexible, that doesn't allow custom attributes, but allows inserting links to the guide of the extension of the config root, with a parameterized anchor. That would still need to be handled by our own tools, though.

[github-actions]

🎊 PR Preview aa93848 has been successfully built and deployed to https://quarkus-pr-main-43808-preview.surge.sh/version/main/guides/

• Images of blog posts older than 3 months are not available.
• Newsletters older than 3 months are not available.

[gsmet]

I think we can close this in favor of #43943 which looks like a better approach as discussed earlier this week.