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?

Jackhammer

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?

Shortage

Isn't this a sidebar with more than 2 levels? read-the-docs.readthedocs.org/en/latest/getting_started.html How can I mimic this behavior? It only shows multiple levels when I an item with subitems, but that's good enough for me. – Shelves

Ok, I was on version 0.1.6, apparently they added support for depth 3 and 4 in version 0.1.8: github.com/snide/sphinx_rtd_theme#v0-1-8 – Shelves

Does this work on the online version of RTD? It seems to only work locally for me, see the corresponding issue on Github – Falconer

For depths higher than 4, the sidebar seems to miss-behave. Topics will not properly indent relative to parent topics, for example. – Dissuasive

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.

Penoyer