From 9c85b307369fa7d22e1d373243120656013072d2 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Wed, 28 Aug 2024 19:15:55 -0700 Subject: [PATCH 1/8] local toc with immediate parents, less in the global toc --- Doc/conf.py | 2 +- Doc/contents.rst | 1 + Doc/tools/templates/customlocaltoc.html | 24 ++++++++++++++++++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 Doc/tools/templates/customlocaltoc.html diff --git a/Doc/conf.py b/Doc/conf.py index e2dff74538a342..e84431aff331cb 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -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'], } diff --git a/Doc/contents.rst b/Doc/contents.rst index b57f4b09a5dcb6..95c0083c611f26 100644 --- a/Doc/contents.rst +++ b/Doc/contents.rst @@ -3,6 +3,7 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. toctree:: + :maxdepth: 2 whatsnew/index.rst tutorial/index.rst diff --git a/Doc/tools/templates/customlocaltoc.html b/Doc/tools/templates/customlocaltoc.html new file mode 100644 index 00000000000000..874617acb78845 --- /dev/null +++ b/Doc/tools/templates/customlocaltoc.html @@ -0,0 +1,24 @@ +{# + Customization of sphinx's basic/localtoc.html + + - Always display links to the parent pages within sections, + rather than link to the global contents + - +#} +
+
+{%- if parents %} +{%- for parent in parents %} + + + {{ parent.title }} + + +{%- endfor %} +{%- else %} +

{{ docstitle|e }}

+{%- endif %} +
+ {{ toc }} +
\ No newline at end of file From c1b2e99a207ce998096744dba8317982a9c3f086 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Wed, 28 Aug 2024 19:42:47 -0700 Subject: [PATCH 2/8] cleanup template comment --- Doc/tools/templates/customlocaltoc.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/tools/templates/customlocaltoc.html b/Doc/tools/templates/customlocaltoc.html index 874617acb78845..e6d9e343242aed 100644 --- a/Doc/tools/templates/customlocaltoc.html +++ b/Doc/tools/templates/customlocaltoc.html @@ -1,9 +1,9 @@ {# Customization of sphinx's basic/localtoc.html - - Always display links to the parent pages within sections, + - 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 #}
From a24f20acfc2594d9739c09ef69df8896dfccbb50 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Wed, 28 Aug 2024 19:47:47 -0700 Subject: [PATCH 3/8] tabs to spaces --- Doc/tools/templates/customlocaltoc.html | 32 ++++++++++++------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Doc/tools/templates/customlocaltoc.html b/Doc/tools/templates/customlocaltoc.html index e6d9e343242aed..c31ddf176663bd 100644 --- a/Doc/tools/templates/customlocaltoc.html +++ b/Doc/tools/templates/customlocaltoc.html @@ -1,24 +1,24 @@ {# - Customization of sphinx's basic/localtoc.html + 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 + - 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 #} -
-
+
+
{%- if parents %} {%- for parent in parents %} - - - {{ parent.title }} - - + + + {{ parent.title }} + + {%- endfor %} {%- else %} -

{{ docstitle|e }}

+

{{ docstitle|e }}

{%- endif %} -
- {{ toc }} -
\ No newline at end of file +
+ {{ toc }} +
\ No newline at end of file From cb1f06182d35f6e8710e90951b6d16c448123428 Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Thu, 29 Aug 2024 00:00:34 -0700 Subject: [PATCH 4/8] add title to global toc entry, make formatting match --- Doc/tools/templates/customlocaltoc.html | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Doc/tools/templates/customlocaltoc.html b/Doc/tools/templates/customlocaltoc.html index c31ddf176663bd..e93c185019801c 100644 --- a/Doc/tools/templates/customlocaltoc.html +++ b/Doc/tools/templates/customlocaltoc.html @@ -17,7 +17,12 @@ {%- endfor %} {%- else %} -

{{ docstitle|e }}

+

+ + {{ docstitle|e }} + +

{%- endif %}
{{ toc }} From d16545ed2f5a72ea3fdf570b198377d3f3512ab9 Mon Sep 17 00:00:00 2001 From: Jonny Saunders Date: Tue, 12 May 2026 10:16:12 -0700 Subject: [PATCH 5/8] Apply suggestion from @hugovk Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/tools/templates/customlocaltoc.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tools/templates/customlocaltoc.html b/Doc/tools/templates/customlocaltoc.html index e93c185019801c..e2633964788782 100644 --- a/Doc/tools/templates/customlocaltoc.html +++ b/Doc/tools/templates/customlocaltoc.html @@ -1,5 +1,5 @@ {# - Customization of sphinx's basic/localtoc.html + Customization of Sphinx's basic/localtoc.html - When present, display links to the parent pages within sections, rather than link to the global contents From 0df7ac80d23080ed039c73b63ef7e9906f75a60e Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 12 May 2026 17:02:49 -0700 Subject: [PATCH 6/8] newline --- Doc/tools/templates/customlocaltoc.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tools/templates/customlocaltoc.html b/Doc/tools/templates/customlocaltoc.html index e2633964788782..48f341c5affee9 100644 --- a/Doc/tools/templates/customlocaltoc.html +++ b/Doc/tools/templates/customlocaltoc.html @@ -26,4 +26,4 @@

{%- endif %}

{{ toc }} - \ No newline at end of file + From 0ad85a4ee2bb74b1c54d4a1381467776ca5cb5bc Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 12 May 2026 17:37:03 -0700 Subject: [PATCH 7/8] strip tags from link title, limit to the most proximal 4 parents. --- Doc/tools/templates/customlocaltoc.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/tools/templates/customlocaltoc.html b/Doc/tools/templates/customlocaltoc.html index 48f341c5affee9..91172fdd3389b2 100644 --- a/Doc/tools/templates/customlocaltoc.html +++ b/Doc/tools/templates/customlocaltoc.html @@ -8,10 +8,10 @@
{%- if parents %} -{%- for parent in parents %} +{%- for parent in parents[-4:] %} - + {{ parent.title }} From 573bfa1b07da65f5d7dd217fe7fc73732024a16d Mon Sep 17 00:00:00 2001 From: sneakers-the-rat Date: Tue, 12 May 2026 17:49:34 -0700 Subject: [PATCH 8/8] striptags from the global toc header to match, even though that should never be a problem --- Doc/tools/templates/customlocaltoc.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tools/templates/customlocaltoc.html b/Doc/tools/templates/customlocaltoc.html index 91172fdd3389b2..4e723ca6e79e61 100644 --- a/Doc/tools/templates/customlocaltoc.html +++ b/Doc/tools/templates/customlocaltoc.html @@ -19,7 +19,7 @@ {%- else %}

+ title="{{ docstitle|striptags }}"> {{ docstitle|e }}