[Python-checkins] r64200 - in doctools/trunk: CHANGES doc/changes.rst doc/markup/misc.rst sphinx/environment.py

[georg.brandl]

Author: georg.brandl
Date: Thu Jun 12 23:56:06 2008
New Revision: 64200

Log:
Add maxdepth for TOCs.


Modified:
   doctools/trunk/CHANGES
   doctools/trunk/doc/changes.rst
   doctools/trunk/doc/markup/misc.rst
   doctools/trunk/sphinx/environment.py

Modified: doctools/trunk/CHANGES
==============================================================================
--- doctools/trunk/CHANGES	(original)
+++ doctools/trunk/CHANGES	Thu Jun 12 23:56:06 2008
@@ -38,6 +38,9 @@
 
 * 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
 ----------
 

Modified: doctools/trunk/doc/changes.rst
==============================================================================
--- doctools/trunk/doc/changes.rst	(original)
+++ doctools/trunk/doc/changes.rst	Thu Jun 12 23:56:06 2008
@@ -1,3 +1,5 @@
+:tocdepth: 2
+
 .. _changes:
 
 Changes in Sphinx

Modified: doctools/trunk/doc/markup/misc.rst
==============================================================================
--- doctools/trunk/doc/markup/misc.rst	(original)
+++ doctools/trunk/doc/markup/misc.rst	Thu Jun 12 23:56:06 2008
@@ -16,7 +16,12 @@
 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

Modified: doctools/trunk/sphinx/environment.py
==============================================================================
--- doctools/trunk/sphinx/environment.py	(original)
+++ doctools/trunk/sphinx/environment.py	Thu Jun 12 23:56:06 2008
@@ -605,7 +605,12 @@
         """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 @@
                                             *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 @@
                     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'])