Docs: Diataxis framework templates

[ebullient]

The directory structure: diataxis vs asciidoc is temporary, to identify what has been touched and what hasn't. Consider it an internal detail (not surfaced on the website).

the doc-\* pages are intended for those that will be contributing to Quarkus documentation, so they understand the intent/distinction between the four types of docs. This content also provides exemplars of each type: doc-\*-tutorial.adoc for tutorials, doc-\*-howto.adoc for how-tos, doc-\*-concepts.adoc for concepts, and doc-\*-reference.adoc for references.

Resolves #25355

UPDATE:

• Flattened back into the single asciidoc directory so we can make incremental progress on improving docs. See Docs: generate index.yaml with title + preamble #25952 for a tool that will enumerate the docs that don't fit in any of the target categories or are missing required things so we know what still needs to be done.

ADDITIONAL NOTES (2022-06-29):

• This does not impact website publishing. New docs following templates will still need to be added manually to be included on the website.
• Indexes are generated by tools introduced in Docs: generate index.yaml with title + preamble #25952 may allow a bit more automation (to pick up descriptions, and or allow iteration over docs of different types), but that tool is essentially experimental, to allow us to figure out how to then improve the publication process and work towards James' updated design that breaks out documents by type.

[quarkus-bot]

Thanks for your pull request!

The title of your pull request does not follow our editorial rules. Could you have a look?

• title should preferably start with an uppercase character (if it makes sense!)

This message is automatically generated by a bot.

[gsmet]

I added a bunch of comments. Some are minor, some not so much.

[gsmet]

I don't think it's such a good idea to have the sources like that.
We won't be able to compile them given the conventions you used so it's not really better than having them in the .adoc.

If we do that, we need to make _examples an appropriate source directory and the content of it a proper thing with packages but...

Problem is that you will end up with a gigantic Quarkus app if all the sources are in the same module. And it probably won't work as some extensions cannot be combined with some others.

[ebullient]

We can certainly make a proper src tree under examples if that's what we want to do. The comments alone are fine..

This is something I did want to ask. We could be annotating source from quickstarts (remote sources can still use tagged regions...), but I would like to see if we can get here somehow.

[gsmet]

Well, what I'm saying is that what you're suggesting here is not an improvement: it requires more work and is not compilable/compiled.
If you think you can make a proper src tree under examples, then let's demo it because my fear is that you won't be able to make it work properly without some really annoying work i.e. basically reconstructing the quickstarts here.

So my advice would be to get rid of this until we can find a proper solution. Or until you can show me what you did can work and will scale.

[ebullient]

or we acccept that this is a one-off that demonstrates what should be done using source from a quickstart ... I'm not sure I want to create a new quickstart just for this docs example.

I can make it more clear this is a one-off example, and perform a similar markup to the micrometer quickstart?

[ebullient]

One option (aside from this one-off example) is to encourage source samples to come from integration tests..

[ebullient]

Long term, I think pulling from integration tests (which are compiled and run) is the right answer. A build-time fetch/copy of referenced source files for use in docs (in the same way we generate config files), but the build/test happens in the integration tests that have the correct dependency configurations.

This kind of code referencing is also optional, but I wanted to have an example of it.

[maxandersen]

can we add a blurp stating including directly in adoc is ok?

[maxandersen]

LGTM.

does not change or affect current layout and let us get moving on getting diataxis doc approach going and evolve to what goes into website/docs sites.

[michalvavrik]

@ebullient clean install is the default goal for the profile quickly, so maybe you could leave it out for taciturnity?

[ebullient]

sure. new PR?

[ebullient]

Fixed in #26664