The `toctree() callable in templates now has a maxdepth`

keyword argument to control the depth of the generated tree.

Also add tests for that callable.

CHANGES

@@ -1,6 +1,9 @@
 Release 1.0 (in development)
 ============================
 
+* The ``toctree()`` callable in templates now has a ``maxdepth``
+  keyword argument to control the depth of the generated tree.
+
 * Added Catalan translation, thanks to Pau Fernández.
 
 * Added new minimal theme called scrolls.

doc/templating.rst

@@ -364,5 +364,10 @@ are in HTML form), these variables are also available:
 .. data:: toctree
 
    A callable yielding the global TOC tree containing the current page, rendered
-   as HTML bullet lists.  If the optional keyword argument ``collapse`` is true,
-   all TOC entries that are not ancestors of the current page are collapsed.
+   as HTML bullet lists.  Optional keyword arguments:
+
+   * ``collapse`` (true by default): if true, all TOC entries that are not
+     ancestors of the current page are collapsed
+
+   * ``maxdepth`` (defaults to the max depth selected in the toctree directive):
+     the maximum depth of the tree; set it to ``-1`` to allow unlimited depth

sphinx/builders/html.py

@@ -644,7 +644,7 @@ class StandaloneHTMLBuilder(Builder):
         if self.indexer is not None and title:
             self.indexer.feed(pagename, title, doctree)
 
-    def _get_local_toctree(self, docname, collapse=True):
+    def _get_local_toctree(self, docname, collapse=True, maxdepth=0):
         return self.render_partial(self.env.get_toctree_for(
             docname, self, collapse))['fragment']
 

sphinx/environment.py

@@ -1007,12 +1007,13 @@ class BuildEnvironment:
             node['refuri'] = node['anchorname']
         return toc
 
-    def get_toctree_for(self, docname, builder, collapse):
+    def get_toctree_for(self, docname, builder, collapse, maxdepth=0):
         """Return the global TOC nodetree."""
         doctree = self.get_doctree(self.config.master_doc)
         for toctreenode in doctree.traverse(addnodes.toctree):
             result = self.resolve_toctree(docname, builder, toctreenode,
-                                          prune=True, collapse=collapse)
+                                          prune=True, collapse=collapse,
+                                          maxdepth=maxdepth)
             if result is not None:
                 return result
 

tests/root/_templates/layout.html

@@ -1,5 +1,12 @@
 {% extends "!layout.html" %}
+
 {% block extrahead %}
 <meta name="hc" content="{{ hckey }}" />
 {{ super() }}
 {% endblock %}
+
+{% block sidebartoc %}
+{# display global TOC in addition to local TOC #}
+{{ super() }}
+{{ toctree(collapse=False, maxdepth=-1) }}
+{% endblock %}

tests/root/objects.txt

@@ -1,5 +1,5 @@
-Testing description units
-=========================
+Testing object descriptions
+===========================
 
 .. function:: func_without_module(a, b, *c[, d])
 

tests/test_build_html.py

@@ -138,6 +138,11 @@ HTML_XPATH = {
         ".//a[@href='#SPHINX_USE_PYTHON']": '',
         ".//a[@href='#SphinxType']": '',
         ".//a[@href='#sphinx_global']": '',
+        # test global TOC created by toctree()
+        ".//ul[@class='current']/li[@class='toctree-l1 current']/a[@href='']":
+            'Testing object descriptions',
+        ".//li[@class='toctree-l1']/a[@href='markup.html']":
+            'Testing various markup',
     },
     'contents.html': {
         ".//meta[@name='hc'][@content='hcval']": '',