From ccb5af5ffdaa1aab2e8729e130fde90f40aadf0e Mon Sep 17 00:00:00 2001 From: Nabil Date: Fri, 19 Apr 2024 05:15:59 +0600 Subject: [PATCH 1/8] FIX (partial): sphinx_gallery_conf not pickleable --- doc/conf.py | 24 ++++-------------------- doc/sphinxext/gallery_order.py | 5 ++++- doc/sphinxext/util.py | 20 ++++++++++++++++++++ 3 files changed, 28 insertions(+), 21 deletions(-) create mode 100644 doc/sphinxext/util.py diff --git a/doc/conf.py b/doc/conf.py index bc9b1ff7c1fa..467775344485 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -228,22 +228,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] @@ -261,7 +245,7 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, 'examples_dirs': example_dirs, 'filename_pattern': '^((?!sgskip).)*$', 'gallery_dirs': gallery_dirs, - 'image_scrapers': (matplotlib_reduced_latex_scraper, ), + 'image_scrapers': ("sphinxext.util.matplotlib_reduced_latex_scraper", ), 'image_srcset': ["2x"], 'junit': '../test-results/sphinx-gallery/junit.xml' if CIRCLECI else '', 'matplotlib_animations': True, @@ -272,11 +256,11 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, '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) + "sphinxext.util.clear_basic_unit" ), - 'subsection_order': gallery_order.sectionorder, + 'subsection_order': "sphinxext.gallery_order.sectionorder", 'thumbnail_size': (320, 224), - 'within_subsection_order': gallery_order.subsectionorder, + 'within_subsection_order': "sphinxext.gallery_order.subsectionorder", 'capture_repr': (), 'copyfile_regex': r'.*\.rst', } diff --git a/doc/sphinxext/gallery_order.py b/doc/sphinxext/gallery_order.py index 70a018750537..44735f62753b 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 @@ -119,6 +119,9 @@ def __call__(self, item): # ensure not explicitly listed items come last. return "zzz" + item +# from sphinx.confing import is_serializable +# assert is_serializable(MplExplicitSubOrder) + # Provide the above classes for use in conf.py sectionorder = MplExplicitOrder(explicit_order_folders) diff --git a/doc/sphinxext/util.py b/doc/sphinxext/util.py new file mode 100644 index 000000000000..c0874364aa5b --- /dev/null +++ b/doc/sphinxext/util.py @@ -0,0 +1,20 @@ +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 clear_basic_unit(gallery_conf, fname): + return sys.modules.pop('basic_units', None) \ No newline at end of file From 883535d74e15142e0e560334f8839e1686378df3 Mon Sep 17 00:00:00 2001 From: Nabil Date: Sat, 20 Apr 2024 02:09:47 +0600 Subject: [PATCH 2/8] modify ci config to test updated sphinx_gallery --- .circleci/config.yml | 1 + requirements/doc/doc-requirements.txt | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 1ab22d302314..ec321cb368fe 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -107,6 +107,7 @@ commands: python -m pip install --user \ numpy<< parameters.numpy_version >> \ -r requirements/doc/doc-requirements.txt + pip install git+https://github.com/larsoner/sphinx-gallery.git@serial python -m pip install --no-deps --user \ git+https://github.com/matplotlib/mpl-sphinx-theme.git diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index 8f8e01a34e4d..11c81abd5128 100644 --- a/requirements/doc/doc-requirements.txt +++ b/requirements/doc/doc-requirements.txt @@ -18,7 +18,6 @@ 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-tags>=0.3.0 From f331594533d2d72bafd4a9729c970e3a8eb3d57d Mon Sep 17 00:00:00 2001 From: Nabil Date: Sat, 20 Apr 2024 11:44:02 +0600 Subject: [PATCH 3/8] clean code & remove sphinx version restriction --- doc/conf.py | 1 - doc/sphinxext/util.py | 4 ++-- requirements/doc/doc-requirements.txt | 2 +- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 467775344485..ddaead0545e1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -180,7 +180,6 @@ 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 # The following import is only necessary to monkey patch the signature later on from sphinx_gallery import gen_rst diff --git a/doc/sphinxext/util.py b/doc/sphinxext/util.py index c0874364aa5b..5100693a779f 100644 --- a/doc/sphinxext/util.py +++ b/doc/sphinxext/util.py @@ -1,6 +1,6 @@ import sys -# Sphinx gallery configuration + def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, **kwargs): """ @@ -17,4 +17,4 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, def clear_basic_unit(gallery_conf, fname): - return sys.modules.pop('basic_units', None) \ No newline at end of file + return sys.modules.pop('basic_units', None) diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index 11c81abd5128..24a3f90ccfa8 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 colorspacious ipython ipywidgets From ba8345f6444a006554dd9a286dadd76976e7b132 Mon Sep 17 00:00:00 2001 From: Nabil Date: Sat, 20 Apr 2024 12:19:48 +0600 Subject: [PATCH 4/8] remove unnecessary comment --- doc/sphinxext/gallery_order.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/sphinxext/gallery_order.py b/doc/sphinxext/gallery_order.py index 44735f62753b..378cb394d37b 100644 --- a/doc/sphinxext/gallery_order.py +++ b/doc/sphinxext/gallery_order.py @@ -119,9 +119,6 @@ def __call__(self, item): # ensure not explicitly listed items come last. return "zzz" + item -# from sphinx.confing import is_serializable -# assert is_serializable(MplExplicitSubOrder) - # Provide the above classes for use in conf.py sectionorder = MplExplicitOrder(explicit_order_folders) From 8c18b4d22eb360ad95bf18a21fffcc9635aeb43f Mon Sep 17 00:00:00 2001 From: Nabil Date: Sat, 20 Apr 2024 15:22:41 +0600 Subject: [PATCH 5/8] properly undo #28094 --- requirements/doc/doc-requirements.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index 24a3f90ccfa8..fc6a7c6d1a12 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 +sphinx>=3.0.0,!=6.1.2 colorspacious ipython ipywidgets From 6046659c2e08fee055a10268d0b4d6d73207a995 Mon Sep 17 00:00:00 2001 From: Nabil Date: Tue, 23 Apr 2024 01:16:11 +0600 Subject: [PATCH 6/8] move sphinx-gallery installation back to requirements.txt~ --- .circleci/config.yml | 1 - requirements/doc/doc-requirements.txt | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index ec321cb368fe..1ab22d302314 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -107,7 +107,6 @@ commands: python -m pip install --user \ numpy<< parameters.numpy_version >> \ -r requirements/doc/doc-requirements.txt - pip install git+https://github.com/larsoner/sphinx-gallery.git@serial python -m pip install --no-deps --user \ git+https://github.com/matplotlib/mpl-sphinx-theme.git diff --git a/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index fc6a7c6d1a12..642a03d00b1f 100644 --- a/requirements/doc/doc-requirements.txt +++ b/requirements/doc/doc-requirements.txt @@ -21,3 +21,4 @@ sphinxcontrib-svg2pdfconverter>=1.1.0 sphinx-copybutton sphinx-design sphinx-tags>=0.3.0 +sphinx-gallery @ git+https://github.com/larsoner/sphinx-gallery.git@serial From 4a803393a2c053c998109750ad0c056df1961fb8 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Wed, 1 May 2024 22:43:47 -0400 Subject: [PATCH 7/8] DOC: Keep supporting older sphinx-gallery --- doc/conf.py | 34 +++++++++++++++++---------- doc/sphinxext/util.py | 3 ++- requirements/doc/doc-requirements.txt | 2 +- 3 files changed, 24 insertions(+), 15 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index ddaead0545e1..04763d062d3e 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,8 +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 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 @@ -237,14 +250,14 @@ def _check_dependencies(): 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'), 'examples_dirs': example_dirs, 'filename_pattern': '^((?!sgskip).)*$', 'gallery_dirs': gallery_dirs, - 'image_scrapers': ("sphinxext.util.matplotlib_reduced_latex_scraper", ), + 'image_scrapers': (matplotlib_reduced_latex_scraper, ), 'image_srcset': ["2x"], 'junit': '../test-results/sphinx-gallery/junit.xml' if CIRCLECI else '', 'matplotlib_animations': True, @@ -252,14 +265,10 @@ def _check_dependencies(): '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 - "sphinxext.util.clear_basic_unit" - ), - 'subsection_order': "sphinxext.gallery_order.sectionorder", + 'reset_modules': ('matplotlib', clear_basic_units), + 'subsection_order': gallery_order_sectionorder, 'thumbnail_size': (320, 224), - 'within_subsection_order': "sphinxext.gallery_order.subsectionorder", + 'within_subsection_order': gallery_order_subsectionorder, 'capture_repr': (), 'copyfile_regex': r'.*\.rst', } @@ -741,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') @@ -797,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/util.py b/doc/sphinxext/util.py index 5100693a779f..14097ba9396a 100644 --- a/doc/sphinxext/util.py +++ b/doc/sphinxext/util.py @@ -16,5 +16,6 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf, return matplotlib_scraper(block, block_vars, gallery_conf, **kwargs) -def clear_basic_unit(gallery_conf, fname): +# 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/requirements/doc/doc-requirements.txt b/requirements/doc/doc-requirements.txt index 642a03d00b1f..e7fc207a739c 100644 --- a/requirements/doc/doc-requirements.txt +++ b/requirements/doc/doc-requirements.txt @@ -20,5 +20,5 @@ pyyaml sphinxcontrib-svg2pdfconverter>=1.1.0 sphinx-copybutton sphinx-design +sphinx-gallery>=0.12.0 sphinx-tags>=0.3.0 -sphinx-gallery @ git+https://github.com/larsoner/sphinx-gallery.git@serial From bda6ac5a330524a40c333e4c736e1616da6924b8 Mon Sep 17 00:00:00 2001 From: Elliott Sales de Andrade Date: Thu, 2 May 2024 00:28:10 -0400 Subject: [PATCH 8/8] Update header patch for 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. --- doc/conf.py | 2 +- lib/matplotlib/tests/test_doc.py | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 04763d062d3e..c9a475aecf9c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -325,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 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