Adds plot_exclude_patterns config to selectively disable plot_directive.#31270
Adds plot_exclude_patterns config to selectively disable plot_directive.#31270billbrod wants to merge 6 commits intomatplotlib:mainfrom
plot_exclude_patterns config to selectively disable plot_directive.#31270Conversation
|
Thank you for opening your first PR into Matplotlib! If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks. You can also join us on gitter for real-time discussion. For details on testing, writing docs, and our review process, please see the developer guide. We strive to be a welcoming and open project. Please follow our Code of Conduct. |
| error will be raised. | ||
|
|
||
| plot_exclude_patterns | ||
| List of regex patterns to check against to selectively skip plot |
There was a problem hiding this comment.
My standard question when matching file patterns 😄: Do you really want regular expressions or are wildcard patterns (fnmatch) sufficient/better?
There was a problem hiding this comment.
I was not aware of fnmatch -- that looks sufficient (and easier) to me! I'll update the PR to use that instead.
|
|
||
| plot_exclude_patterns | ||
| List of regex patterns to check against to selectively skip plot | ||
| directives. If any pattern matches the name of the file containing the |
There was a problem hiding this comment.
Is filename enough or do we need a relative path?
There was a problem hiding this comment.
Oh relative path might be better. That increases the chance of false positive matches, but makes it easier to do a simple "disable all plot directives found in the API documentation", which is nice. I'll do that
There was a problem hiding this comment.
You may also want to check https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.full_match and https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.match, which may be more convenient than fnmatch.
|
Pushed changes following @timhoffm suggestions. Some questions this raised for me:
|
|
The failing tests look unrelated to my changes, should I try and fix them? |
|
Yes the failing tests are unrelated. On "a lot of wildcards": As mentioned above, you may also want to check https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.full_match and https://docs.python.org/3/library/pathlib.html#pathlib.PurePath.match, which may be more convenient than fnmatch. |
2 participants
PR summary
I opened a discussion on discourse asking whether it was possible to temporarily disable the plot_directive, and was told by @timhoffm that "There is currently no clean way of doing this. One could add a config value. It’s not important enough that I’d work on this myself, but I’d accept a PR for it." This is my attempt at that change.
Inspired by myst-nb's
nb_execution_excludepatternsconfig option, this allows users to specify in their sphinx configuration a list of patterns to selectively avoid running some plot directives. The goal is to speed up build time when developing, especially when making changes to project documentation. It does this in a simple way, by checkingre.matchagainst theoutput_basefor the created plots for all patterns in the list. If any match, we do not run the code, setresult = [(code, [])], and continue. Settingresultin this way makes it so the appearance in the built docs is the same as if an error was encountered: code is displayed if so configured, no associated plot.function_nameor something more specific, but it looks like that is often not visible to the sphinx extension, especially when building examples found in docstrings (which is my most common use case).re.fullmatchagainstoutput_base, but it seems to me that the full output_base might be difficult for a user to predict. Using justre.matchmay be over-zealous, but given that this is intended to speed up builds during development (not during production), false positives seem more acceptable to me.nb_execution_excludepatterns) are most common for filenames, and the use ofre.matchmeans that simple matches (e.g., just"plot") will function as a substring check, while still allowing for more complicated logic.plot_exclude_patterns(with the underscore) rather thanplot_excludepatterns(which would match myst-nb's value) to be more consistent with the naming pattern of the other config values.AI Disclosure
No LLMs were used in this contribution.
PR checklist
plot_directive.py, from grepping for the other config values.