ENH: be able to configure the number of levels in the page TOC

[jorisvandenbossche]

Currently we collapse all but the first level of headers, and then only show additional levels for the section where you are at the page.

In some case (e.g. when having relatively short pages), it might actually be perferable to show more or all levels by default and not collapse them.

@bryevdv @bjnath

[jorisvandenbossche]

I think this would certainly be a nice addition to the theme.

I thought originally this would be fairly straightforward. But, currently, this collapsing behaviour is defined in css here:

https://github.com/pandas-dev/pydata-sphinx-theme/blob/a8ae966da192c47aedf1344ee65aa461a6873aa2/src/scss/index.scss#L344-L356

I am not fully sure what the best way is to change something in the css based on a sphinx config option (normally you could have a templated css file with sphinx, but since we already use SASS preprocessor, not sure that is possible).

The easiest is maybe in the html template to use a different class name for both options, and then we can have different css for both classes (one that collapses, the other not).

[bryevdv]

I am definitely not the CSS expert who can help with any suggestions but happy to try anything out if that's ever useful!

Also just for a concrete example of where this would be useful, there is this page:

https://docs.bokeh.org/en/latest/docs/user_guide/interaction/widgets.html

It only has two top level headings on load

But being able to automatically see on more level would make the page much more usable:

[jorisvandenbossche]

Yes, that's certainly a good use case.

In an ideal case, what is your preference for the solution (feature wise, not technical):

• Global config, or being able to set the level per page
• Simply show either only the first or otherwise all levels, or being able to eg specify to show the first 2 levels but still collapse the other levels?

[jorisvandenbossche]

BTW, short term, it can also be customized with a relatively straightforward css override of the snippet I showed above.

[choldgraf]

I think this is a great idea 👍

I'd imagine behavior like:

in conf.py

{
"toc_show_levels": 2
}

and this would make all TOC levels up to 2 always shown, with sub-levels shown on scroll.

[bryevdv]

Global config is fine with me