From 55b3991ea192de3763372a53932bf8b09ff0350c Mon Sep 17 00:00:00 2001
From: Ruth Comer <ruth.comer@metoffice.gov.uk>
Date: Sun, 11 Sep 2022 14:22:00 +0100
Subject: [PATCH 1/2] implement make html-noplot

---
 doc/Makefile                  | 5 +++++
 doc/conf.py                   | 1 +
 doc/devel/documenting_mpl.rst | 5 ++++-
 3 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/doc/Makefile b/doc/Makefile
index 8a9dc61c7a3d..6316a5ca0407 100644
--- 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
index f5bb09017024..f9da388ae3f5 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -188,6 +188,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': (
diff --git a/doc/devel/documenting_mpl.rst b/doc/devel/documenting_mpl.rst
index 87f06e5d13dc..648d765ce857 100644
--- 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``.

From 1374e34d2f5cb9c424fc0ae4a9495f3e562e4b06 Mon Sep 17 00:00:00 2001
From: Ruth Comer <ruth.comer@metoffice.gov.uk>
Date: Sun, 18 Sep 2022 21:43:25 +0100
Subject: [PATCH 2/2] filter warnings

---
 doc/conf.py | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/doc/conf.py b/doc/conf.py
index f9da388ae3f5..3c2910638acf 100644
--- 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
@@ -201,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']