Merge pull request #1700 from ericholscher/toctree-name

Add initial ability to name a TOC Tree

sphinx/directives/other.py

@@ -40,6 +40,7 @@ class TocTree(Directive):
     final_argument_whitespace = False
     option_spec = {
         'maxdepth': int,
+        'name': str,
         'glob': directives.flag,
         'hidden': directives.flag,
         'includehidden': directives.flag,
@@ -51,6 +52,7 @@ class TocTree(Directive):
         env = self.state.document.settings.env
         suffixes = env.config.source_suffix
         glob = 'glob' in self.options
+        name = self.options.get('name')
 
         ret = []
         # (title, ref) pairs, where ref may be a document, or an external link,
@@ -109,6 +111,7 @@ class TocTree(Directive):
         # includefiles only entries that are documents
         subnode['includefiles'] = includefiles
         subnode['maxdepth'] = self.options.get('maxdepth', -1)
+        subnode['name'] = name
         subnode['glob'] = glob
         subnode['hidden'] = 'hidden' in self.options
         subnode['includehidden'] = 'includehidden' in self.options

sphinx/environment.py

@@ -1380,7 +1380,15 @@ class BuildEnvironment:
                                   separate=False, subtree=False):
             """Return TOC entries for a toctree node."""
             refs = [(e[0], e[1]) for e in toctreenode['entries']]
+            name = toctreenode.attributes.get('name')
             entries = []
+            if name:
+                entries.extend(
+                        nodes.reference('', '', internal=False,
+                                                    refuri='', anchorname='',
+                                                    *[nodes.Text(name)])
+                )
+
             for (title, ref) in refs:
                 try:
                     refdoc = None