sphinx-gallery
diff --git a/‎doc/configuration.rst
Copy file name to clipboardExpand all lines: doc/configuration.rst
+8-5Lines changed: 8 additions & 5 deletions b/‎doc/configuration.rst
Copy file name to clipboardExpand all lines: doc/configuration.rst
+8-5Lines changed: 8 additions & 5 deletions
diff --git a/‎sphinx_gallery/gen_gallery.py
Copy file name to clipboardExpand all lines: sphinx_gallery/gen_gallery.py
+26-21Lines changed: 26 additions & 21 deletions b/‎sphinx_gallery/gen_gallery.py
Copy file name to clipboardExpand all lines: sphinx_gallery/gen_gallery.py
+26-21Lines changed: 26 additions & 21 deletions
diff --git a/‎sphinx_gallery/tests/test_full.py
Copy file name to clipboardExpand all lines: sphinx_gallery/tests/test_full.py
+2-1Lines changed: 2 additions & 1 deletion b/‎sphinx_gallery/tests/test_full.py
Copy file name to clipboardExpand all lines: sphinx_gallery/tests/test_full.py
+2-1Lines changed: 2 additions & 1 deletion
@@ -1898,11 +1898,14 @@ in your document.  You can, of course, add a ``toctree`` to your
 Manually passing ``index.rst``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you want control over the gallery (or subgallery) ``index.rst``, you
-can bypass Sphinx-Gallery creating it from ``README.txt`` by including
-it in the gallery-source instead of the README.  If you do this, you are
-responsible for building your own ``toctree`` in that index or elsewhere
-that includes the gallery items.
+You can bypass Sphinx-Gallery automatically creating an index ``index.rst``
+from a ``README.txt`` in a gallery directory or subdirectory. If your
+``copyfile_regex`` includes ``index.rst``, and you have an ``index.rst`` in the
+gallery-source instead of the README, Sphinx-Gallery will use that instead of
+the index it automatically makes.  If you do this, you are responsible for
+adding your own Sphinx ``toctree`` in that index (or elsewhere in your Sphinx
+documentation) that includes any gallery items or other files in that
+directory.
 
 .. _show_api_usage:
 
 
@@ -457,6 +457,24 @@ def _prepare_sphx_glr_dirs(gallery_conf, srcdir):
     return list(zip(examples_dirs, gallery_dirs))
 
 
+def _format_toctree(items, includehidden=False):
+    """Format a toc tree"""
+
+    st = """
+.. toctree::
+   :hidden:
+"""
+    if includehidden:
+        st += """
+   :includehidden:
+"""
+    st += """
+
+   %s\n""" % "\n   ".join(items)
+
+    return st
+
+
 def generate_gallery_rst(app):
     """Generate the Main examples gallery reStructuredText
 
@@ -519,21 +537,18 @@ def generate_gallery_rst(app):
         # (this will overwrite the rst file generated by the previous call
         # to generate_dir_rst)
 
-        # :orphan: to suppress "not included in TOCTREE" sphinx
-        # warnings
         if this_content:
+            # :orphan: to suppress "not included in TOCTREE" sphinx warnings
             indexst = ":orphan:\n\n" + this_content
         else:
+            # we are not going to use the index.rst.new that gets made here,
+            # but go through the motions to run through all the subsections...
             indexst = 'Never used!'
 
         # Write toctree with gallery items from gallery root folder
         if len(this_toctree_items) > 0:
-            this_toctree = """
-.. toctree::
-   :hidden:
+            this_toctree = _format_toctree(this_toctree_items)
 
-   %s\n
-""" % "\n   ".join(this_toctree_items)
         indexst += this_toctree
 
         # list all paths to subsection index files in this array
@@ -575,12 +590,8 @@ def generate_gallery_rst(app):
             # toctree filenames were generated for the subsection.
             if not gallery_conf["nested_sections"]:
                 if len(subsection_toctree_filenames) > 0:
-                    subsection_index_toctree = """
-.. toctree::
-   :hidden:
-
-   %s\n
-""" % "\n   ".join(subsection_toctree_filenames)
+                    subsection_index_toctree = _format_toctree(
+                        subsection_toctree_filenames)
                     indexst += subsection_index_toctree
             # Otherwise, a new index.rst.new file should
             # have been created and it needs to be parsed
@@ -594,14 +605,8 @@ def generate_gallery_rst(app):
 
         # generate toctree with subsections
         if gallery_conf["nested_sections"] is True:
-            subsections_toctree = """
-.. toctree::
-   :hidden:
-   :includehidden:
-
-   %s\n
-""" % "\n   ".join(subsection_index_files)
-# """ % "\n   ".join(this_toctree_items + subsection_index_files)
+            subsections_toctree = _format_toctree(
+                subsection_index_files, includehidden=True)
 
             # add toctree to file only if there are subsections
             if len(subsection_index_files) > 0:
 
@@ -43,7 +43,7 @@
 # gen_modules + sg_api_usage + doc/index.rst + minigallery.rst
 N_OTHER = 9 + 1 + 1 + 1 + 1
 N_RST = N_EXAMPLES + N_PASS + N_INDEX + N_EXECUTE + N_OTHER
-N_RST = '(%s|%s)' % (N_RST, N_RST - 1)  # AppVeyor weirdness
+N_RST = '(%s|%s|%s)' % (N_RST, N_RST - 1, N_RST - 2)  # AppVeyor weirdness
 
 
 @pytest.fixture(scope='module')
@@ -180,6 +180,7 @@ def test_junit(sphinx_app, tmpdir):
                             'plot_numpy_matplotlib.py')
     failing_fname = op.join(new_src_dir, '../examples', 'future',
                             'plot_future_imports_broken.py')
+    print('Names', passing_fname, failing_fname)
     shutil.move(passing_fname, passing_fname + '.temp')
     shutil.move(failing_fname, passing_fname)
     shutil.move(passing_fname + '.temp', failing_fname)