refs #1700: now toctree caption become paragraph block instead of Text under ul element. and add permalink for toctree caption.

CHANGES

@@ -77,6 +77,7 @@ Features added
 
 * #1227: Add `html_scaled_image_link` config option to conf.py, to control
   scaled image link.
+* #1700: Add `:caption:` option for `toctree`.
 
 Bugs fixed
 ----------

doc/markup/toctree.rst

@@ -85,6 +85,13 @@ tables of contents.  The ``toctree`` directive is the central element.
 
    **Additional options**
 
+   You can use ``caption`` option to provide toctree caption::
+
+      .. toctree::
+         :caption: Table of Contents
+
+         foo
+
    If you want only the titles of documents in the tree to show up, not other
    headings of the same level, you can use the ``titlesonly`` option::
 
@@ -168,6 +175,9 @@ tables of contents.  The ``toctree`` directive is the central element.
    .. versionchanged:: 1.2
       Added "includehidden" option.
 
+   .. versionchanged:: 1.3
+      Added "caption" option.
+
 Special names
 -------------
 

sphinx/directives/other.py

@@ -53,6 +53,8 @@ class TocTree(Directive):
         suffixes = env.config.source_suffix
         glob = 'glob' in self.options
         caption = self.options.get('caption')
+        if caption:
+            self.options['name'] = nodes.fully_normalize_name(caption)
 
         ret = []
         # (title, ref) pairs, where ref may be a document, or an external link,
@@ -120,6 +122,7 @@ class TocTree(Directive):
         set_source_info(self, subnode)
         wrappernode = nodes.compound(classes=['toctree-wrapper'])
         wrappernode.append(subnode)
+        self.add_name(wrappernode)
         ret.append(wrappernode)
         return ret
 

sphinx/environment.py

@@ -1380,15 +1380,7 @@ class BuildEnvironment:
                                   separate=False, subtree=False):
             """Return TOC entries for a toctree node."""
             refs = [(e[0], e[1]) for e in toctreenode['entries']]
-            caption = toctreenode.attributes.get('caption')
             entries = []
-            if caption:
-                entries.extend(
-                        nodes.reference('', '', internal=False,
-                                                    refuri='', anchorname='',
-                                                    *[nodes.Text(caption)])
-                )
-
             for (title, ref) in refs:
                 try:
                     refdoc = None
@@ -1489,7 +1481,11 @@ class BuildEnvironment:
         if not tocentries:
             return None
 
-        newnode = addnodes.compact_paragraph('', '', *tocentries)
+        newnode = addnodes.compact_paragraph('', '')
+        caption = toctree.attributes.get('caption')
+        if caption:
+            newnode += nodes.caption(caption, '', *[nodes.Text(caption)])
+        newnode.extend(tocentries)
         newnode['toctree'] = True
 
         # prune the tree to maxdepth, also set toc depth and current classes

sphinx/writers/html.py

@@ -334,6 +334,8 @@ class HTMLTranslator(BaseTranslator):
             self.add_permalink_ref(node.parent, _('Permalink to this code'))
         elif isinstance(node.parent, nodes.figure):
             self.add_permalink_ref(node.parent, _('Permalink to this image'))
+        elif node.parent.get('toctree'):
+            self.add_permalink_ref(node.parent.parent, _('Permalink to this toctree'))
 
         if isinstance(node.parent, nodes.container) and node.parent.get('literal_block'):
             self.body.append('</div>\n')