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