diff --git a/docs/examples/system-models/oedi_9068.py b/docs/examples/system-models/NX_oedi_9068.py similarity index 96% rename from docs/examples/system-models/oedi_9068.py rename to docs/examples/system-models/NX_oedi_9068.py index 9a73bfa9ce..f447c123da 100644 --- a/docs/examples/system-models/oedi_9068.py +++ b/docs/examples/system-models/NX_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 `__. +# 9068 `__. # noqa: E501 # For more information about the system, see its `OEDI # page `__. +# +# .. warning:: +# This example requires user-provided credentials to be run at step +# :ref:`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 diff --git a/docs/sphinx/source/conf.py b/docs/sphinx/source/conf.py index defbb2cdd0..acbe33936c 100644 --- a/docs/sphinx/source/conf.py +++ b/docs/sphinx/source/conf.py @@ -20,6 +20,9 @@ # for generating GH links with linenumbers import inspect +# to escape special characters in sphinx-gallery OS-dependant regex +import re + # import distutils before calling pd.show_versions() # https://github.com/pypa/setuptools/issues/3044 import distutils # noqa: F401 @@ -384,12 +387,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 NX_ + # 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: gallery_conf["filename_pattern"] = '^(.*)/(?!NX_)([^/]*)$' + # windows: gallery_conf["filename_pattern"] = '^(.*)\\\\(?!NX_)([^\\\\]*)$' + 'filename_pattern': rf"^(.*){os_re_sep}(?!NX_)([^{os_re_sep}]*)$", # directory where function/class granular galleries are stored 'backreferences_dir': 'reference/generated/gallery_backreferences', diff --git a/docs/sphinx/source/whatsnew/v0.15.3.rst b/docs/sphinx/source/whatsnew/v0.15.3.rst index 87ded069ee..d46faf1c90 100644 --- a/docs/sphinx/source/whatsnew/v0.15.3.rst +++ b/docs/sphinx/source/whatsnew/v0.15.3.rst @@ -38,7 +38,7 @@ Requirements Maintenance ~~~~~~~~~~~ - +* Fix some gallery examples not being run. Only gallery examples whose filename begins with ``NX_`` will be excluded. (:issue:`2790`, :pull:`2792`) Contributors ~~~~~~~~~~~~ diff --git a/pyproject.toml b/pyproject.toml index f359cc846d..002ff1394f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -59,7 +59,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',