The `toctree directive now supports a :hidden:` flag,

which will prevent links from being generated in place of
the directive -- this allows you to define your document
structure, but place the links yourself.

CHANGES

@@ -15,6 +15,13 @@ New features added
        if name.startswith('_'):
            return True
 
+* Markup:
+
+  - The ``toctree`` directive now supports a ``:hidden:`` flag,
+    which will prevent links from being generated in place of
+    the directive -- this allows you to define your document
+    structure, but place the links yourself.
+
 * Configuration:
 
   - The new ``html_add_permalinks`` config value can be used to

doc/concepts.rst

@@ -86,6 +86,18 @@ tables of contents.  The ``toctree`` directive is the central element.
    documents in the ``recipe`` folder, then all remaining documents (except the
    one containing the directive, of course.) [#]_
 
+   You can also give a "hidden" option to the directive, like this::
+
+      .. toctree::
+         :hidden:
+
+         doc_1
+         doc_2
+
+   This will still notify Sphinx of the document hierarchy, but not insert links
+   into the document at the location of the directive -- this makes sense if you
+   intend to insert these links yourself, in a different style.
+          
    In the end, all documents in the :term:`source directory` (or subdirectories)
    must occur in 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
@@ -100,6 +112,9 @@ tables of contents.  The ``toctree`` directive is the central element.
    .. versionchanged:: 0.3
       Added "globbing" option.
 
+   .. versionchanged:: 0.6
+      Added "hidden" option.
+
 
 Special names
 -------------

sphinx/directives/other.py

@@ -29,7 +29,6 @@ def toctree_directive(name, arguments, options, content, lineno,
     glob = 'glob' in options
 
     ret = []
-    subnode = addnodes.toctree()
     includefiles = []
     includetitles = {}
     all_docnames = env.found_docs.copy()
@@ -66,15 +65,18 @@ def toctree_directive(name, arguments, options, content, lineno,
                 ret.append(state.document.reporter.warning(
                     'toctree glob pattern %r didn\'t match any documents' % entry,
                     line=lineno))
+    subnode = addnodes.toctree()
     subnode['includefiles'] = includefiles
     subnode['includetitles'] = includetitles
     subnode['maxdepth'] = options.get('maxdepth', -1)
     subnode['glob'] = glob
+    subnode['hidden'] = 'hidden' in options
     ret.append(subnode)
     return ret
 
 toctree_directive.content = 1
-toctree_directive.options = {'maxdepth': int, 'glob': directives.flag}
+toctree_directive.options = {'maxdepth': int, 'glob': directives.flag,
+                             'hidden': directives.flag}
 directives.register_directive('toctree', toctree_directive)
 
 

sphinx/environment.py

@@ -902,6 +902,8 @@ class BuildEnvironment:
         If *titles_only* is True, only toplevel document titles will be in the
         resulting tree.
         """
+        if toctree.get('hidden', False):
+            return None
 
         def _walk_depth(node, depth, maxdepth, titleoverrides):
             """Utility: Cut a TOC at a specified depth."""