As a newcomer to Sphinx, I found many things confusing, but the table of contents or “toc” configuration was the thing that almost made me change my mind and pick a different platform! I now have a setup that works pretty well, using Sphinx External TOC, so I thought I’d share my setup.

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 :)