gh-123452: Improved ToC navigation within documentation sections #123453
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,6 +3,7 @@ | |
| %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% | ||
|
|
||
| .. toctree:: | ||
| :maxdepth: 2 | ||
|
|
||
| whatsnew/index.rst | ||
| tutorial/index.rst | ||
|
|
||
| Original file line number | Diff line number | Diff 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
Member
There was a problem hiding this comment. Comparing {# 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 Here we have two
Author
There was a problem hiding this comment. 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
Author
There was a problem hiding this comment. 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.
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> | ||
There was a problem hiding this comment.
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!
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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.