CODEWITHSUNDEEP
pythonpython-sphinxsidebarsectionstoctree
Joe D
Joe D

Reputation: 401

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.

Upvotes: 40

Views: 8568

Answers (4)

Steve B.
Steve B.

Reputation: 41

Here's how it can be done for the mobile-ready "sphinx_rtd_theme" theme.

Add to your custom JavaScript the following [Vanilla] JS:

function toctreeExpand ()
{var toctree=document.querySelector('button.toctree-expand');

 toctree.focus ();
 toctree.click ();
} // function toctreeExpand ()                                                                

function deferToctreeExpand ()
{// flush any pending housekeeping events first...                                            
 setTimeout (toctreeExpand);
} // function deferToctreeExpand ()                                                           

function init ()
{var anchors=document.querySelectorAll('a.reference.internal');

 toctreeExpand ();
 for (var anchor of anchors)
     anchor.addEventListener ('click', deferToctreeExpand);
} // function init ()                                                                         

window.addEventListener ('load', init);

It expands only the top-level entries -but that's a hell of a lot better than the default of showing the tree completely collapsed as a single entry! This could be improved upon by (re-)expanding a nested branch where you just clicked (possibly three levels down...) But I have a full inbox; so the fix above was acceptable for now for me...

Upvotes: 0

user1460675
user1460675

Reputation: 427

Unfortunately, there's an open bug about this: https://github.com/readthedocs/sphinx_rtd_theme/issues/455

Upvotes: 3

Al Landy
Al Landy

Reputation: 31

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!

Upvotes: 3

Stephane Martin
Stephane Martin

Reputation: 1642

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

Upvotes: 14

Related Questions