Allow new titles in the toctree.

CHANGES

@@ -5,6 +5,9 @@ Changes in trunk
   It works like ``add_description_unit`` but the directive will only
   create a target and no output.
 
+* sphinx.directives: Allow giving a different title to documents
+  in the toctree.
+
 
 Release 0.1.61950 (Mar 26, 2008)
 ================================

doc/concepts.rst

@@ -56,9 +56,24 @@ tables of contents.  The ``toctree`` directive is the central element.
      document, the library index.  From this information it generates "next
      chapter", "previous chapter" and "parent chapter" links.
      
+   Document titles in the :dir:`toctree` will be automatically read from the
+   title of the referenced document. If that isn't what you want, you can give
+   the specify an explicit title and target using a similar syntax to reST
+   hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
+   looks like::
+   
+       .. toctree::
+          
+          intro
+          All about strings <strings>
+          datatypes
+          
+   The second line above will link to the ``strings`` document, but will use the
+   title "All about strings" instead of the title of the ``strings`` document.
+          
    In the end, all documents under the :term:`documentation root` must occur in
-   one ``toctree`` directive; Sphinx will emit a warning if it finds a file that
-   is not included, because that means that this file will not be reachable
+   some ``toctree`` directive; Sphinx will emit a warning if it finds a file
+   that is not included, because that means that this file will not be reachable
    through standard navigation.  Use :confval:`unused_documents` to explicitly
    exclude documents from this check.
 

doc/contents.rst

@@ -4,10 +4,10 @@ Sphinx documentation contents
 =============================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    intro
-   concepts
+   Konzepte <concepts>
    rest
    markup/index
    builders

sphinx/directives.py

@@ -19,6 +19,7 @@ from docutils import nodes
 from docutils.parsers.rst import directives
 
 from sphinx import addnodes
+from sphinx.roles import caption_ref_re
 from sphinx.util.compat import make_admonition
 
 ws_re = re.compile(r'\s+')
@@ -622,9 +623,15 @@ def toctree_directive(name, arguments, options, content, lineno,
     ret = []
     subnode = addnodes.toctree()
     includefiles = []
+    includetitles = {}
     for docname in content:
         if not docname:
             continue
+        # look for explicit titles and documents ("Some Title <document>").
+        m = caption_ref_re.match(docname)
+        if m:
+            docname = m.group(2)
+            includetitles[docname] = m.group(1)    
         # absolutize filenames, remove suffixes
         if docname.endswith(suffix):
             docname = docname[:-len(suffix)]
@@ -635,6 +642,7 @@ def toctree_directive(name, arguments, options, content, lineno,
         else:
             includefiles.append(docname)
     subnode['includefiles'] = includefiles
+    subnode['includetitles'] = includetitles
     subnode['maxdepth'] = options.get('maxdepth', -1)
     ret.append(subnode)
     return ret

sphinx/environment.py

@@ -60,18 +60,6 @@ default_settings = {
 ENV_VERSION = 21
 
 
-def walk_depth(node, depth, maxdepth):
-    """Utility: Cut a TOC at a specified depth."""
-    for subnode in node.children[:]:
-        if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)):
-            walk_depth(subnode, depth, maxdepth)
-        elif isinstance(subnode, nodes.bullet_list):
-            if depth > maxdepth:
-                subnode.parent.replace(subnode, [])
-            else:
-                walk_depth(subnode, depth+1, maxdepth)
-
-
 default_substitutions = set([
     'version',
     'release',
@@ -736,13 +724,33 @@ class BuildEnvironment:
                 return addnodes.compact_paragraph('', '', *entries)
             return None
 
+        def _walk_depth(node, depth, maxdepth, titleoverrides):
+            """Utility: Cut a TOC at a specified depth."""
+            for subnode in node.children[:]:
+                if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)):
+                    _walk_depth(subnode, depth, maxdepth, titleoverrides)
+                elif isinstance(subnode, nodes.bullet_list):
+                    if depth > maxdepth:
+                        subnode.parent.replace(subnode, [])
+                    else:
+                        _walk_depth(subnode, depth+1, maxdepth, titleoverrides)
+
         for toctreenode in doctree.traverse(addnodes.toctree):
             maxdepth = toctreenode.get('maxdepth', -1)
+            titleoverrides = toctreenode.get('includetitles', {})
             newnode = _entries_from_toctree(toctreenode)
             if newnode is not None:
-                # prune the tree to maxdepth
+                # prune the tree to maxdepth and replace titles
                 if maxdepth > 0:
-                    walk_depth(newnode, 1, maxdepth)
+                    _walk_depth(newnode, 1, maxdepth, titleoverrides)
+                # replace titles, if needed
+                if titleoverrides:
+                    for refnode in newnode.traverse(nodes.reference):
+                        if refnode.get('anchorname', None):
+                            continue
+                        if refnode['refuri'] in titleoverrides:
+                            newtitle = titleoverrides[refnode['refuri']]
+                            refnode.children = [nodes.Text(newtitle)]
                 toctreenode.replace_self(newnode)
             else:
                 toctreenode.replace_self([])