[FEATURE] Support index generation (genindex)

[linawolf]

Sphinx-authored documentation -- including TYPO3 Core's own Changelog
files -- relies on .. index:: entries so readers can jump straight to
every page a term is discussed on, the way a printed book's index does.
This library parsed those entries but threw them away, so porting such
docs here meant silently losing that navigation aid.

Entries are now collected project-wide and made available as a genindex
page, so documentation migrated from Sphinx keeps working the way its
authors intended.

Each term is also stamped onto the section it belongs to as a data
attribute, independent of any genindex page. That's for tooling that
crawls the rendered HTML rather than the reST source -- a custom search
engine such as TYPO3's Elasticsearch integration can pick up the same
terms an author already tagged with index, instead of reimplementing
that logic itself.

Closes #921

Assisted-By: Claude Sonnet 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01Y48g2S9Q2uUVLcsTEAeyGX
Signed-off-by: linawolf

[jaapio]

I think this is a great addition to what we already do with this project. However I would love to see a bit smaller PR in steps. I think the template on documents makes a lot of sense also in a separate feature.

The compiler pass needs some extra attention. It contains a lot of logic, which could be split. This would allow tools like phpDocumentor to extend the index before rendering.

[linawolf]

@jaapio I applied all requested changes, please resume review

[linawolf]

@jaapio Replaced the phpstan-type array shapes in the IndexCollector classes with real value classes (GenIndexRowData, GenIndexTermData, GenIndexTermMap) per your Slack feedback and the article you linked. Ready for another look.

[jaapio]

I have the feeling that the index terms should not be part of the section node. It's more like some kind of metadata that we want to add to the nodes? What if we would add this as a more generic node element?

If I see the rendering as a data element, and combine that with options I'm researching with https://pagefind.app/docs/metadata/ this could be very useful,

Maybe it makes sense to add some metadata property to the abstractNode, That will make it more generic.

public function addMetaData(DataNode $node)

The rendering should check the metadata for nodes it can handle. We could use a custom twig filter/function for this to render the data attributes on the nodes.

<h1 data-index="{{ renderIndexData(node) }}">

This new system will help us to add attributes to the html elements in a more generic way, allowing people to do even more, like what I try to do with the pagefind, to make static search possible.

[jaapio]

the options scope and no-letter-index seem to be missing on this directive.

[jaapio]

The :name: option described in the linked sphinx docs seem to be missing?