Docs: Bring summaries from Quarkus website guide_* file into docs

[ebullient]

Description

Goal: Generate all docs attributes from content in the quarkus dir.

To facilitate this, we need manually maintained information currently in th guide data for the main branch of the website:

• Copy the description field into the associated *.adoc file as a summary attribute.
• Copy the category-id (surrounding group) into the categories attribute.
  • Replace alternative-languages with alt-languages

[nderwin]

@ebullient Is this simply a matter of adding, for example

:categories: getting-started
:summary: Discover how to create your first Quarkus application.

to getting-started.adoc, then rinse and repeat for the other .adoc files mentioned in the link above?

If so, I could put together a PR for that. Is there a way to test that it works, or would that be covered in the larger refactoring effort?

[ebullient]

Yep. That's it. If you run the docs build, you can check the contents of the index files to make sure the values are present.

Building docs: https://github.com/quarkusio/quarkus/blob/main/CONTRIBUTING.md#building-the-documentation

[ebullient]

Note that some docs appear in the guide file more than once, as they are in different categories...

[nderwin]

Clearly, I'm doing something wrong. Updated my fork last night, made a branch off of main, ran the -DquicklyDocs build on the project, ran the build for the docs project, grepped for the summary text I added to the getting-started.adoc file, and only see it in the .adoc file, nothing in the target directory has it.

indexByFile.yaml and indexByType.yaml both seem to be unaffected.

[ebullient]

https://github.com/quarkusio/quarkus/pull/28491 was integrated overnight / this morning.

Can you double-check that the content of indexByFile for doc-contribute-docs-howto.adoc matches what is in the PR?

[nderwin]

Ah hah, just needed to re-update my fork. doc-contribute-docs-howto-adoc has the categories entry, as do the changes that I started to make. Cool.

[nderwin]

PR will be forthcoming, but here's a few things I noticed while working on this:

all-config.adoc and all-builditems.adoc refuse to generate the categories and summary, even though they are specified in the .adoc file. I'm not sure why.

There are several files mentioned in the guides-main.yaml file where there are no corresponding .adoc file:

• amazon-dynamodb, amazon-iam, amazon-kms, amazon-s3, amazon-ses, amazon-sns, amazon-sqs, amazon-ssm
• consul-config
• jgit
• logging-sentry
• neo4j
• reactive-messaging-http, reactive-messaging-websocket
• security-jpa
• tika
• vault, vault-auth, vault-datasource, vault-transit

There's also a lot of .adoc files that do not have a corresponding entry in the guides-main.yaml.

[ebullient]

I can have a look at all-config / all-builditems .. it is likely something the YAML generator is (or more likely is not) doing.

For the others, I think this is the list! =) I am fairly sure that all of the files you're looking for you will find in quarkiverse repositories.. https://github.com/quarkiverse. Handling the docs from those repos using generated metadata is also on my list (notes added to #28506). If you want to get all of the hacktoberfest credits for making PRs to add the attributes there, that's excellent.

And yes, docs that we have that are not in guides-main is one of several reasons I want to stop maintaining these guide files manually.

[ebullient]

Resolved by #28523