Show entire toctree in Read The Docs sidebar

Question

It's my understanding the new Read The Docs theme generates the sidebar from the toctree with a depth of 2. My documentation is relatively deep, and a depth of 2 is not enough for it to be useful. How can I increase this limit, or preferably remove it entirely?

If that's not reasonably possible, how can I use local ToC's instead of the global toctree?

Answer 1

Note: The previous answer was outdated. As @Ariel notes in a comment, the maxdepth is now configurable by setting navigation_depth in html_theme_options. As per the README, change this in your project's conf.py:

html_theme_options = {
    'navigation_depth': 4,
}

---

Looking at the source for the theme on Github, it seems the ToC depth is hard-coded on line 93 in sphinx_rtd_theme/layout.html. As such, there is no configuration you can make to the theme to override it.

Since the line is hard-coded, you will always get the global toctree returned by toctree, instead of the local one "supported" by the following lines.

You can, of course, fork the theme and change that line for your local use (and you can use custom themes on RTD so should work there as well). I tried doing so with the demo theme. It looks like this with maxdepth=3, so some additional CSS might be needed. The documentation for the toctree template function specifies that for unlimited depth, simply pass maxdepth=-1. Note that this does not add collapse/expand to the sublevels of the TOC.

Might be a good target for a pull request?

Answer 2

There is no way of customizing this behavior, at least in ReadTheDocs. However, you can still read the additional layers of detail in the pages - they just don't show up in navigation.