From 29e77e369d8b72f6161c1e4211256a48bd6bc19a Mon Sep 17 00:00:00 2001 From: Kyle Sunden Date: Wed, 8 May 2024 16:08:47 -0500 Subject: [PATCH] Backport PR #28103: [DOC]: Fix compatibility with sphinx-gallery 0.16 --- doc/conf.py | 51 +++++++++++---------------- doc/sphinxext/gallery_order.py | 2 +- doc/sphinxext/util.py | 21 +++++++++++ lib/matplotlib/tests/test_doc.py | 5 +-- requirements/doc/doc-requirements.txt | 4 +-- 5 files changed, 48 insertions(+), 35 deletions(-) create mode 100644 doc/sphinxext/util.py diff --git a/doc/conf.py b/doc/conf.py index bc9b1ff7c1fa..c9a475aecf9c 100644 --- a/doc/conf.py +++ b/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 ` - 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 --git a/doc/sphinxext/gallery_order.py b/doc/sphinxext/gallery_order.py index 70a018750537..378cb394d37b 100644 --- a/doc/sphinxext/gallery_order.py +++ b/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 --git a/doc/sphinxext/util.py b/doc/sphinxext/util.py new file mode 100644 index 000000000000..14097ba9396a --- /dev/null +++ b/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 --git a/lib/matplotlib/tests/test_doc.py b/lib/matplotlib/tests/test_doc.py index 592a24198d1b..3e28fd1b8eb7 100644 --- a/lib/matplotlib/tests/test_doc.py +++ b/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 ` - to download the full example code{2} + to download the full example code.{2} .. rst-class:: sphx-glr-example-title diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index 8f8e01a34e4d..e7fc207a739c 100644 --- a/requirements/doc/doc-requirements.txt +++ b/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 pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy