Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to expand all the subsections on the sidebar toctree in Sphinx?

I was wondering if there is a way to expand all the subsections under the headers that are included in the index.rst file?

As an example, here is how it is:

Section 1 Section 2 Section 3 

And here is how I would like it to be:

Section 1   Subsection 1.1   Subsection 1.2   Subsection 1.3 Section 2   Subsection 2.1   Subsection 2.2   Subsection 2.3 Section 3   Subsection 3.1   Subsection 3.2   Subsection 3.3 

If I click on Section 1, it shows what's under that, but if I click on Section 2, contents of section 1 are hidden and only 2 is shown. I would like all 2 sections to be expanded every time I'm on the index page. I've tried adding toctree and maxdepth, nothing works.

like image 338
Joe D Avatar asked Jan 23 '13 10:01

Joe D


2 Answers

If you are using sphinx_rtd_theme, you can change the maximum depth of the sidebar menu in the html page by changing the 'toctree maxdepth' value defined in the file layout.html. This file is usually located in the directory source/_themes/sphinx_rtd_theme. There are several solutions:

  • The simplest, fastest solution: Show deeper toctree in sidebar

  • You are using an old version of the theme. Then you can set a new 'maxdepth' value (e.g., 3) in the line that says:

    {% set toctree = toctree(maxdepth=3, collapse=False, includehidden=True) %} 
  • You are using a newest version of the theme. Then you may have these lines in the file layout.html:

    {% set global_toc = toctree(maxdepth=theme_navigation_depth|int,                             collapse=theme_collapse_navigation|tobool,                             includehidden=theme_includehidden|tobool,                             titles_only=theme_titles_only|tobool) %} 

    In this case, you may define 'theme_navigation_depth' in theme.conf:

    [options] theme_navigation_depth = 3 

Recompile after the change is done... and don't forget to enjoy the Sun!

like image 36
Al Landy Avatar answered Sep 19 '22 20:09

Al Landy


Well, i lost approximately 3.4M neurons trying to read sphinx source code (was it written by a bunch of rabbid reckless raccoons ?! so many levels of abstraction).

So :

  • make your own sphinx theme (use a 3rd party theme as a base, very easy. I use 'readable' theme for that)
  • in the directory where you have theme.conf, add a "fulltoc.html" template, containing one line:

fulltoc.html:

{{ toctree(collapse=False) }} 

(Heh, notice the 'collapse' argument?)

  • in sphinx conf.py, modify the html_sidebars option to add your template; and declare your theme

conf.py:

html_theme_path = [customized_readable_theme.get_html_theme_path()] html_theme = 'customized_readable' html_sidebars = {'**': ['fulltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']} 
  • rebuild documentation
like image 99
Stephane Martin Avatar answered Sep 18 '22 20:09

Stephane Martin