local toc with immediate parents, less in the global toc

Author: sneakers-the-rat

Doc/conf.py

@@ -314,7 +314,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'],
 }
 

Doc/contents.rst

@@ -3,6 +3,7 @@
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 .. toctree::
+   :maxdepth: 2
 
    whatsnew/index.rst
    tutorial/index.rst

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
+	- 
+#}
+	<div>
+  	<div>
+{%- if parents %}
+{%- for parent in parents %}
+  		<h{{ loop.index0 + 3 }}>
+  			<a href="{{ parent.link|e }}" 
+  			   title="{{ parent.title }}">
+  			   {{ parent.title }}
+			  </a>
+			</h{{ loop.index0 + 3 }}>
+{%- endfor %}
+{%- else %}
+			<h3><a href="{{ pathto(root_doc)|e }}">{{ docstitle|e }}</a></h3>
+{%- endif %}
+  	</div>
+		{{ toc }}
+	</div>