Many levels of Toctree in Python-Sphinx

Question

I am trying to use sphinx to document several "levels" of documentation, for example:

• Link to Api
• Guide
• Study guides
• Etc.

The idea is that the table of contents is displayed in the sidebar relative to the section you are in. Therefore, when you are on the main index, it shows only those sections that were mentioned above. When you go, for example. "Manual" shows another ToC specific to this section, and a way to return to the main ToC.

I tried to figure out how to make this work in Sphinx without hacking it, but so far I cannot figure out how. The folder structure already reflects different sections (i.e., all the “manual” documentation is stored in _source / manual), and I tried to place separate index files in each of these directories, but it seems that the toctree function looks only at the main index file.

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

Can someone tell me how I am going to add ToC like this using Sphinx?

thanks

Answer 1

(Maybe a little late for this answer) I have the same situation as you, I have three sections contained in the same TOC tree:

• Equipment
• Software
• Study guides

I tried to achieve the same thing as you, which hides everything for my sidebar menu that does not apply to the current toctree-l1. Knowing that Sphinx is adding the "current" CSS class, I came up with:

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

This is not the best solution ever, but since Sphinx can just process one main root for documentation and from it it creates the whole TOC tree, if you need it only for the sidebar menu, CSS may work for you.

Screenshot of my menu showing the content below one section:

Answer 2

It looks like .. toctree:: in a document in a subdirectory is rooted in this subdirectory (see, for example, https://docs.python.org/2/_sources/howto/index.txt ). For top-level :maxdepth: limits the inclusion of lower layers.

This can be placed in the sidebar by creating the appropriate template and adding it to the html_sidebars parameter. UPDATE: does not work; in a sidebar template, a TOC always has its root at the top.