From 35f0b555a437619c730f1fc7a8622922c5598db6 Mon Sep 17 00:00:00 2001
From: Georg Brandl <georg@python.org>
Date: Sun, 30 May 2010 13:16:26 +0200
Subject: [PATCH] The ``toctree`` callable in templates now accepts a
 ``titles_only`` keyword argument.

---
 CHANGES                             |  2 ++
 doc/templating.rst                  |  3 +++
 sphinx/builders/html.py             |  4 ++--
 sphinx/environment.py               | 11 +++++++----
 tests/root/_templates/customsb.html |  2 ++
 5 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/CHANGES b/CHANGES
index 300f5fe28..38a810593 100644
--- a/CHANGES
+++ b/CHANGES
@@ -107,6 +107,8 @@ Features added
   - Added new theme ``scrolls``, created by Armin Ronacher.
   - #193: Added a ``visitedlinkcolor`` theme option to the default
     theme.
+  - The ``toctree`` callable in templates now accepts a ``titles_only``
+    keyword argument.
 
 * Extension API:
 
diff --git a/doc/templating.rst b/doc/templating.rst
index 5bf09dbde..507e570f2 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -384,3 +384,6 @@ are in HTML form), these variables are also available:
 
    * ``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
+
+   * ``titles_only`` (false by default): if true, put only toplevel document
+     titles in the tree
diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py
index 2b73885ee..0e23c8a4e 100644
--- a/sphinx/builders/html.py
+++ b/sphinx/builders/html.py
@@ -637,9 +637,9 @@ 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, maxdepth=0):
+    def _get_local_toctree(self, docname, collapse=True, **kwds):
         return self.render_partial(self.env.get_toctree_for(
-            docname, self, collapse))['fragment']
+            docname, self, collapse, **kwds))['fragment']
 
     def get_outfilename(self, pagename):
         return path.join(self.outdir, os_path(pagename) + self.out_suffix)
diff --git a/sphinx/environment.py b/sphinx/environment.py
index c8b3f018c..d5697943f 100644
--- a/sphinx/environment.py
+++ b/sphinx/environment.py
@@ -1033,15 +1033,18 @@ class BuildEnvironment:
             node['refuri'] = node['anchorname'] or '#'
         return toc
 
-    def get_toctree_for(self, docname, builder, collapse, maxdepth=0):
+    def get_toctree_for(self, docname, builder, collapse, **kwds):
         """Return the global TOC nodetree."""
         doctree = self.get_doctree(self.config.master_doc)
         toctrees = []
+        if 'includehidden' not in kwds:
+            kwds['includehidden'] = True
+        if 'maxdepth' not in kwds:
+            kwds['maxdepth'] = 0
+        kwds['collapse'] = collapse
         for toctreenode in doctree.traverse(addnodes.toctree):
             toctree = self.resolve_toctree(docname, builder, toctreenode,
-                                           prune=True, collapse=collapse,
-                                           maxdepth=maxdepth,
-                                           includehidden=True)
+                                           prune=True, **kwds)
             toctrees.append(toctree)
         if not toctrees:
             return None
diff --git a/tests/root/_templates/customsb.html b/tests/root/_templates/customsb.html
index cc88b8cfb..0cd6735a2 100644
--- a/tests/root/_templates/customsb.html
+++ b/tests/root/_templates/customsb.html
@@ -1,2 +1,4 @@
 {# custom sidebar template #}
 <h4>Custom sidebar</h4>
+
+{{ toctree(titles_only=True, maxdepth=1) }}