Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sneakers-the-rat wants to merge 8 commits into
base:main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9c85b30
local toc with immediate parents, less in the global toc
sneakers-the-rat Aug 29, 2024
c1b2e99
cleanup template comment
sneakers-the-rat Aug 29, 2024
a24f20a
tabs to spaces
sneakers-the-rat Aug 29, 2024
cb1f061
add title to global toc entry, make formatting match
sneakers-the-rat Aug 29, 2024
d16545e
Apply suggestion from @hugovk
sneakers-the-rat May 12, 2026
0df7ac8
newline
sneakers-the-rat May 13, 2026
0ad85a4
strip tags from link title, limit to the most proximal 4 parents.
sneakers-the-rat May 13, 2026
573bfa1
striptags from the global toc header to match, even though that shoul…
sneakers-the-rat May 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Doc/conf.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -312,7 +312,7 @@
html_sidebars = {
# Defaults taken from https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_sidebars
# Removes the quick search block
'**': ['localtoc.html', 'relations.html', 'customsourcelink.html'],
'**': ['customlocaltoc.html', 'relations.html', 'customsourcelink.html'],
'index': ['indexsidebar.html'],
}

Expand Down
1 change: 1 addition & 0 deletions Doc/contents.rst
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -3,6 +3,7 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

.. toctree::
:maxdepth: 2

@sneakers-the-ratsneakers-the-ratMay 11, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@hugovkhugovkMay 12, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What does this change?

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

@sneakers-the-ratsneakers-the-ratMay 12, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


whatsnew/index.rst
tutorial/index.rst
Expand Down
29 changes: 29 additions & 0 deletions Doc/tools/templates/customlocaltoc.html
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
{#
Customization of Sphinx's basic/localtoc.html

- When present, display links to the parent pages within sections,
rather than link to the global contents
- When parents are absent, display a link to the document root using the docstitle
#}
<div>
<div>
{%- if parents %}
{%- for parent in parents[-4:] %}
<h{{ loop.index0 + 3 }}>
Comment on lines +8 to +12

@hugovkhugovkMay 12, 2026•
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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><ahref="{{ 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-ratsneakers-the-ratMay 12, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-ratsneakers-the-ratMay 13, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Screenshot 2026-05-12 at 5 36 49 PM

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)

Screenshot 2026-05-12 at 5 34 40 PM

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.

@StanFromIrelandStanFromIrelandMay 13, 2026•
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Custom CSS goes in our Sphinx theme generally.

@sneakers-the-ratsneakers-the-ratMay 13, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread
sneakers-the-rat marked this conversation as resolved.
<a href="{{ parent.link|e }}"
title="{{ parent.title|striptags }}">
{{ parent.title }}
</a>
</h{{ loop.index0 + 3 }}>
{%- endfor %}
{%- else %}
<h3>
<a href="{{ pathto(root_doc)|e }}"
title="{{ docstitle|striptags }}">
{{ docstitle|e }}
</a>
</h3>
{%- endif %}
</div>
{{ toc }}
</div>
Loading