diff --git a/CHANGES b/CHANGES index a4e45e808..7c153091b 100644 --- a/CHANGES +++ b/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 diff --git a/doc/concepts.rst b/doc/concepts.rst index ca7aaf7c4..379888ffc 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -85,6 +85,18 @@ tables of contents. The ``toctree`` directive is the central element. This includes first all documents whose names start with ``intro``, then all 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 @@ -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 ------------- diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index b63d139c8..6262531e8 100644 --- a/sphinx/directives/other.py +++ b/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) diff --git a/sphinx/environment.py b/sphinx/environment.py index 826fe8faa..10d88cb78 100644 --- a/sphinx/environment.py +++ b/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."""