1. Georg Brandl
  2. sphinx


Jon Waltman  committed d221965 Merge

Merged in rolmei/sphinx-epub (pull request #106: Add includehidden option to the toctree directive)

  • Participants
  • Parent commits 5d9d54f, 5b155ec
  • Branches default

Comments (0)

Files changed (4)


View file
   Previously, if these values were not set, no output would be genereted by
   their respective builders.
+* 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

File doc/markup/toctree.rst

View file
    intend to insert these links yourself, in a different style, or in the HTML
+   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
    .. versionchanged:: 1.1
       Added numeric argument to "numbered".
+   .. versionchanged:: 1.2
+      Added "includehidden" option.
 Special names

File sphinx/directives/other.py

View file
         'maxdepth': int,
         'glob': directives.flag,
         'hidden': directives.flag,
+        'includehidden': directives.flag,
         'numbered': int_or_nothing,
         'titlesonly': directives.flag,
         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)

File sphinx/environment.py

View file
         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