Add maxdepth for TOCs.

CHANGES

@@ -38,6 +38,9 @@ New features added
 
 * Added TextBuilder to create plain-text output.
 
+* ``tocdepth`` can be given as a file-wide metadata entry, and specifies
+  the maximum depth of a TOC of this file.
+
 Bugs fixed
 ----------
 

doc/changes.rst

@@ -1,3 +1,5 @@
+:tocdepth: 2
+
 .. _changes:
 
 Changes in Sphinx

doc/markup/misc.rst

@@ -16,7 +16,12 @@ normal documents can be used to record the author, date of publication and
 other metadata.  In Sphinx, the docinfo is used as metadata, too, but not
 displayed in the output.
 
-At the moment, only one metadata field is recognized:
+At the moment, these metadata fields are recognized:
+
+``tocdepth``
+   The maximum depth for a table of contents of this file.
+
+   .. versionadded:: 0.4
 
 ``nocomments``
    If set, the web application won't display a comment form for a page generated

sphinx/environment.py

@@ -605,7 +605,12 @@ class BuildEnvironment:
         """Build a TOC from the doctree and store it in the inventory."""
         numentries = [0] # nonlocal again...
 
-        def build_toc(node):
+        try:
+            maxdepth = int(self.metadata[docname].get('tocdepth', 0))
+        except ValueError:
+            maxdepth = 0
+
+        def build_toc(node, depth=1):
             entries = []
             for subnode in node:
                 if isinstance(subnode, addnodes.toctree):
@@ -636,7 +641,8 @@ class BuildEnvironment:
                                             *nodetext)
                 para = addnodes.compact_paragraph('', '', reference)
                 item = nodes.list_item('', para)
-                item += build_toc(subnode)
+                if maxdepth == 0 or depth < maxdepth:
+                    item += build_toc(subnode, depth+1)
                 entries.append(item)
             if entries:
                 return nodes.bullet_list('', *entries)
@@ -749,7 +755,7 @@ class BuildEnvironment:
                     else:
                         _walk_depth(subnode, depth+1, maxdepth, titleoverrides)
 
-       def _entries_from_toctree(toctreenode, separate=False):
+        def _entries_from_toctree(toctreenode, separate=False):
             """Return TOC entries for a toctree node."""
             includefiles = map(str, toctreenode['includefiles'])