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 ↩

[kandersolar]

I cannot remember exactly why I added that line, but I suspect that the build was failing without it. If the build passes without it, then it's fine with me to remove it 👍

[dgowdaan-cmyk]

Nice detective work tracking down the distutils import history back to #1435 — agreed it looks like a leftover workaround that may no longer be needed. Curious whether removing it locally on 3.12 actually caused any doc build failures for you, or just an ImportError/warning that didn't block the build?

[echedey-ls]

All set up by my side. Feel free to review.

[cwhanse]

I have a mild preference for "noplot" rather than "NX", as the prefix indicating an example that is not executed when the documentation is built. "noplot" negates "plot" which is the prefix for examples that are executed.