Add includehidden option to the toctree directive

This option is equivalent to the includehidden option of the template function
toctree() and allows to restore to the toctree behaviour prior to version 1.1.
See also bug #790.

CHANGES

@@ -1,6 +1,11 @@
 Release 1.2 (in development)
 ============================
 
+* The :rst:dir:`toctree` directive and the ``toctree()`` template function now
+  have an ``includehidden`` option that includes hidden toctree entries (bugs
+  #790 and #1047). A bug in the ``maxdepth`` option for the ``toctree()``
+  template function has been fixed (bug #1046).
+
 * PR#99: Strip down seealso directives to normal admonitions.  This removes
   their unusual CSS classes (admonition-see-also), inconsistent LaTeX
   admonition title ("See Also" instead of "See also"), and spurious indentation

doc/markup/toctree.rst

@@ -126,6 +126,18 @@ tables of contents.  The ``toctree`` directive is the central element.
    intend to insert these links yourself, in a different style, or in the HTML
    sidebar.
 
+   In cases where you want to have only one top-level toctree and hide all other
+   lower level toctrees you can add the "includehidden" option to the top-level
+   toctree entry::
+
+      .. toctree::
+         :includehidden:
+
+         doc_1
+         doc_2
+
+   All other toctree entries can then be eliminated by the "hidden" option.
+
    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
@@ -150,6 +162,8 @@ tables of contents.  The ``toctree`` directive is the central element.
    .. versionchanged:: 1.1
       Added numeric argument to "numbered".
 
+   .. versionchanged:: 1.2
+      Added "includehidden" option.
 
 Special names
 -------------

sphinx/directives/other.py

@@ -43,6 +43,7 @@ class TocTree(Directive):
         'maxdepth': int,
         'glob': directives.flag,
         'hidden': directives.flag,
+        'includehidden': directives.flag,
         'numbered': int_or_nothing,
         'titlesonly': directives.flag,
     }
@@ -108,6 +109,7 @@ class TocTree(Directive):
         subnode['maxdepth'] = self.options.get('maxdepth', -1)
         subnode['glob'] = glob
         subnode['hidden'] = 'hidden' in self.options
+        subnode['includehidden'] = 'includehidden' in self.options
         subnode['numbered'] = self.options.get('numbered', 0)
         subnode['titlesonly'] = 'titlesonly' in self.options
         set_source_info(self, subnode)

sphinx/environment.py

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