Right now when we click in a doc page like here we don't see the ToC in the context of the full docs, only what's under the current page. And it's a recursive problem, e.g: https://docs.softwareheritage.org/devel/apidoc/swh.model.html#module-swh.model.hashutil
The usual solution to have a better navigation in Sphinx is to change localtoc.html -> globaltoc.html, but because the ToC have always been broken in the docs, it just doesn't work to do that change, the globaltoc is completely blank when we do that. I fought with the alabaster theme to make it work properly, but I just couldn't make it work properly, and the behavior kept changing from page to page.
Switching to the RTD theme improved marginally everything I was working on, because:
- it properly highlighted all the TOC problems, instead of showing blank sections every time some toc had some kind of issue in it
- it was consistent across all pages, instead of working only in some pages
Since there doesn't really seem to be a consensus on which theme looks better, and the navigation is improved a lot by switching, we're going to do that. This will at least highlight all the TOC issues for the time being, and when everything is fixed on the TOC side, if someone wants to switch back to another theme it will be way easier.