Fix some gallery files not being executed

[echedey-ls]

• Closes Missing thumbnails in the example gallery #2790
• I am familiar with the contributing guidelines
• I attest that there is no AI-generated material in this PR, just like the good old days
• Tests added
• Updates entries in docs/sphinx/source/reference for API changes.
• Adds description and name entries in the appropriate "what's new" file in docs/sphinx/source/whatsnew for all changes. Includes link to the GitHub Issue with :issue:`num` or this Pull Request with :pull:`num`. Includes contributor name and/or GitHub username (link with :ghuser:`user`).
• New code is fully documented. Includes numpydoc compliant docstrings, examples, and comments where necessary.
• Pull request is nearly complete and ready for detailed review.
• Maintainer: Appropriate GitHub Labels (including remote-data) and Milestone are assigned to the Pull Request and linked Issue.

Other suggestions for the prefix welcome. I left a warning in NX_oedi9068.py to explicitly state it is not run by documentation. I don't really care but I thought it may be useful to hint users before running.

[echedey-ls]

regex ^(?!.*/)*((?!/NX_).)*$ was tested with the following test batch:

# True negatives
/NX_test1.py
/NX_oedi.py
/NX_.rst
/NX_.py
/NX__.py
/home/echedey/Documents/10_Programming/pvlib-python/docs/examples/system-models/NX_oedi_9068.py
# These are considered negatives; I differ a little bit but I don't know how feasible is to make the regex match so
/NX_/hello.py
/NX_what/hello.py
# True positives
/index.rst
/plot_test1.py
/plot_oedi.py
/oedi.py
/__lalilailola__.py
/white spaces.py
/special chars?.py
/is_middle_NX_detected.py
/home/echedey/Documents/10_Programming/pvlib-python/docs/examples/system-models/oedi_9068.py

https://regex101.com/ - remember to change to python flavor if you try it.

Edit: updated regex and test data at 00h30 UTC 2026-06-19

Last edit: I invite anybody on windows to try this out, I only checked on linux which is enough for the readthedocs builds, but you may want to check windows users can use this locally too.

[echedey-ls]

I've tested on Windows. Now it works flawlessly; NX_ prefix only applies to filenames (not the start of any folder, too, I was wrong when I reported otherwise, if you ever saw that).

We have 41 .py examples:

Counted via command line

~/Documents/10_Programming/pvlib-python/docs fix_some_examples_not_run_by_sphinx* ≡
❯ find examples -mindepth 1 -type f -name "*.py" -printf x | wc -c
41

And both in linux and windows it shows 40 of them are executed (while also leaving oedi example in the web):

sphinx-gallery report on build - Linux

Sphinx-Gallery successfully executed 0 out of 0 files subselected by:

    gallery_conf["filename_pattern"] = '^(.*)/(?!NX_)([^/]*)$'
    gallery_conf["ignore_pattern"]   = '__init__\\.py'

after excluding 40 files that had previously been run (based on MD5).

sphinx-gallery report on build - Windows

Sphinx-Gallery successfully executed 40 out of 40 files subselected by:

    gallery_conf["filename_pattern"] = '^(.*)\\\\(?!NX_)([^\\\\]*)$'
    gallery_conf["ignore_pattern"]   = '__init__\\.py'

after excluding 0 files that had previously been run (based on MD5).

I hope you like the set of changes I propose here. Don't hesitate to point anything out, from maintenance burden to whatever else that comes to your mind. I think it would be great to have this issue solved in the short term to fix the latest documentation branch on readthedocs.

[echedey-ls]

This package was deprecated for quite some time, and finally got removed in CPython 3.12 ¹.
Our pipeline runs on CPython 3.12 too ², but I guess readthedocs installs some stub to avoid breaking build processes - pure speculation from my side.

I've had to remove the import line in my python setups to compile the docs, both 3.14 (linux) and 3.12 (win). In both cases, I only installed our [doc] optional dependencies.

It was introduced quite some time ago, in #1435. The specific commit is 76972a8 (#1435). I couldn't trace what it attempts to solve, to see if it's now fixed (at pandas, probably?). Nowadays normal people use imporlib.metadata, so my guess is that we are looking at is a digital fossil. Wondering if anybody (presumably @kandersolar or @mikofski) knows if we can safely remove this.

Footnotes

1. https://docs.python.org/3.12/library/distutils.html ↩

2. https://github.com/pvlib/pvlib-python/blob/0f7a2051ca154055e5b3f1ec6b3f4cd07f870b1e/readthedocs.yml#L14 ↩