Merge pull request matplotlib#28190 from meeseeksmachine/auto-backport-of-pr-28103-on-v3.9.x

Backport PR matplotlib#28103 on branch v3.9.x ([DOC]: Fix compatibility with sphinx-gallery 0.16)

Author: QuLogic

Diff for: 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,20 @@ 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'):
+    gallery_order_sectionorder = 'sphinxext.gallery_order.sectionorder'
+    gallery_order_subsectionorder = 'sphinxext.gallery_order.subsectionorder'
+    clear_basic_units = 'sphinxext.util.clear_basic_units'
+    matplotlib_reduced_latex_scraper = 'sphinxext.util.matplotlib_reduced_latex_scraper'
+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,
+        subsectionorder as gallery_order_subsectionorder)
+    from sphinxext.util import clear_basic_units, matplotlib_reduced_latex_scraper
 
 # The following import is only necessary to monkey patch the signature later on
 from sphinx_gallery import gen_rst
@@ -228,22 +240,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 +250,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 +265,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', clear_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 +325,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 +750,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 +805,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}")

Diff for: doc/sphinxext/gallery_order.py

@@ -105,7 +105,7 @@ def __call__(self, item):
 explicit_subsection_order = [item + ".py" for item in list_all]
 
 
-class MplExplicitSubOrder:
+class MplExplicitSubOrder(ExplicitOrder):
     """For use within the 'within_subsection_order' key."""
     def __init__(self, src_dir):
         self.src_dir = src_dir  # src_dir is unused here

Diff for: doc/sphinxext/util.py

@@ -0,0 +1,21 @@
+import sys
+
+
+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)
+
+
+# Clear basic_units module to re-register with unit registry on import.
+def clear_basic_units(gallery_conf, fname):
+    return sys.modules.pop('basic_units', None)

Diff for: 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
 

Diff for: requirements/doc/doc-requirements.txt

@@ -7,7 +7,7 @@
 # Install the documentation requirements with:
 #     pip install -r requirements/doc/doc-requirements.txt
 #
-sphinx>=3.0.0,!=6.1.2,!=7.3.*
+sphinx>=3.0.0,!=6.1.2
 colorspacious
 ipython
 ipywidgets
@@ -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-copybutton
 sphinx-design
+sphinx-gallery>=0.12.0
 sphinx-tags>=0.3.0