[PRA-153] docs: Add autogenerated metadata description

[izmalk]

Description

Add an autogenerated metadata description for every documentation page.

Checklist

• I have added or updated any relevant documentation.

[deusebio]

How is this auto-generated? could you provide guidance on how you did this, such that we can also do this when creating new documentation?

Also we generally prepend the description with the Jira ticket. I believe we forgot that when merging the previous PR about docs, but could you update the title of the PR?

[izmalk]

I used agentic Copilot (company licence, Claude Sonnet 4.5 model) in VScode with a pre-designed long prompt (which works great for that specific task). It detects all the documentation source files (by file extension and location), creates a summary and formats it in a specific way (frontmatter syntax for MyST). It also checks that the summary roughly fits expected length, that docs can be built without errors, that summary is there in the HTML header, etc.

I'm not sure this can be very useful for the generic documentation task, as this one is very simple:

• Create a list of all documentation files with a simple bash command
• Summarise contents of each page in a text roughly 120-160 character long
• Add the summary in a specific syntax at the very beginning of the relevant page
• Test thoroughly

Creating a summary of existing content is something that LLMs are very good at. And I still find some problems later during review that I fix manually. The same approach can't be directly applied to create useful new documentation. It's just a lot of menial work here done in a mostly automatic way. I can do a Tech Talk on this use case if you want.

[theoctober19th]

Nice work, Vladimir. The automation to generate this seems interesting -- and to be honest I found it quite efficient and precise in most cases. I have a few minor comments here and there.

[izmalk]

Comments for review suggestions.

[theoctober19th]

Thanks for the enhancement!

[deusebio]

I used agentic Copilot (company licence, Claude Sonnet 4.5 model) in VScode with a pre-designed long prompt (which works great for that specific task).

Oh I see. Yes, that's a very good use-case.

I can do a Tech Talk on this use case if you want.

I believe it would be nice that, or also just showing it on a Demo session. Either way, I believe it is worth sharing :D

[deusebio]

Looks good! I have just a suggestions to revise some of the headings to make it more compliant with Diataxis (that LLMs do not seem to like :D). For instance, I would avoid "learn" in how-to guides, and also provide references to Diataxis in the main indices

But these are mostly non-blocking minor improvements. So up to you whether you feel are sensible to follow up