[MAINT] Fix some gallery files not being executed

docs/examples/system-models/oedi_9068.py → docs/examples/system-models/noplot_oedi_9068.py

@@ -13,9 +13,15 @@
 #
 # The system has public monitoring data available at the Open Energy Data
 # Initiative (OEDI) under `System ID
-# 9068 <https://data.openei.org/s3_viewer?bucket=oedi-data-lake&prefix=pvdaq%2F2023-solar-data-prize%2F9068_OEDI%2F>`__.
+# 9068 <https://data.openei.org/s3_viewer?bucket=oedi-data-lake&prefix=pvdaq%2F2023-solar-data-prize%2F9068_OEDI%2F>`__.  # noqa: E501
 # For more information about the system, see its `OEDI
 # page <https://openei.org/wiki/PVDAQ/Sites/SR_CO>`__.
+#
+# .. warning::
+#    This example requires user-provided credentials to be run at step
+#    :ref:`Fetch weather data <fetch_weather_data>`. Therefore, it is not
+#    executed as part of documentation build process and it's more
+#    susceptible to API changes. Please, report any issues you may find.
 
 # sphinx_gallery_thumbnail_path = "_images/OEDI_9068_daily_timeseries.png"
 import pvlib
@@ -132,6 +138,7 @@
 # %%
 # Fetch weather data
 # ------------------
+# .. _fetch_weather_data:
 #
 # The system does have measured plane-of-array irradiance data, but the
 # measurements suffer from row-to-row shading and tracker stalls. In this

docs/sphinx/source/conf.py

@@ -20,9 +20,9 @@
 # for generating GH links with linenumbers
 import inspect
 
-# import distutils before calling pd.show_versions()
-# https://github.com/pypa/setuptools/issues/3044
-import distutils  # noqa: F401
+# to escape special characters in sphinx-gallery OS-dependant regex
+import re
+
 import pandas as pd
 
 pd.show_versions()
@@ -384,12 +384,19 @@ def setup(app):
 # https://github.com/pvlib/pvlib-python/issues/837
 suppress_warnings = ['ref.footnote']
 
+os_re_sep = re.escape(os.path.sep)
 # settings for sphinx-gallery
 sphinx_gallery_conf = {
     'examples_dirs': ['../../examples'],  # location of gallery scripts
     'gallery_dirs': ['gallery'],  # location of generated output
-    # execute only files starting with plot_
-    'filename_pattern': 'plot_',
+
+    # do not execute gallery examples filenames that begin with noplot_
+    # first group + sep := match folders up to filename
+    # negative lookahead + match anything but sep := match filename (if valid)
+    # https://sphinx-gallery.github.io/stable/configuration.html#parsing-and-executing-examples-via-matching-patterns  # noqa: E501
+    # unix: filename_pattern = '^(.*)/(?!noplot_)([^/]*)$'
+    # win: filename_pattern = '^(.*)\\\\(?!noplot_)([^\\\\]*)$'
+    'filename_pattern': rf"^(.*){os_re_sep}(?!noplot_)([^{os_re_sep}]*)$",
 
     # directory where function/class granular galleries are stored
     'backreferences_dir': 'reference/generated/gallery_backreferences',

docs/sphinx/source/whatsnew/v0.15.3.rst

@@ -42,6 +42,7 @@ Requirements
 
 Maintenance
 ~~~~~~~~~~~
+* Fix some gallery examples not being run. Only gallery examples whose filename begins with ``noplot_`` will be excluded. (:issue:`2790`, :pull:`2792`)
 * Removed unused internal function ``clearsky._is_leap_year`` (:issue:`2768`, :pull:`2813`)
 * Fix documentation builds on runner images lacking link-type timezones. (:issue:`2795`, :pull:`2809`)
 

pyproject.toml

@@ -60,7 +60,7 @@ doc = [
     'matplotlib',
     'sphinx == 7.3.7',
     'pydata-sphinx-theme == 0.15.4',
-    'sphinx-gallery',
+    'sphinx-gallery == 0.21',
     'docutils == 0.21',
     'pillow',
     'sphinx-toggleprompt == 0.5.2',