merge

doc/templating.rst

@@ -391,3 +391,6 @@ are in HTML form), these variables are also available:
 
    * ``titles_only`` (false by default): if true, put only toplevel document
      titles in the tree
+
+   * ``includehidden`` (false by default): if true, the TOC tree will also
+     contain hidden entries.

sphinx/builders/html.py

@@ -653,6 +653,8 @@ class StandaloneHTMLBuilder(Builder):
             self.indexer.feed(pagename, title, doctree)
 
     def _get_local_toctree(self, docname, collapse=True, **kwds):
+        if 'includehidden' not in kwds:
+            kwds['includehidden'] = False
         return self.render_partial(self.env.get_toctree_for(
             docname, self, collapse, **kwds))['fragment']
 

sphinx/environment.py

@@ -1340,46 +1340,56 @@ class BuildEnvironment:
         if toctree.get('hidden', False) and not includehidden:
             return None
 
-        def _walk_depth(node, depth, maxdepth):
+        # For reading the following two helper function, it is useful to keep
+        # in mind the node structure of a toctree (using HTML-like node names
+        # for brevity):
+        #
+        # <ul>
+        #   <li>
+        #     <p><a></p>
+        #     <p><a></p>
+        #     ...
+        #     <ul>
+        #       ...
+        #     </ul>
+        #   </li>
+        # </ul>
+        #
+        # The transformation is made in two passes in order to avoid
+        # interactions between marking and pruning the tree (see bug #1046).
+
+        def _toctree_prune(node, depth, maxdepth):
             """Utility: Cut a TOC at a specified depth."""
-
-            # For reading this function, it is useful to keep in mind the node
-            # structure of a toctree (using HTML-like node names for brevity):
-            #
-            # <ul>
-            #   <li>
-            #     <p><a></p>
-            #     <p><a></p>
-            #     ...
-            #     <ul>
-            #       ...
-            #     </ul>
-            #   </li>
-            # </ul>
-
             for subnode in node.children[:]:
                 if isinstance(subnode, (addnodes.compact_paragraph,
                                         nodes.list_item)):
-                    # for <p> and <li>, just indicate the depth level and
+                    # for <p> and <li>, just recurse
-                    # recurse to children
+                    _toctree_prune(subnode, depth, maxdepth)
-                    subnode['classes'].append('toctree-l%d' % (depth-1))
-                    _walk_depth(subnode, depth, maxdepth)
-
                 elif isinstance(subnode, nodes.bullet_list):
                     # for <ul>, determine if the depth is too large or if the
                     # entry is to be collapsed
                     if maxdepth > 0 and depth > maxdepth:
                         subnode.parent.replace(subnode, [])
                     else:
-                        # to find out what to collapse, *first* walk subitems,
-                        # since that determines which children point to the
-                        # current page
-                        _walk_depth(subnode, depth+1, maxdepth)
                         # cull sub-entries whose parents aren't 'current'
                         if (collapse and depth > 1 and
                             'iscurrent' not in subnode.parent):
                             subnode.parent.remove(subnode)
+                        else:
+                            # recurse on visible children  
+                            _toctree_prune(subnode, depth+1, maxdepth)
 
+        def _toctree_add_classes(node, depth):
+            """Add 'toctree-l%d' and 'current' classes to the toctree."""
+            for subnode in node.children:
+                if isinstance(subnode, (addnodes.compact_paragraph,
+                                        nodes.list_item)):
+                    # for <p> and <li>, indicate the depth level and recurse
+                    subnode['classes'].append('toctree-l%d' % (depth-1))
+                    _toctree_add_classes(subnode, depth)
+                elif isinstance(subnode, nodes.bullet_list):
+                    # for <ul>, just recurse
+                    _toctree_add_classes(subnode, depth+1)
                 elif isinstance(subnode, nodes.reference):
                     # for <a>, identify which entries point to the current
                     # document and therefore may not be collapsed
@@ -1500,8 +1510,9 @@ class BuildEnvironment:
         newnode = addnodes.compact_paragraph('', '', *tocentries)
         newnode['toctree'] = True
 
-        # prune the tree to maxdepth and replace titles, also set level classes
+        # prune the tree to maxdepth, also set toc depth and current classes
-        _walk_depth(newnode, 1, prune and maxdepth or 0)
+        _toctree_add_classes(newnode, 1)
+        _toctree_prune(newnode, 1, prune and maxdepth or 0)
 
         # set the target paths in the toctrees (they are not known at TOC
         # generation time)