Close #7902: html theme: Add a new option globaltoc_maxdepth

CHANGES

@@ -19,6 +19,8 @@ Features added
 * #7888: napoleon: Add aliases Warn and Raise.
 * C, added :rst:dir:`c:alias` directive for inserting copies
   of existing declarations.
+* #7902: html theme: Add a new option :confval:`globaltoc_maxdepth` to control
+  the behavior of globaltoc in sidebar
 * #7052: add ``:noindexentry:`` to the Python, C, C++, and Javascript domains.
   Update the documentation to better reflect the relationship between this option
   and the ``:noindex:`` option.

doc/usage/theming.rst

@@ -172,6 +172,12 @@ These themes are:
 
     .. versionadded:: 3.1
 
+  - **globaltoc_maxdepth** (int): The maximum depth of the toctree in
+    ``globaltoc.html`` (see :confval:`html_sidebars`).  Set it to -1 to allow
+    unlimited depth. Defaults to the max depth selected in the toctree directive.
+
+    .. versionadded:: 3.2
+
 **alabaster**
   `Alabaster theme`_ is a modified "Kr" Sphinx theme from @kennethreitz
   (especially as used in his Requests project), which was itself originally

sphinx/builders/html/__init__.py

@@ -886,6 +886,8 @@ def index_page(self, pagename: str, doctree: nodes.document, title: str) -> None
     def _get_local_toctree(self, docname: str, collapse: bool = True, **kwargs: Any) -> str:
         if 'includehidden' not in kwargs:
             kwargs['includehidden'] = False
+        if kwargs.get('maxdepth') == '':
+            kwargs.pop('maxdepth')
         return self.render_partial(TocTree(self.env).get_toctree_for(
             docname, self, collapse, **kwargs))['fragment']
 

sphinx/themes/basic/globaltoc.html

@@ -8,4 +8,4 @@
     :license: BSD, see LICENSE for details.
 #}
 <h3><a href="{{ pathto(master_doc)|e }}">{{ _('Table of Contents') }}</a></h3>
-{{ toctree(includehidden=theme_globaltoc_includehidden, collapse=theme_globaltoc_collapse) }}
+{{ toctree(includehidden=theme_globaltoc_includehidden, collapse=theme_globaltoc_collapse, maxdepth=theme_globaltoc_maxdepth) }}

sphinx/themes/basic/theme.conf

@@ -12,3 +12,4 @@ body_max_width = 800
 navigation_with_keys = False
 globaltoc_collapse = true
 globaltoc_includehidden = false
+globaltoc_maxdepth =