Multiple Levels of Toctree's in Python-Sphinx

Question

I'm trying to use sphinx in a way to document multiple "levels" of documentation, eg:

• Api Reference
• Manual
• Tutorials
• Etc.

The idea is that the Table of Contents is shown on the sidebar relative to the section you're in. So when you're on the main index it only shows the sections mentioned above. When you go into eg. "Manual" it shows a different ToC specific to that section, and a way to go back to the main ToC.

I've been trying to figure out how to get this to work in Sphinx without hacking it in, but so far can't quite figure out a way. The folder structure is already reflecting the different sections (ie. all "manual" documentation is stored under _source/manual) and I've tried placing separate index files in each of those directories, but it appears that the toctree functionality only looks at the main index file.

I am using the "readthedocs" theme, the code I'm looking at specifically is https://github.com/snide/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/layout.html#L93

Can anyone tell me how I would go about adding a ToC like this using Sphinx?

Thank you

Answer 1

(Maybe a little bit late for this response) I have a similar situation, three sections contained in the same TOC Tree:

• Hardware
• Software
• Tutorials

I was trying to achieve the same, that is hiding from my sidebar menu everything that doesn't belong to the current toctree-l1. Knowing that Sphinx adds the CSS class 'current' I came up with:

#sidebar li.toctree-l1:not(.current){
  display: none;
} 

It is not the best solution ever, but since Sphinx can only handle one main root for documentation and, from that one, it creates the entire TOC Tree, if you only need it for the sidebar menu, CSS should work for you.

Screenshot of my menu just showing content below one section:

Answer 2

It appears that a .. toctree:: in a document in a subdirectory is rooted at that subdirectory (see eg https://docs.python.org/2/_sources/howto/index.txt ) . For the upper-level TOC, :maxdepth: limits the inclusion of lower levels.

This can be placed into the sidebar by making a corresponding template and adding it to html_sidebars build parameter. UPDATE: doesn't work; in a sidebar template, TOC always has its root at the top.