Show 3rd level headers

[ericholscher]

Copying from readthedocs/readthedocs.org#604

The new theme is lovely, but the way it handles the sidebar navigation breaks things.

http://python-notes.curiousefficiency.org/en/latest/python3/questions_and_answers.html is a good example of the problem.

With the default Sphinx approach, navigation within that page is easy: the level 2 heading and the level 3 subheadings are shown at the top of the side nav bar, with the previous and next topics presented below that.

With the new default RTFD theme, the side bar always shows the nav for the entire site, bringing in all the other irrelevant L1 headings, but doesn't display any of the L3 headings within the document itself. That means I can only navigate within the doc by popping back up to the overview page for that section to get access to the third level of the TOC.

[pdion891]

Hi, Can we show 3 level of section into the left sidebar with this patch ?

[winhamwr]

Hello,

My ideal solution to this would be either Dynamic ToC Levels or a new navigation element.

Dynamic ToC Levels

For the current page, the TOC always includes all H1's, all ancestors of the current section, siblings of the current section and the current section's direct children. Taking inspiration from the bootstrap docs, we would detect the scroll position and if you're in an H2, the ToC expands to display the H3's.

A challenge might be visually displaying deep nesting without using a ton of horizontal space. We might be able to just decrease the left margin size and still communicate nesting effectively. If we can't, maybe automatic numbering could help or maybe breadcrumb-style indicators (>, >>, >>>, >>>>) would convey nesting without using as much space.

H3 example

If you're in an H3, you can see:

• All H1's
• Your parent H2
• Your parent H2's siblings
• Your H3
• Your H3's siblings
• Your child H4s

H4 example

If you're in an H4, you can see:

• All H1's
• Your grandparent H2
• Your grandparent H2's siblings
• Your H3 parent
• Your H3 parent's siblings
• Your H4
• Your H4's siblings
• Your H5 children

New navigation element

Add a new UI element for the current page's ToC, which will display all nesting levels. This could go on the right side in the desktop view and maybe it slides from the right in the mobile view. I don't love this solution, though.

Thoughts?

-Wes

[mightyiam]

+1

[beddari]

A solution to this would increase usability for my use cases ...

[martinpengellyphillips]

+1

[tgamblin]

+1

[safl]

+1

[AlessandroGianfelici]

+1