Support sphinx-gallery 0.16.0

There was a small change to the `EXAMPLE_HEADER` that we patch, so
update that to match the new version. However, since that change is only
a single period, I did not bother to keep the old version around.

Additionally, sphinx-gallery has changed its recommendations for its
configuration to use strings denoting importable callables. As this
doesn't work in the older version, this has been made conditional
instead of bumping the minimum requirement.

Author: QuLogic

doc/conf.py

@@ -22,6 +22,7 @@
 from urllib.parse import urlsplit, urlunsplit
 import warnings
 
+from packaging.version import parse as parse_version
 import sphinx
 import yaml
 
@@ -178,9 +179,21 @@ def _check_dependencies():
 
 
 # Import only after checking for dependencies.
-# gallery_order.py from the sphinxext folder provides the classes that
-# allow custom ordering of sections and subsections of the gallery
-import sphinxext.gallery_order as gallery_order
+
+import sphinx_gallery
+
+if parse_version(sphinx_gallery.__version__) >= parse_version('0.16.0'):
+    matplotlib_reduced_latex_scraper = 'sphinxext.matplotlib_reduced_latex_scraper'
+    reset_modules_basic_units = 'sphinxext.reset_modules_basic_units'
+    gallery_order_sectionorder = 'sphinxext.gallery_order.sectionorder'
+    gallery_order_subsectionorder = 'sphinxext.gallery_order.subsectionorder'
+else:
+    # gallery_order.py from the sphinxext folder provides the classes that
+    # allow custom ordering of sections and subsections of the gallery
+    from sphinxext.gallery_order import sectionorder as gallery_order_sectionorder
+    from sphinxext.gallery_order import subsectionorder as gallery_order_subsectionorder
+    from sphinxext import matplotlib_reduced_latex_scraper
+    from sphinxext import reset_modules_basic_units
 
 # The following import is only necessary to monkey patch the signature later on
 from sphinx_gallery import gen_rst
@@ -230,20 +243,6 @@ def _check_dependencies():
 
 # Sphinx gallery configuration
 
-def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
-                                     **kwargs):
-    """
-    Reduce srcset when creating a PDF.
-
-    Because sphinx-gallery runs *very* early, we cannot modify this even in the
-    earliest builder-inited signal. Thus we do it at scraping time.
-    """
-    from sphinx_gallery.scrapers import matplotlib_scraper
-
-    if gallery_conf['builder_name'] == 'latex':
-        gallery_conf['image_srcset'] = []
-    return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs)
-
 gallery_dirs = [f'{ed}' for ed in
                 ['gallery', 'tutorials', 'plot_types', 'users/explain']
                 if f'{ed}/*' not in skip_subdirs]
@@ -254,7 +253,7 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
     example_dirs += [f'../galleries/{gd}']
 
 sphinx_gallery_conf = {
-    'backreferences_dir': Path('api') / Path('_as_gen'),
+    'backreferences_dir': Path('api', '_as_gen'),
     # Compression is a significant effort that we skip for local and CI builds.
     'compress_images': ('thumbnails', 'images') if is_release_build else (),
     'doc_module': ('matplotlib', 'mpl_toolkits'),
@@ -269,14 +268,10 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
     'plot_gallery': 'True',  # sphinx-gallery/913
     'reference_url': {'matplotlib': None},
     'remove_config_comments': True,
-    'reset_modules': (
-        'matplotlib',
-        # clear basic_units module to re-register with unit registry on import
-        lambda gallery_conf, fname: sys.modules.pop('basic_units', None)
-    ),
-    'subsection_order': gallery_order.sectionorder,
+    'reset_modules': ('matplotlib', reset_modules_basic_units),
+    'subsection_order': gallery_order_sectionorder,
     'thumbnail_size': (320, 224),
-    'within_subsection_order': gallery_order.subsectionorder,
+    'within_subsection_order': gallery_order_subsectionorder,
     'capture_repr': (),
     'copyfile_regex': r'.*\.rst',
 }
@@ -333,7 +328,7 @@ def gallery_image_warning_filter(record):
         :class: sphx-glr-download-link-note
 
         :ref:`Go to the end <sphx_glr_download_{1}>`
-        to download the full example code{2}
+        to download the full example code.{2}
 
 .. rst-class:: sphx-glr-example-title
 
@@ -758,7 +753,6 @@ def js_tag_with_cache_busting(js):
 
 if link_github:
     import inspect
-    from packaging.version import parse
 
     extensions.append('sphinx.ext.linkcode')
 
@@ -814,7 +808,7 @@ def linkcode_resolve(domain, info):
         if not fn.startswith(('matplotlib/', 'mpl_toolkits/')):
             return None
 
-        version = parse(matplotlib.__version__)
+        version = parse_version(matplotlib.__version__)
         tag = 'main' if version.is_devrelease else f'v{version.public}'
         return ("https://github.com/matplotlib/matplotlib/blob"
                 f"/{tag}/lib/{fn}{linespec}")

doc/sphinxext/__init__.py

@@ -0,0 +1,22 @@
+import sys
+
+
+# Sphinx gallery configuration
+
+def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, **kwargs):
+    """
+    Reduce srcset when creating a PDF.
+
+    Because sphinx-gallery runs *very* early, we cannot modify this even in the earliest
+    builder-inited signal. Thus we do it at scraping time.
+    """
+    from sphinx_gallery.scrapers import matplotlib_scraper
+
+    if gallery_conf['builder_name'] == 'latex':
+        gallery_conf['image_srcset'] = []
+    return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs)
+
+
+def reset_modules_basic_units(gallery_conf, fname):
+    # Clear basic_units module to re-register with unit registry on import
+    sys.modules.pop('basic_units', None)

lib/matplotlib/tests/test_doc.py

@@ -9,7 +9,8 @@ def test_sphinx_gallery_example_header():
     EXAMPLE_HEADER, this test will start to fail. In that case, please update
     the monkey-patching of EXAMPLE_HEADER in conf.py.
     """
-    gen_rst = pytest.importorskip('sphinx_gallery.gen_rst')
+    pytest.importorskip('sphinx_gallery', minversion='0.16.0')
+    from sphinx_gallery import gen_rst
 
     EXAMPLE_HEADER = """
 .. DO NOT EDIT.
@@ -24,7 +25,7 @@ def test_sphinx_gallery_example_header():
         :class: sphx-glr-download-link-note
 
         :ref:`Go to the end <sphx_glr_download_{1}>`
-        to download the full example code{2}
+        to download the full example code.{2}
 
 .. rst-class:: sphx-glr-example-title
 

requirements/doc/doc-requirements.txt

@@ -18,7 +18,7 @@ pydata-sphinx-theme~=0.15.0
 mpl-sphinx-theme~=3.8.0
 pyyaml
 sphinxcontrib-svg2pdfconverter>=1.1.0
-sphinx-gallery>=0.12.0
+sphinx-gallery>=0.16.0
 sphinx-copybutton
 sphinx-design
 sphinx-tags>=0.3.0