gh-123452: Improved ToC navigation within documentation sections

[sneakers-the-rat]

fix: #123452

This PR makes two minor modifications:

• Decrease the global Toctree's maxdepth to 2
• Adds links to document parents within the local toctree.

Global ToC

Currently

this is roughly 1/20th of the total Toc length. The changelog/whats new go on for about half of that, and the user-facing tutorial and language reference is >halfway down.

expand/collapse long image

This PR

expand/collapse long image

Local ToC

Currently

The current sub-document/document section is not shown, and the "Table of Contents" links to the global ToC

This PR

Within-Document ToC

The current sub-document/document section is linked at the top of the table of contents when any such parents exist. There aren't any double-nested documents as far as i can tell, but if there were, then they would be be shown with successive header levels.

Index ToC

When there is no parent, as is the case in the section ToC's, a link to the global ToC is shown.

Discussion

Unlike sphinx's localtoc, the toc is always shown even when it only has one link in it, as that is how the title of individual pages/ToCs is encoded - without it, sometimes the "Table of Contents" link is absent and sometimes it's not, and it's unclear without understanding the code why that would be.

I am hoping this is a relatively uncontroversial PR, as it is a small change to the code that would make a relatively large improvement to the usability of the docs for those of us who read on mobile or split their screen into columns where the breadcrumbs are invisible. I tried to follow naming conventions for customlocaltoc.html mimicking customsourcelink.html, but am happy to modify this however the maintainers would like :)

• Issue: Within-section navigation missing for smaller screens, global contents difficult to navigate. #123452

---

📚 Documentation preview 📚: https://cpython-previews--123453.org.readthedocs.build/

[ghost]

All commit authors signed the Contributor License Agreement.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[sneakers-the-rat]

I don't believe this needs a NEWS entry since it's a docs change, but lmk if it needs one and i'll write it

[devdanzin]

I really like the results and the code looks clean and tight (didn't build the docs locally).

Has this been discussed on discuss.python.org already? If not, that could be a way to attract reviews from core docs people. If it has been discussed, I can try pinging some people that would be interested in joining the discussion.

[sneakers-the-rat]

(didn't build the docs locally).

Do the preview docs get the gist? though that build is outdated at this point: https://cpython-previews--123453.org.readthedocs.build/

Has this been discussed on discuss.python.org already?

No, I had not posted it there! Is that a standard part of the contributing process? Sorry if I missed that. I'll post there when I'm back at home at keyboard.

---

Edit: sorry for causing noise, just saw rebasing re-requested review.

[devdanzin]

Is that a standard part of the contributing process?

No, but it can be an interesting way of getting feedback and attention. No pressure or hurry to post, just a suggestion if you feel like it :)

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[sneakers-the-rat]

I see this got marked as stale, im not sure what i need to do to keep it unstale? I dont want to spam anybody, but i still regularly face this challenge when navigating the docs and would love it to be merged

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32665609 | 📁 Comparing 573bfa1 against main (4b33308)

  🔍 Preview build  

128 files changed · + 3 added · ± 125 modified

+ Added

• c-api/sentinel.html
• c-api/slots.html
• whatsnew/3.16.html

± Modified

• glossary.html
• index.html
• c-api/buffer.html
• c-api/code.html
• c-api/concrete.html
• c-api/descriptor.html
• c-api/dict.html
• c-api/exceptions.html
• c-api/extension-modules.html
• c-api/gcsupport.html
• and 115 more...

[sneakers-the-rat]

this is a separable change from the toc headers if that would be better to consider separately!

[hugovk]

What does this change?

For example, these both go down to 2.5.4.1, so I guess it's something else?

• https://docs.python.org/3/reference/lexical_analysis.html
• https://cpython-previews--123453.org.readthedocs.build/en/123453/reference/lexical_analysis.html

[sneakers-the-rat]

Just the depth of this page: https://cpython-previews--123453.org.readthedocs.build/en/123453/contents.html

We can remove this change or increase the number or whatever works, that page is just at the top of the hierarchy (and what you get bumped to whenever you click "up" in the ToC currently), and so if the hierarchy was easier to ascend and descend, then I thought it might be easier to have that page not list every child page, but a shorter view that can then be expanded.

But I don't want it to be a blocker for the main TOC header change, so if its controversial we can drop it.

[hugovk]

Something is wrong here, before:

• https://docs.python.org/3/library/email.message.html

After:

• https://cpython-previews--123453.org.readthedocs.build/en/123453/library/email.message.html

[hugovk]

Comparing Doc/venv/lib/python3.14/site-packages/sphinx/themes/basic/localtoc.html:

{# Sphinx sidebar template: local table of contents. #}
{%- if display_toc %}
  <div>
    <h3><a href="{{ pathto(root_doc)|e }}">{{ _('Table of Contents') }}</a></h3>
    {{ toc }}
  </div>
{%- endif %}

That's one <div> before the first h.

Here we have two <div> before the first h. Do we need both or can we drop one to keep it consistent?

[sneakers-the-rat]

No problem - I had added the second one to group all the header elements together with ToC as a sibling in case we wanted to style those as a group, but there currently aren't any CSS rules that target it, so can drop

[sneakers-the-rat]

fixed the other problems, and the TOC for a triple-nested page looks like this:

which is fine, but it's a little awkward - it's not that obvious that the top three are parent headers and then the one below that is the page contents. It might be useful to add some additional spacing or a divider after the header block, reduce the top-margins on the headers, or add some hierarchy indicators (this looks pretty crappy, just a 5 minute manual in-page css edit for the sake of illustration)

I don't see any custom css in here except for the profiling visualization css, so it might not be worth it to introduce it just for this, but i could write it inline if that would be desired.

or, if it's fine, and we want to remove this extra div, just lmk, no problem with that.

[StanFromIreland]

Custom CSS goes in our Sphinx theme generally.

[sneakers-the-rat]

got it, lmk if that would be a good addition!

[willingc]

Thanks for reviewing @hugovk and @sneakers-the-rat for your patience. I can also take a look after I arrive at PyCon.

[sneakers-the-rat]

Something is wrong here, before:

fixed in 65bb1fa , just needed to strip tags from the title attribute. good catch!

further thoughts about styling here - #123453 (comment)

Thanks for reviewing @hugovk and @sneakers-the-rat for your patience

no worries at all, i just wasn't sure if i was supposed to do something more to have this considered :). no rush and enjoy PyCon!

[willingc]

@sneakers-the-rat @hugovk I would really like it if we could collapse/expand the sections. I've always wondered why the sidebars open as a long list without the ability to collapse.

The pydata-sphinx-theme https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/navigation.html# has a nice implementation.

[sneakers-the-rat]

I would really like it if we could collapse/expand the sections.

i am a huge fan of the style of docs where there is one global toctree and the page you are on just controls which part of the toctree is expanded on load - but otherwise you can navigate from any page to any page by just expanding and collapsing the toctree. so i am of course very in favor of collapsible docs.

should we do that here or elsewhere? If elsewhere, we can remove the change here that decreases the maxdepth on the main page. otherwise, i am pretty sure this can be done with pure css at this point and i would be happy to do it, if it's ok if i make appropriate style changes like adding collapse/expand indicators and so on.

[StanFromIreland]

@willingc That's an open issue: python/python-docs-theme#245