From 1639f5972688dda9a90c7fcea5780d5718d52967 Mon Sep 17 00:00:00 2001
From: Roland Meister <Roland Meister@localhost>
Date: Sun, 6 Jan 2013 14:55:35 +0100
Subject: [PATCH] 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                    |  5 +++++
 doc/markup/toctree.rst     | 14 ++++++++++++++
 sphinx/directives/other.py |  2 ++
 sphinx/environment.py      |  2 ++
 4 files changed, 23 insertions(+)

diff --git a/CHANGES b/CHANGES
index d7ec12a3a..df649c937 100644
--- a/CHANGES
+++ b/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
diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index 625fbb611..fe27e019d 100644
--- a/doc/markup/toctree.rst
+++ b/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
 -------------
diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py
index 3167d606f..75a199159 100644
--- a/sphinx/directives/other.py
+++ b/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)
diff --git a/sphinx/environment.py b/sphinx/environment.py
index 2ce1a6fc1..e7b8eb77f 100644
--- a/sphinx/environment.py
+++ b/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