Repository navigation
Adds plot_skip_execution config to temporarily disable plot_directive. - #31270
Conversation
|
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. |
|
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. |
|
Sorry this took me a bit, I was at a conference. It looks like
|
|
Hi all, wanted to bump this. |
|
Responded to your comments |
|
Please rebase so that the doc builds work. |
7e4e832 to
0f01f46
Compare
|
I believe I did the rebase, let me know if I did it incorrectly |
0f01f46 to
8378b29
Compare
|
Following up on
This works on all three possibilities, as can be seen in my minimal working example. In The wrinkle here, and this is something we went back and forth on, is that it matches the For my MWE, that's and you can see the three names to match there:
Properly, you can look at the .rst files produced by your apidocs generator and sphinx-gallery: What this doesn't allow you to match, which might be surprising to users is:
|
|
So to clarify: This always uses the .rst file from which the docs are rendered. If the plot directive is in a Python file, e.g. docstrings or Sphinx-gallery example, the .rst filename and location depends on the respective tooling that generates the intermediate .rst representation. Is this correct? If so, that should be added to the description of the option. |
|
For the tests: the fact that I was testing so many variations is I think a legacy of the fact that I initially was using regex and wanted to make sure I understood how it worked. I agree that now that I'm using I also agree that a mark would be better (much easier to use) and an overall "Skip all" would be sufficient for my use case, and it might be preferable to keep it really simple. I'm not familiar with that many examples using a decorator with Sphinx, only Deprecated. If we want to go that route, are there other packages you're familiar with that I can look at as examples?
I see this functionality being used by having some logic in How should I proceed on this? Like I said, I think either of your suggestions (mark/decorator or some sort of global "skip all") work well, and are simpler to use / explain than my current solution, so are preferable. I defer to you all as to what makes the most sense. |
|
If skipall is sufficient to you, let's just do that. That's much simpler than adding markers and we can always add markers later should the need arise. |
b67b208 to
0a1931b
Compare
|
Okay, I went ahead and switched this to now be I kept the logic at the same place, so that the only thing that is skipped is running the code (all the machinery around captions, show code, etc. are unaffected). Happy to move it if that would be better. |
|
Can you please also add a whats_new entry including how to use this from the command line (as @QuLogic noted above)? |
Done, let me know if you have any comments on it. I also added This made me realize maybe |
81d289b to
4fa13ba
Compare
|
Renamed the option to |
plot_exclude_patterns config to selectively disable plot_directive.plot_skip_execution config to temporarily disable plot_directive.
timhoffm
left a comment
There was a problem hiding this comment.
You should squash the commits to fix the PR cleanliness issue. Thevrdtcheck failure in precommit is unrelated and can be ignored.
|
To make sure I understand, since I'm wary about messing with git history, do you want me to squash all the commits? So I'll run: git reset --soft HEAD~12
git commit
git push --force origin sphinext-optionalOr do you just want me to squash the commits that involve the |
|
Yes, that is one way for squashing. Please squash everything into one commit. We don't need the history how we landed here. |
b2eb4c5 to
5505983
Compare
|
Done, I squashed the commit and rebased onto |
|
I took the liberty of updating the version number in the docstring. This landed some place good, thank you for this work @billbrod and thank you for sticking with us through a circuitous review process. |
|
The docs failure is not getting the intersphinx inventory for wx which I'm happy to merge over. |
|
congratulations on your first merged Matplotlib PR @billbrod ! I hope we hear from you again. |
|
Thanks, I'm pleased with where we landed on this! |


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.