Change TOC generation to make it more flexible

[javiereguiluz]

Problem

In Symfony Docs is very common to have ultra-long, but very narrow, TOC. See for example this page: https://symfony.com/doc/current/routing.html

Thanks to some redesigns, we can now display those long TOCs in two columns, while keeping the normal and short TOCs as before.

Solution

There are two kinds of TOCs:

• Embedded: these are the TOCs that are included in doc pages via the .. toctree directive. They are fully generated with this builder and rendered via toc.html.twig
• Programmatic: these are the TOCs that symfony.com adds itself at the beginning of doc pages. These are generated with private Twig templates using the fjson data generated by this builder.

This PR adds a new tocOptions property with the information we need about the TOC. It does for the two kinds of TOCs:

• Programmatic: this one is easy because it's based on the JsonGenerator and the entire logic is small and contained in that class.
• Embedded: this one is tricky. I had to cpoy+paste the entire TocNodeRenderer class from Doctrine RST parser. I hope there's a better solution for this.

Can you please help me find a better solution for embedded TOCs? Thanks!

[nikophil]

Hello @javiereguiluz

it's just an idea, but can't you use a twig extension? Since all these "toc options" are only related to the html rendering. This way, you don't have to touch to TocNodRenderer

And maybe we can externalize this "toc options" logic into another class which will be used into the twig extension and the JsonGenerator

[javiereguiluz]

@nikophil that's the kind of brilliant thinking I was looking for! Thanks a lot 🙇

Your solution solves this problem very easily and avoids all duplication (with Doctrine code and with our own code). Thanks a lot!