Integrate the Sphinx theme
weaverryan opened this issue · 6 comments
The current docs use this theme when building: https://github.com/symfony/symfony-docs/tree/master/_build/_themes/sphinx_rtd_theme
We need to integrate that: use it when we build our docs. And, ideally, keep the standard Sphinx theming-system as much as possible (not reinventing our own).
We will likely also need a "blank" theme, or an option to use no theme, so we can render just the raw content needed for symfony.com.
how do you like us to do that ?
shall we add some post process, after the rendering is finished, to create some other html files with twig ?
do you have an example of what it looks like ? i've understood it's a read the docs theme, but shall we generate the left menu ?
thanks.
To "be like Sphinx", we would create a theme (https://www.doctrine-project.org/projects/doctrine-rst-parser/en/latest/themes.html#themes) where the layout.html.twig is something that is at least enough to look functional (not just a completely, unstyled HTML page). Actually, this is probably the ONLY theme we need - for deploying to symfony.com, we can use the JSON files to get the HTML content without the layout code.
It would be awesome to make the rst-parser compliant with sphinx themes... but that seems unlikely... and probably not worth the effort
i didn't even know that this option ever existed ;)
i don't think that would be to much work for Jon to expose the main TOC to the main templates...
i think it's worth to have a main nav (i think that's currently not possible...)
i didn't even know that this option ever existed ;)
There are constantly new things!
i think it's worth to have a main nav (i think that's currently not possible...)
Hmm, yea, I think having a "main nav" makes sense to me to. So, we would just need to expose some Twig variable to layout.html.twig that contains that info, right?
i think, what we need would be the main toc (with all navigation levels), and the current page id, and then we could show only the top level entries + the siblings of the current page
that wouldn't be THAT work for us nor for Jon