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.