gh-123452: Improved ToC navigation within documentation sections by sneakers-the-rat · Pull Request #123453 · python/cpython · GitHub

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/

All commit authors signed the Contributor License Agreement.

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.

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.

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

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.

(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.

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 :)

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

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

Documentation build overview

📚 cpython-previews | 🛠️ Build #34091445 | 📁 Comparing 9b15e40 against main (4b33308)

🔍 Preview build

308 files changed · + 9 added · ± 298 modified · - 1 deleted

+ Added

± Modified

- Deleted

library/asyncio-policy.html

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

What does this change?

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

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.

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

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?

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

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.

Custom CSS goes in our Sphinx theme generally.

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

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

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!

@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.

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.

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

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

Went stale again but I still regularly run into this problem

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

…d never be a problem

bedevere-app Bot mentioned this pull request Aug 29, 2024

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

Open

bedevere-app Bot added the awaiting review label Aug 29, 2024

sneakers-the-rat mentioned this pull request Aug 29, 2024

<spam> #123454

Closed

hugovk added the skip news label Aug 29, 2024

sneakers-the-rat force-pushed the docs-toc branch from 6a639fc to 38baf4a Compare September 21, 2025 05:12

sneakers-the-rat requested review from AA-Turner and hugovk as code owners September 21, 2025 05:12

github-actions Bot added the stale Stale PR or inactive for long period of time. label Apr 18, 2026

sneakers-the-rat force-pushed the docs-toc branch from 38baf4a to 2de2d67 Compare April 18, 2026 20:30

sneakers-the-rat requested a review from StanFromIreland as a code owner April 18, 2026 20:30

StanFromIreland removed the stale Stale PR or inactive for long period of time. label Apr 20, 2026

sneakers-the-rat force-pushed the docs-toc branch from 2de2d67 to 89267df Compare May 11, 2026 20:50

sneakers-the-rat commented May 11, 2026

View reviewed changes

hugovk reviewed May 12, 2026

View reviewed changes

Comment thread Doc/tools/templates/customlocaltoc.html

sneakers-the-rat force-pushed the docs-toc branch from 4cd8e76 to 573bfa1 Compare May 13, 2026 02:09

github-actions Bot added the stale Stale PR or inactive for long period of time. label Aug 16, 2026

sneakers-the-rat and others added 8 commits August 16, 2026 13:33

local toc with immediate parents, less in the global toc

5eaa724

cleanup template comment

363116a

tabs to spaces

e97c9b1

add title to global toc entry, make formatting match

188e62c

Apply suggestion from @hugovk

8038d88

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

newline

8e60130

strip tags from link title, limit to the most proximal 4 parents.

b29a25f

striptags from the global toc header to match, even though that shoul…

9b15e40

…d never be a problem

sneakers-the-rat force-pushed the docs-toc branch from 573bfa1 to 9b15e40 Compare August 16, 2026 17:33

github-actions Bot removed the stale Stale PR or inactive for long period of time. label Aug 22, 2026

+                <div>
+                  <div>
+              {%- if parents %}
+              {%- for parent in parents %}
+                    <h{{ loop.index0 + 3 }}>

               %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
               .. toctree::
+                 :maxdepth: 2

gh-123452: Improved ToC navigation within documentation sections by sneakers-the-rat · Pull Request #123453 · python/cpython · GitHub

Repository navigation

gh-123452: Improved ToC navigation within documentation sections - #123453

gh-123452: Improved ToC navigation within documentation sections#123453sneakers-the-rat wants to merge 8 commits intopython:mainpython/cpython:mainfrom sneakers-the-rat:docs-tocsneakers-the-rat/cpython:docs-tocCopy head branch name to clipboard

Conversation

sneakers-the-rat commented Aug 29, 2024 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Global ToC

Currently

This PR

Local ToC

Currently

This PR

Within-Document ToC

Index ToC

Discussion

Uh oh!

ghost commented Aug 29, 2024 • edited by ghost Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bedevere-app Bot commented Aug 29, 2024

Uh oh!

bedevere-app Bot commented Aug 29, 2024

Uh oh!

sneakers-the-rat commented Aug 29, 2024

Uh oh!

devdanzin commented Sep 21, 2025

Uh oh!

sneakers-the-rat commented Sep 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

devdanzin commented Sep 21, 2025

Uh oh!

github-actions Bot commented Apr 18, 2026

Uh oh!

sneakers-the-rat commented Apr 19, 2026

Uh oh!

read-the-docs-community Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

sneakers-the-rat May 11, 2026

Choose a reason for hiding this comment

Uh oh!

hugovk May 12, 2026

Choose a reason for hiding this comment

Uh oh!

sneakers-the-rat May 12, 2026

Choose a reason for hiding this comment

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

hugovk May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sneakers-the-rat May 12, 2026

Choose a reason for hiding this comment

Uh oh!

sneakers-the-rat May 13, 2026

Choose a reason for hiding this comment

Uh oh!

StanFromIreland May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sneakers-the-rat May 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

willingc commented May 12, 2026

Uh oh!

sneakers-the-rat commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

willingc commented May 13, 2026

Uh oh!

gh-123452: Improved ToC navigation within documentation sections#123453
sneakers-the-rat wants to merge 8 commits into
python:mainfrom
sneakers-the-rat:docs-toc

sneakers-the-rat commented Aug 29, 2024 •
edited by github-actions Bot
Loading

ghost commented Aug 29, 2024 •
edited by ghost
Loading

sneakers-the-rat commented Sep 21, 2025 •
edited
Loading

read-the-docs-community Bot commented May 11, 2026 •
edited
Loading

hugovk May 12, 2026 •
edited
Loading

StanFromIreland May 13, 2026 •
edited
Loading

sneakers-the-rat commented May 13, 2026 •
edited
Loading