BUG: Fix single column example (#993)

* TST: Expose bug with divs * BUG: Fix bug with doubling * FIX: Better test * FIX: Bump req to 3 * FIX: Try another * FIX: Restoer * FIX: Better name * FIX: Possible * FIX: re
sphinx-gallery · Aug 19, 2022 · f4a283a · f4a283a
1 parent 18705f8
commit f4a283a
Show file tree

Hide file tree

Showing 9 changed files with 73 additions and 48 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,16 @@
 Change Log
 ==========
 
+v0.12.0
+-------
+
+Support for Sphinx < 3 dropped in this release. Requirement is Sphinx >= 3.
+
+**Fixed bugs:**
+
+-  BUG: Fix single column example `#993 <https://github.com/sphinx-gallery/sphinx-gallery/pull/993>`__ (`larsoner <https://github.com/larsoner>`__)
+
+
 v0.11.0
 -------
 

diff --git a/azure-pipelines.yml b/azure-pipelines.yml
@@ -94,10 +94,10 @@ stages:
           DISTRIB: 'ubuntu'
           PYTHON_VERSION: '3.7'
           SPHINXOPTS: ''
-        conda_python37_sphinx183:
+        conda_python37_sphinxOld:
           DISTRIB: 'conda'
           PYTHON_VERSION: '3.7'
-          SPHINX_VERSION: '1.8.3'
+          SPHINX_VERSION: '3'
           LOCALE: 'C'
         conda_python38_sphinxDev:
           DISTRIB: 'conda'

diff --git a/continuous_integration/azure/install.sh b/continuous_integration/azure/install.sh
@@ -67,7 +67,7 @@ elif [ "$DISTRIB" == "ubuntu" ]; then
     python3 -m pip install -r dev-requirements.txt | cat
     python3 -m pip install --upgrade pytest pytest-cov coverage
     # test show_memory=True without memory_profiler by not installing it (not in req)
-    python3 -m pip install sphinx==1.8.3 "jinja2<=3.0.3"
+    python3 -m pip install sphinx==3 "jinja2<=3.0.3"
     python3 setup.py install --user
     python3 -m pip list
 else

diff --git a/dev-requirements.txt b/dev-requirements.txt
@@ -1,4 +1,4 @@
-sphinx>=1.8.3
+sphinx>=3
 sphinx_rtd_theme
 pytest
 pytest-coverage

diff --git a/requirements.txt b/requirements.txt
@@ -1 +1 @@
-sphinx>=1.8.3
+sphinx>=3
diff --git a/sphinx_gallery/backreferences.py b/sphinx_gallery/backreferences.py
@@ -23,7 +23,21 @@
 
 from .scrapers import _find_image_ext
 from .utils import _replace_md5
-from .directives import THUMBNAIL_PARENT_DIV, THUMBNAIL_PARENT_DIV_CLOSE
+
+
+THUMBNAIL_PARENT_DIV = """
+.. raw:: html
+
+    <div class="sphx-glr-thumbnails">
+
+"""
+
+THUMBNAIL_PARENT_DIV_CLOSE = """
+.. raw:: html
+
+    </div>
+
+"""
 
 
 class DummyClass(object):
@@ -311,6 +325,7 @@ def _write_backreferences(backrefs, seen_backrefs, gallery_conf,
                 heading = 'Examples using ``%s``' % backref
                 ex_file.write('\n\n' + heading + '\n')
                 ex_file.write('^' * len(heading) + '\n')
+                ex_file.write('\n\n.. start-sphx-glr-thumbnails\n\n')
                 # Open a div which will contain all thumbnails
                 # (it will be closed in _finalize_backreferences)
                 ex_file.write(THUMBNAIL_PARENT_DIV)

diff --git a/sphinx_gallery/directives.py b/sphinx_gallery/directives.py
@@ -14,21 +14,6 @@
 from sphinx.errors import ExtensionError
 
 
-THUMBNAIL_PARENT_DIV = """
-.. raw:: html
-
-    <div class="sphx-glr-thumbnails">
-
-"""
-
-THUMBNAIL_PARENT_DIV_CLOSE = """
-.. raw:: html
-
-    </div>
-
-"""
-
-
 class MiniGallery(Directive):
     """
     Custom directive to insert a mini-gallery
@@ -87,21 +72,18 @@ def has_backrefs(obj):
         if not any(has_backrefs(obj) for obj in obj_list):
             return []
 
-        # Add div containing all thumbnails;
-        # this is helpful for controlling grid or flexbox behaviours
-        lines.append(THUMBNAIL_PARENT_DIV)
-
-        # Insert the backreferences file(s) using the `include` directive
+        # Insert the backreferences file(s) using the `include` directive.
+        # This already includes the opening <div class="sphx-glr-thumbnails">
+        # and its closing </div>.
         for obj in obj_list:
             path = os.path.join('/',  # Sphinx treats this as the source dir
                                 backreferences_dir,
                                 '{}.examples'.format(obj))
 
-            # Always remove the heading (first 5 lines) from the file
-            lines.append('.. include:: {}\n    :start-line: 5'.format(path))
-
-        # Close thumbnail parent div
-        lines.append(THUMBNAIL_PARENT_DIV_CLOSE)
+            # Always remove the heading from the file
+            lines.append("""\
+.. include:: {}
+    :start-after: start-sphx-glr-thumbnails""".format(path))
 
         # Parse the assembly of `include` and `raw` directives
         text = '\n'.join(lines)

diff --git a/sphinx_gallery/gen_rst.py b/sphinx_gallery/gen_rst.py
@@ -42,7 +42,8 @@
                     optipng)
 from . import glr_path_static
 from .backreferences import (_write_backreferences, _thumbnail_div,
-                             identify_names)
+                             identify_names, THUMBNAIL_PARENT_DIV,
+                             THUMBNAIL_PARENT_DIV_CLOSE)
 from .downloads import CODE_DOWNLOAD
 from .py_source_parser import (split_code_and_text_blocks,
                                remove_config_comments,
@@ -348,21 +349,6 @@ def _get_readme(dir_, gallery_conf, raise_error=True):
     return None
 
 
-THUMBNAIL_PARENT_DIV = """
-.. raw:: html
-
-    <div class="sphx-glr-thumbnails">
-
-"""
-
-THUMBNAIL_PARENT_DIV_CLOSE = """
-.. raw:: html
-
-    </div>
-
-"""
-
-
 def generate_dir_rst(
     src_dir,
     target_dir,

diff --git a/sphinx_gallery/tests/test_full.py b/sphinx_gallery/tests/test_full.py
@@ -395,14 +395,46 @@ def test_backreferences(sphinx_app):
     ('sphinx_gallery.sorting.ExplicitOrder.examples',
      'plot_second_future_imports'),
 ])
-def test_backreferences_examples(sphinx_app, rst_file, example_used_in):
+def test_backreferences_examples_rst(sphinx_app, rst_file, example_used_in):
     """Test linking to mini-galleries using backreferences_dir."""
     backref_dir = sphinx_app.srcdir
     examples_rst = op.join(backref_dir, 'gen_modules', 'backreferences',
                            rst_file)
     with codecs.open(examples_rst, 'r', 'utf-8') as fid:
         lines = fid.read()
     assert example_used_in in lines
+    # check the .. raw:: html div count
+    n_open = lines.count('<div')
+    n_close = lines.count('</div')
+    assert n_open == n_close
+
+
+def test_backreferences_examples_html(sphinx_app):
+    """Test linking to mini-galleries using backreferences_dir."""
+    backref_file = op.join(sphinx_app.outdir, 'gen_modules',
+                           'sphinx_gallery.backreferences.html')
+    with codecs.open(backref_file, 'r', 'utf-8') as fid:
+        lines = fid.read()
+    # Class properties not properly checked on older Sphinx (e.g. 3)
+    # so let's use the "id" instead
+    regex = re.compile(r'<dt[ \S]*id="sphinx_gallery.backreferences.[ \S]*>')
+    n_documented = len(regex.findall(lines))
+    possible = '\n'.join(line for line in lines.split('\n') if '<dt ' in line)
+    # identify_names, DummyClass, DummyClass.prop, DummyClass.run, NameFinder
+    assert n_documented == 5, possible
+    # identify_names, DummyClass, NameFinder (3); once doc, once left bar (x2)
+    n_mini = lines.count('Examples using ')
+    assert n_mini == 6
+    # only 3 actual mini-gallery divs
+    n_div = lines.count('<div class="sphx-glr-thumbnails')
+    assert n_div == 3
+    # 3 documented uses
+    n_thumb = lines.count('<div class="sphx-glr-thumbcontainer')
+    assert n_thumb == 3
+    # matched opening/closing divs
+    n_open = lines.count('<div')
+    n_close = lines.count('</div')
+    assert n_open == n_close  # should always be equal
 
 
 def test_logging_std_nested(sphinx_app):