What I really like about the external_toc plugin is that all the navigation is defined in one place. I configured my project to look for a
_toc.yml file, and that contains all the entries that will be included, and what order they will be included in. I’m using the Furo theme so the table of contents populates the whole of the left hand navigation bar and I find it helpful to have it all in one place rather than looking for
toctree directives nested all in different files and being assembled (or not, as I discovered) to create the navigation.
Since each file can only be included in the navigation once, a particular page such as the “getting started” file can be listed specifically, with others from the same directory included using the
glob keyword to match the path with a wildcard. This is very helpful and I use it in a few places!
However your navigation is constructed, you can use the
.. tableofcontents directive in a page at any level. Just like when using a
toctree directive, this displays the navigation entries below the current page, so it’s useful for detailing subsections without needing to curate lists or indexes.
If you’re building a sphinx project yourself and have tips to add, I’d love to hear them. It’s a great tool but I know that I have much to learn as well :)
Also published on Medium.