Repository: sphinx-gallery/sphinx-gallery

Issue:
Problem in section and example title level in subgalleries
Hello,

Since I'm using the master branch of sphinx-gallery in POT I get to test all your new features ;).

I have a problem because the examples in the subgalleries that where defined as subsubsection in the original doc:
https://pythonot.github.io/auto_examples/index.html
![image](https://user-images.githubusercontent.com/1386873/160867522-6ec1c107-4150-46d7-893a-8d29dd631f90.png)
are now repeated moved at the end of the list with the wrong level
https://pythonot.github.io/master/auto_examples/index.html
![image](https://user-images.githubusercontent.com/1386873/160866932-278a6c29-f3b4-4b80-90ee-1b7330055ba4.png)

There was no change in the subgalleries files. I'm OK with changing stuff to move back to the original behavior but I can't find the information in the doc.

I also noted that you have the same problem in the dev version of your doc:
https://sphinx-gallery.github.io/dev/auto_examples/index.html#no-image-output-examples
![image](https://user-images.githubusercontent.com/1386873/160868826-2cbe53c7-8392-4836-bbe7-17eb68972b50.png)
so I think it might be a bug.


Discussion:
larsoner: Thanks for working on this @alexisthual !
alexisthual: I tried multiple things, but it seems hard (maybe undoable with sphinx `toctree`s) to solve the underlying issue only with `sphinx-gallery` modifications.

However, adding `:titlesonly:` to the `toctree` which generates the part of the navigation bar handling the gallery _almost_ does the trick (see pictures below). From there, I only need to generate one more rst file in order to group together examples which do not belong to a subcategory. 

Before | After
--- | ---
![Screenshot from 2022-04-19 18-25-15](https://user-images.githubusercontent.com/13835654/164051012-13922b16-ac32-4082-8341-826f419122b0.png) | ![Screenshot from 2022-04-19 18-25-37](https://user-images.githubusercontent.com/13835654/164051024-33f1ae7d-d839-4ba9-98ac-51c49e745b06.png)

@larsoner @rflamary do you think it would be reasonable to ask users to:
- add the `:titlesonly:` directive to the relevant `toctree`
- split `index.rst` in two files: `index.rst` which would contain text related to the gallery description and `default.rst` which would contain text related to examples which do not belong to a subcategory (in the case of `sphinx-gallery`, this would refer to the "General Examples" section ; in the case of `POT`, it would refer to the "OT and regularized OT" section)
alexisthual: @rflamary and I just had a call, here are the main points we discussed:
* aforementioned tasks seem reasonable
* however, this new behaviour should be optional (and maybe the default should be the old behaviour) and well documented
* there could be an option such that subsection titles in the navbar link to anchors in the gallery index file rather than to the subsection index file
larsoner: The plan sounds good!

> there could be an option such that subsection titles in the navigation bar link to anchors in the gallery index file rather than to the subsection index file

And I like this option. I think in MNE-Python with the latest changes at some point I clicked a subheading link and expected it to stay on the "big page" but it went to one of the subcategory pages instead... so I'd consider switching to this other option if it were available!
alexisthual: > The plan sounds good!

Ok, this will require more work then, and I won't have a lot of free time in the coming weeks.
When is the next release planned?

larsoner: I don't think we have a timeline, so no problems waiting for now
rflamary: @alexisthual you add an option you double the number of tests! I don't envy you ;)

Thank you all for looking into this. I will probably do a release of POT with stable version of sphinx gallery in th meantime but will be ready for when this is implemented .
alexisthual: Moreover, I added an option to enable/disable nested sections. By default, `nested_sections=True`.

@rflamary I just built `pot`'s latest documentation with this branch and things should now work as expected for you if you set `nested_sections=False` in `./docs/source/conf.py`:
`nested_sections=True` (default) | `nested_sections=False`
--- | ---
![Screenshot from 2022-07-05 17-57-15](https://user-images.githubusercontent.com/13835654/177369072-abf871b6-233e-4610-ab9e-1dcd1e51fa12.png) | ![Screenshot from 2022-07-05 17-57-28](https://user-images.githubusercontent.com/13835654/177369116-0ae5af06-1e01-4e93-8672-aa09ed93954d.png)


larsoner: @alexisthual this sounds good to me, and I agree that the hover behavior is better. Maybe we'll want to add an option for it someday, but let's see if people request it before bothering to add an option. If this is ready to go from you end, can you mark it ready for review? It's still in draft mode. Then I'll take a quick look at the code and hopefully merge!
alexisthual: > Maybe we'll want to add an option for it someday, but let's see if people request it before bothering to add an option.

Are you speaking about an option to toggle the hovering behaviour? 

> If this is ready to go from you end, can you mark it ready for review? It's still in draft mode. Then I'll take a quick look at the code and hopefully merge!

I still have two more things to do:
1. add tests for when `nested_sections=False`
2. edit the changelog to document this option (some users, similarly to `pot`, will need to set `nested_sections=False` in their conf)
larsoner: > Are you speaking about an option to toggle the hovering behaviour?

Yes. It's possible people have used custom CSS for example like:

https://github.com/mne-tools/mne-python/blob/6c43b2d398780e2e69ea2f5b2e3db6b59135825c/doc/_static/style.css#L91-L95

It would be great if stuff like this still worked. But even if it doesn't, adding something in the CHANGES.rst would be good. It sounds like this is already on your TODO list, though!

Let me know when to have a look!
rflamary: That's great, I think that adding this option is a very good idea. Can't wait to do the next release of POT with it ;)
alexisthual: I tried to add tests to `test_full.py` but it seems much more of a burden than I thought.
Initially, I wanted to run `test_rebuild()` two times with `nested_sections` to `True` and `False` respectively, but it seems that setting `confoverrides` when instantiating `Sphinx` objects triggers weird behaviours (such as considering that some files are out of date when they are not, etc).

Otherwise I think this PR is ready for review, and that we can discuss other interesting tests together!
larsoner: > Initially, I wanted to run test_rebuild() two times with nested_sections to True and False respectively, but it seems that setting confoverrides when instantiating Sphinx objects triggers weird behaviours (such as considering that some files are out of date when they are not, etc).

Yeah I would expect a full rebuild actually because a config value has changed. We can deal with this later at some point

Patch:
diff --git a/CHANGES.rst b/CHANGES.rst
index 644b5a4..73ac86d 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -10,11 +10,12 @@ CSS pseudo-elements instead of additional real text. For more details, see
 
 **Implemented enhancements:**
 
--  Modify toctree to include gallery categories (ie gallery subfolders) `#904 <https://github.com/sphinx-gallery/sphinx-gallery/pull/904>`__. Instead of a flat toctree linking the main gallery README / index to all gallery items, one now links the main README to category READMEs, which themselves point to category items. In particular, this allows displaying categories of a given gallery in the sidebar (`alexisthual <https://github.com/alexisthual>`__)
+-  Nest gallery sections (ie gallery subfolders) `#904 <https://github.com/sphinx-gallery/sphinx-gallery/pull/904>`__. This feature can be disabled (see config option ``nested_sections`` in the documentation) if the previous behaviour is prefered (`alexisthual <https://github.com/alexisthual>`__)
+-  Tooltips now overlay gallery items `commit 36166cd <https://github.com/sphinx-gallery/sphinx-gallery/pull/944/commits/36166cd2fc2b43ecbd585654cfe8745f3a1b3f64>`__. Custom CSS might need to be adapted (`alexisthual <https://github.com/alexisthual>`__)
 
 **Fixed bugs:**
 
--  Display gallery items using CSS grid instead of floating `#906 <https://github.com/sphinx-gallery/sphinx-gallery/pull/906>`__, see `migration guide <https://github.com/sphinx-gallery/sphinx-gallery/pull/906#issuecomment-1019542067>`__ to adapt custom css for thumbnails (`alexisthual <https://github.com/alexisthual>`__)
+-  Display gallery items using CSS grid instead of  ``float`` property `#906 <https://github.com/sphinx-gallery/sphinx-gallery/pull/906>`__, see `migration guide <https://github.com/sphinx-gallery/sphinx-gallery/pull/906#issuecomment-1019542067>`__ to adapt custom CSS for thumbnails (`alexisthual <https://github.com/alexisthual>`__)
 
 **Closed issues:**
 
diff --git a/doc/conf.py b/doc/conf.py
index ccf9496..c3056e9 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -395,7 +395,8 @@ sphinx_gallery_conf = {
     # each code block
     'capture_repr': ('_repr_html_', '__repr__'),
     'matplotlib_animations': True,
-    'image_srcset': ["2x"]
+    'image_srcset': ["2x"],
+    'nested_sections': False,
 }
 
 # Remove matplotlib agg warnings from generated doc when using plt.show
diff --git a/doc/configuration.rst b/doc/configuration.rst
index 2b92287..62ee73e 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -57,6 +57,7 @@ file:
 - ``junit`` (:ref:`junit_xml`)
 - ``log_level`` (:ref:`log_level`)
 - ``capture_repr`` and ``ignore_repr_types`` (:ref:`capture_repr`)
+- ``nested_sections`` (:ref:`nested_sections`)
 
 Some options can also be set or overridden on a file-by-file basis:
 
@@ -1826,3 +1827,37 @@ etc. Similarly subclasses of 'matplotlib.axes' (e.g. 'matplotlib.axes.Axes',
         'capture_repr': ('__repr__'),
         'ignore_repr_types': r'matplotlib[text, axes]',
     }
+
+
+.. _nested_sections:
+
+Nesting gallery sections
+========================
+
+By default, ``nested_sections=True``.
+In this case, for each folder present in the gallery's root folder,
+Sphinx-Gallery expects to find a readme and uses it to build
+a specific index file for this subsection.
+This index file will contain the section's description and a toctree
+linking to each gallery item which belongs to this subsection.
+
+Eventually, the gallery's main index files will contain the gallery's
+description and a toctree linking to each subsections's index file.
+
+With this behaviour, generated file structure and toctrees mimic that of
+the original gallery folder. This is useful to generate sidebars with
+nested sections representing the gallery's file structure.
+
+.. note::
+
+    When ``nested_sections=True``, gallery items located in the gallery's root folder
+    should be move to a new subfolder, otherwise the sidebar
+    might not behave as expected (due to the fuzzy toctree structure).
+
+If ``nested_sections=False``, Sphinx-Gallery will behave as it used to
+previous to version 0.10.2.
+Specifically, it will generate a single index file for the whole gallery.
+This index file will contain descriptions for the whole gallery as well as for
+each subsection, and a specific toctree for each subsection.
+In particular, sidebars generated using these toctrees might not reflect the
+actual section / folder structure.
\ No newline at end of file
diff --git a/sphinx_gallery/_static/sg_gallery.css b/sphinx_gallery/_static/sg_gallery.css
index a862f10..ee72dfd 100644
--- a/sphinx_gallery/_static/sg_gallery.css
+++ b/sphinx_gallery/_static/sg_gallery.css
@@ -4,9 +4,10 @@ Tested for Sphinx 1.3.1 for all themes: default, alabaster, sphinxdoc,
 scrolls, agogo, traditional, nature, haiku, pyramid
 Tested for Read the Docs theme 0.1.7 */
 
-html[data-theme="light"] {
-  --sg-tooltip-foreground: #fff;
-  --sg-tooltip-background: rgba(0, 0, 0, 0.8);
+/* Define light colors */
+:root, html[data-theme="light"], body[data-theme="light"]{
+  --sg-tooltip-foreground: black;
+  --sg-tooltip-background: rgba(250, 250, 250, 0.9);
   --sg-tooltip-border: #ccc transparent;
   --sg-thumb-box-shadow-color: #6c757d40;
   --sg-thumb-hover-border: #0069d9;
@@ -23,9 +24,31 @@ html[data-theme="light"] {
   --sg-download-a-hover-box-shadow-1: rgba(255, 255, 255, 0.1);
   --sg-download-a-hover-box-shadow-2: rgba(0, 0, 0, 0.25);
 }
-html[data-theme="dark"] {
-  --sg-tooltip-foreground: #212529;
-  --sg-tooltip-background: rgba(255, 255, 255, 0.8);
+@media(prefers-color-scheme: light) {
+  :root[data-theme="auto"], html[data-theme="auto"], body[data-theme="auto"] {
+    --sg-tooltip-foreground: black;
+    --sg-tooltip-background: rgba(250, 250, 250, 0.9);
+    --sg-tooltip-border: #ccc transparent;
+    --sg-thumb-box-shadow-color: #6c757d40;
+    --sg-thumb-hover-border: #0069d9;
+    --sg-script-out: #888;
+    --sg-script-pre: #fafae2;
+    --sg-pytb-foreground: #000;
+    --sg-pytb-background: #ffe4e4;
+    --sg-pytb-border-color: #f66;
+    --sg-download-a-background-color: #ffc;
+    --sg-download-a-background-image: linear-gradient(to bottom, #ffc, #d5d57e);
+    --sg-download-a-border-color: 1px solid #c2c22d;
+    --sg-download-a-color: #000;
+    --sg-download-a-hover-background-color: #d5d57e;
+    --sg-download-a-hover-box-shadow-1: rgba(255, 255, 255, 0.1);
+    --sg-download-a-hover-box-shadow-2: rgba(0, 0, 0, 0.25);
+  }
+}
+
+html[data-theme="dark"], body[data-theme="dark"] {
+  --sg-tooltip-foreground: white;
+  --sg-tooltip-background: rgba(10, 10, 10, 0.9);
   --sg-tooltip-border: #333 transparent;
   --sg-thumb-box-shadow-color: #79848d40;
   --sg-thumb-hover-border: #003975;
@@ -42,9 +65,31 @@ html[data-theme="dark"] {
   --sg-download-a-hover-box-shadow-1: rgba(0, 0, 0, 0.1);
   --sg-download-a-hover-box-shadow-2: rgba(255, 255, 255, 0.25);
 }
+@media(prefers-color-scheme: dark){
+  html[data-theme="auto"], body[data-theme="auto"] {
+    --sg-tooltip-foreground: white;
+    --sg-tooltip-background: rgba(10, 10, 10, 0.9);
+    --sg-tooltip-border: #333 transparent;
+    --sg-thumb-box-shadow-color: #79848d40;
+    --sg-thumb-hover-border: #003975;
+    --sg-script-out: rgb(179, 179, 179);
+    --sg-script-pre: #2e2e22;
+    --sg-pytb-foreground: #fff;
+    --sg-pytb-background: #1b1717;
+    --sg-pytb-border-color: #622;
+    --sg-download-a-background-color: #443;
+    --sg-download-a-background-image: linear-gradient(to bottom, #443, #221);
+    --sg-download-a-border-color: 1px solid #3a3a0d;
+    --sg-download-a-color: #fff;
+    --sg-download-a-hover-background-color: #616135;
+    --sg-download-a-hover-box-shadow-1: rgba(0, 0, 0, 0.1);
+    --sg-download-a-hover-box-shadow-2: rgba(255, 255, 255, 0.25);
+  }
+}
 
 .sphx-glr-thumbnails {
   width: 100%;
+  margin: 0px 0px 20px 0px;
 
   /* align thumbnails on a grid */
   justify-content: space-between;
@@ -135,27 +180,20 @@ thumbnail with its default link Background color */
 }
 .sphx-glr-thumbcontainer[tooltip]:hover:after {
   background: var(--sg-tooltip-background);
-  -webkit-border-radius: 5px;
-  -moz-border-radius: 5px;
-  border-radius: 5px;
+  -webkit-border-radius: 4px;
+  -moz-border-radius: 4px;
+  border-radius: 4px;
   color: var(--sg-tooltip-foreground);
   content: attr(tooltip);
-  left: 95%;
-  padding: 5px 15px;
-  position: absolute;
+  padding: 10px;
   z-index: 98;
-  width: 220px;
-  bottom: 52%;
-}
-.sphx-glr-thumbcontainer[tooltip]:hover:before {
-  border: solid;
-  border-color: var(--sg-tooltip-border);
-  border-width: 18px 0 0 20px;
-  bottom: 58%;
-  content: "";
-  left: 85%;
+  width: 100%;
+  height: 100%;
   position: absolute;
-  z-index: 99;
+  top: 0;
+  box-sizing: border-box;
+  overflow: hidden;
+  backdrop-filter: blur(3px);
 }
 
 .sphx-glr-script-out {
diff --git a/sphinx_gallery/gen_gallery.py b/sphinx_gallery/gen_gallery.py
index a74dd57..2da42e5 100644
--- a/sphinx_gallery/gen_gallery.py
+++ b/sphinx_gallery/gen_gallery.py
@@ -99,6 +99,7 @@ DEFAULT_GALLERY_CONF = {
     'image_srcset': [],
     'default_thumb_file': None,
     'line_numbers': False,
+    'nested_sections': True,
     'prefer_full_module': [],
 }
 
@@ -478,22 +479,42 @@ def generate_gallery_rst(app):
         gallery_dir_abs_path = os.path.join(app.builder.srcdir, gallery_dir)
 
         # Create section rst files and fetch content which will
-        # be added to current index file
-        this_fhindex, this_costs, this_toctree, _ = generate_dir_rst(
+        # be added to current index file. This only includes content
+        # from files located in the root folder of the current gallery
+        # (ie not in subfolders)
+        (
+            _,
+            this_content,
+            this_costs,
+            this_toctree_items,
+        ) = generate_dir_rst(
             examples_dir_abs_path,
             gallery_dir_abs_path,
             gallery_conf,
-            seen_backrefs
+            seen_backrefs,
+            include_toctree=False,
         )
 
         costs += this_costs
         write_computation_times(gallery_conf, gallery_dir_abs_path, this_costs)
 
-        # we create an index.rst with all examples
+        # We create an index.rst with all examples
+        # (this will overwrite the rst file generated by the previous call
+        # to generate_dir_rst)
         index_rst_new = os.path.join(gallery_dir_abs_path, 'index.rst.new')
         with codecs.open(index_rst_new, 'w', encoding='utf-8') as fhindex:
             # :orphan: to suppress "not included in TOCTREE" sphinx warnings
-            fhindex.write(":orphan:\n\n" + this_fhindex + this_toctree)
+            fhindex.write(":orphan:\n\n" + this_content)
+
+            # Write toctree with gallery items from gallery root folder
+            if len(this_toctree_items) > 0:
+                this_toctree = """
+.. toctree::
+   :hidden:
+
+   %s\n
+""" % "\n   ".join(this_toctree_items)
+                fhindex.write(this_toctree)
 
             # list all paths to subsection index files in this array
             subsection_index_files = []
@@ -509,10 +530,10 @@ def generate_gallery_rst(app):
                 )
 
                 (
+                    subsection_index_path,
                     subsection_index_content,
                     subsection_costs,
-                    _,
-                    subsection_index_path,
+                    subsection_toctree_filenames,
                 ) = generate_dir_rst(
                     src_dir, target_dir, gallery_conf, seen_backrefs
                 )
@@ -527,25 +548,41 @@ def generate_gallery_rst(app):
 
                 fhindex.write(subsection_index_content)
 
+                # Write subsection toctree in main file
+                # only if nested_sections is False or None
+                if not gallery_conf["nested_sections"]:
+                    if len(subsection_toctree_filenames) > 0:
+                        subsection_index_toctree = """
+.. toctree::
+   :hidden:
+
+   %s\n
+""" % "\n   ".join(subsection_toctree_filenames)
+                    fhindex.write(subsection_index_toctree)
+                # Otherwise, a new index.rst.new file should
+                # have been created and it needs to be parsed
+                else:
+                    _replace_md5(subsection_index_path, mode='t')
+
                 costs += subsection_costs
                 write_computation_times(
                     gallery_conf, target_dir, subsection_costs
                 )
 
-                _replace_md5(subsection_index_path, mode='t')
-
             # generate toctree with subsections
-            subsections_toctree = """
+            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)
 
-            # add toctree to file only if there are subsections
-            if len(subsection_index_files) > 0:
-                fhindex.write(subsections_toctree)
+                # add toctree to file only if there are subsections
+                if len(subsection_index_files) > 0:
+                    fhindex.write(subsections_toctree)
 
             if gallery_conf['download_all_examples']:
                 download_fhindex = generate_zipfiles(
diff --git a/sphinx_gallery/gen_rst.py b/sphinx_gallery/gen_rst.py
index 2e3ea19..d78c028 100644
--- a/sphinx_gallery/gen_rst.py
+++ b/sphinx_gallery/gen_rst.py
@@ -363,8 +363,46 @@ THUMBNAIL_PARENT_DIV_CLOSE = """
 """
 
 
-def generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs):
-    """Generate the gallery reStructuredText for an example directory."""
+def generate_dir_rst(
+    src_dir,
+    target_dir,
+    gallery_conf,
+    seen_backrefs,
+    include_toctree=True,
+):
+    """Generate the gallery reStructuredText for an example directory.
+
+    Parameters
+    ----------
+    src_dir: str,
+        Path to example directory containing python files
+        and possibly sub categories
+    target_dir: str,
+        Path where parsed examples (rst, python files, etc)
+        will be outputed
+    gallery_conf : Dict[str, Any]
+        Gallery configurations.
+    seen_backrefs: set,
+        Back references encountered when parsing this gallery
+        will be stored in this set.
+    include_toctree: bool,
+        Whether or not toctree should be included
+        in generated rst file.
+        Default = True.
+
+    Returns
+    -------
+    index_path: str,
+        Path to index rst file presenting the current example gallery
+    index_content: str,
+        Content which will be written to the index rst file
+        presenting the current example gallery
+    costs: list,
+        List of costs for building each element of the gallery
+    toctree_items: list,
+        List of files included in toctree
+        (independent of include_toctree's value)
+    """
     head_ref = os.path.relpath(target_dir, gallery_conf['src_dir'])
 
     subsection_index_content = ""
@@ -416,7 +454,7 @@ def generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs):
             target_dir, gallery_conf['src_dir'], fname, intro, title
         )
         entries_text.append(this_entry)
-        subsection_toctree_filenames.append(gallery_item_filename)
+        subsection_toctree_filenames.append("/" + gallery_item_filename)
 
     for entry_text in entries_text:
         subsection_index_content += entry_text
@@ -424,33 +462,41 @@ def generate_dir_rst(src_dir, target_dir, gallery_conf, seen_backrefs):
     # Close thumbnail parent div
     subsection_index_content += THUMBNAIL_PARENT_DIV_CLOSE
 
-    # Create toctree for index file
-    # with all gallery items which belong to current subsection.
-    # The toctree string should be empty if there are no subsections
-    # or related files, as it will be returned at the end of this function.
-    subsection_index_toctree = ""
-    if len(subsection_toctree_filenames) > 0:
-        subsection_index_toctree = """
+    # Write subsection index file
+    # only if nested_sections is True
+    subsection_index_path = None
+    if gallery_conf["nested_sections"] is True:
+        subsection_index_path = os.path.join(target_dir, 'index.rst.new')
+        with codecs.open(subsection_index_path, 'w', encoding='utf-8') as (
+            findex
+        ):
+            findex.write("""\n\n.. _sphx_glr_{0}:\n\n""".format(
+                head_ref.replace(os.path.sep, '_')
+            ))
+            findex.write(subsection_index_content)
+
+            # Create toctree for index file
+            # with all gallery items which belong to current subsection
+            # and add it to generated index rst file if need be.
+            # Toctree cannot be empty
+            # and won't be added if include_toctree is false
+            # (this is useful when generating the example gallery's main
+            # index rst file, which should contain only one toctree)
+            if len(subsection_toctree_filenames) > 0 and include_toctree:
+                subsection_index_toctree = """
 .. toctree::
    :hidden:
 
-   /%s\n
-""" % "\n   /".join(subsection_toctree_filenames)
+   %s\n
+""" % "\n   ".join(subsection_toctree_filenames)
+                findex.write(subsection_index_toctree)
 
-    # Write subsection index file
-    subsection_index_path = os.path.join(target_dir, 'index.rst.new')
-    with codecs.open(subsection_index_path, 'w', encoding='utf-8') as findex:
-        findex.write("""\n\n.. _sphx_glr_{0}:\n\n""".format(
-            head_ref.replace(os.path.sep, '_')
-        ))
-        findex.write(subsection_index_content)
-
-        # add toctree to file only if toctree is not empty
-        if len(subsection_toctree_filenames) > 0:
-            findex.write(subsection_index_toctree)
-
-    return subsection_index_content, costs, subsection_index_toctree, \
-        subsection_index_path
+    return (
+        subsection_index_path,
+        subsection_index_content,
+        costs,
+        subsection_toctree_filenames,
+    )
 
 
 def handle_exception(exc_info, src_file, script_vars, gallery_conf):


Test patch:
diff --git a/sphinx_gallery/tests/test_gen_rst.py b/sphinx_gallery/tests/test_gen_rst.py
index de31005..92462d7 100644
--- a/sphinx_gallery/tests/test_gen_rst.py
+++ b/sphinx_gallery/tests/test_gen_rst.py
@@ -565,7 +565,7 @@ def test_gen_dir_rst(gallery_conf, fakesphinxapp, ext):
             generate_dir_rst(*args)
     else:
         out = generate_dir_rst(*args)
-        assert u"Óscar here" in out[0]
+        assert u"Óscar here" in out[1]
 
 
 def test_pattern_matching(gallery_conf, log_collector, req_pil):