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

Thu Jun 12 23:56:06 CEST 2008

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'])
 
