Add symbolic link to examples

[gastaldi]

See https://docs.antora.org/antora/latest/symlinks/ for details

[gastaldi]

Hm, the maven build didn't like it, let me investigate why

[gastaldi]

@abelsromero @LightGuard is this a known issue with the asciidoctor maven plugin?

[gastaldi]

I created asciidoctor/asciidoctor-maven-plugin#588 to track this

[gsmet]

I have a setup that works here:

• https://github.com/quarkiverse/quarkus-github-app/blob/main/docs/templates/includes/attributes.adoc for the attribute
• https://raw.githubusercontent.com/quarkiverse/quarkus-github-app/main/docs/modules/ROOT/pages/commands.adoc for the actual includes
• https://github.com/quarkiverse/quarkus-github-app/tree/main/docs/modules/ROOT/examples/command/airline for the source code
• https://github.com/quarkiverse/quarkus-github-app/blob/main/docs/pom.xml#L29 to actually get things compiled and validated by Maven

[gastaldi]

Using @gsmet's example above I managed to make it work (but without compiling, since it would require setting the dependencies and put in the expected packages).

I think we can add the examplesdir attribute in the quarkiverse-parent pom.xml to make configuration easier, WDYT?

[gsmet]

I /think/ I included this new stuff in the template.

[gastaldi]

@gsmet that's right, you did, but https://github.com/quarkusio/quarkus/blob/main/independent-projects/tools/base-codestarts/src/main/resources/codestarts/quarkus-extension/code/quarkiverse/java/docs/pom.tpl.qute.xml#L28 assumes that everything under the examples/ is compilable, which may not be necessarily true

[gsmet]

Yeah, for me, the whole point of that was to have compilable examples. If not compilable, better add them directly in the doc and not bother about creating external files.

[gastaldi]

They are already compiled when the integration tests are executed, so the idea is to just reference them in the docs instead of having it copied somewhere

[abelsromero]

I answered asciidoctor/asciidoctor-maven-plugin#588 but reading this I am confused. This repo is crearly and Antora module, it doesn't make sense to use the asciidoctor maven plugin unless you are reusing pieces of docs somehow. Which I would not recommend, Antora adds many things on top and we cannot support them unless we build a full reimplementation.

[gsmet]

@abelsromero so basically, we are using the Maven plugin to get some local rendering to check the output. Except for that, we don't use it.

And the modules of several repositories are then aggregated into a single Antora website.

So our general aim is to have both outputs working so that people can check the output in their local repo before pushing it.

[abelsromero]

Thanks @gsmet I'll integrate that into our story, there may be something we can do to support this preview scenario 🙇 .

[michael-simons]

@all-contributors please add @gastaldi for infra

[allcontributors]

@michael-simons

I've put up a pull request to add @gastaldi! 🎉