Added `titlesonly option to toctree` directive.

CHANGES

@@ -1,6 +1,8 @@
 Release 1.0 (in development)
 ============================
 
+* Added ``titlesonly`` option to ``toctree`` directive.
+
 * Removed the deprecated ``sphinx.builder`` module.
 
 * #193: Added a ``visitedlinkcolor`` theme option to the default

doc/concepts.rst

@@ -89,6 +89,15 @@ tables of contents.  The ``toctree`` directive is the central element.
    Numbering then starts at the heading of ``foo``.  Sub-toctrees are
    automatically numbered (don't give the ``numbered`` flag to those).
 
+   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::
+
+      .. toctree::
+         :titlesonly:
+
+         foo
+         bar
+
    You can use "globbing" in toctree directives, by giving the ``glob`` flag
    option.  All entries are then matched against the list of available
    documents, and matches are inserted into the list alphabetically.  Example::
@@ -139,6 +148,9 @@ tables of contents.  The ``toctree`` directive is the central element.
       Added "numbered" and "hidden" options as well as external links and
       support for "self" references.
 
+   .. versionchanged:: 1.0
+      Added "titlesonly" option.
+
 
 Special names
 -------------

sphinx/directives/other.py

@@ -33,6 +33,7 @@ class TocTree(Directive):
         'glob': directives.flag,
         'hidden': directives.flag,
         'numbered': directives.flag,
+        'titlesonly': directives.flag,
     }
 
     def run(self):
@@ -97,6 +98,7 @@ class TocTree(Directive):
         subnode['glob'] = glob
         subnode['hidden'] = 'hidden' in self.options
         subnode['numbered'] = 'numbered' in self.options
+        subnode['titlesonly'] = 'titlesonly' in self.options
         ret.append(subnode)
         return ret
 

sphinx/environment.py

@@ -1132,6 +1132,8 @@ class BuildEnvironment:
             return entries
 
         maxdepth = maxdepth or toctree.get('maxdepth', -1)
+        if not titles_only and toctree.get('titlesonly', False):
+            titles_only = True
 
         # NOTE: previously, this was separate=True, but that leads to artificial
         # separation when two or more toctree entries form a logical unit, so