Merge pull request #23870 from rcomer/skip-gallery-builds

timhoffm · web-flow · commit 89d625e35dd6 · 2022-09-19T13:50:13.000+02:00
Implement Sphinx-Gallery's `make html-noplot`
diff --git a/doc/Makefile b/doc/Makefile
@@ -28,6 +28,11 @@ clean:
 show:
 	@python -c "import webbrowser; webbrowser.open_new_tab('file://$(shell pwd)/build/html/index.html')"
 
+html-noplot:
+	$(SPHINXBUILD) -D plot_gallery=0 -b html $(SOURCEDIR) $(BUILDDIR)/html $(SPHINXOPTS) $(O)
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
diff --git a/doc/conf.py b/doc/conf.py
@@ -11,6 +11,7 @@
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
+import logging
 import os
 from pathlib import Path
 import shutil
@@ -188,6 +189,7 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
     'junit': '../test-results/sphinx-gallery/junit.xml' if CIRCLECI else '',
     'matplotlib_animations': True,
     'min_reported_time': 1,
+    'plot_gallery': 'True',  # sphinx-gallery/913
     'reference_url': {'matplotlib': None},
     'remove_config_comments': True,
     'reset_modules': (
@@ -200,6 +202,25 @@ def matplotlib_reduced_latex_scraper(block, block_vars, gallery_conf,
     'within_subsection_order': gallery_order.subsectionorder,
 }
 
+if 'plot_gallery=0' in sys.argv:
+    # Gallery images are not created.  Suppress warnings triggered where other
+    # parts of the documentation link to these images.
+
+    def gallery_image_warning_filter(record):
+        msg = record.msg
+        for gallery_dir in sphinx_gallery_conf['gallery_dirs']:
+            if msg.startswith(f'image file not readable: {gallery_dir}'):
+                return False
+
+        if msg == 'Could not obtain image size. :scale: option is ignored.':
+            return False
+
+        return True
+
+    logger = logging.getLogger('sphinx')
+    logger.addFilter(gallery_image_warning_filter)
+
+
 mathmpl_fontsize = 11.0
 mathmpl_srcset = ['2x']
 
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
@@ -67,6 +67,10 @@ Other useful invocations include
 
 .. code-block:: sh
 
+   # Build the html documentation, but skip generation of the gallery images to
+   # save time.
+   make html-noplot
+
    # Delete built files.  May help if you get errors about missing paths or
    # broken links.
    make clean
@@ -86,7 +90,6 @@ You can use the ``O`` variable to set additional options:
 
 * ``make O=-j4 html`` runs a parallel build with 4 processes.
 * ``make O=-Dplot_formats=png:100 html`` saves figures in low resolution.
-* ``make O=-Dplot_gallery=0 html`` skips the gallery build.
 
 Multiple options can be combined, e.g. ``make O='-j4 -Dplot_gallery=0'
 html``.
