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.
Please let us know if (and how) you use AI, it will help us give you better feedback on your PR.

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:

• Should there be examples of showing some matches in the user-facing docs somewhere? Given that "matching" works differently for fnmatch and regex (though fnmatch behaves the same as glob, right?), an example or two might make expected behavior more obvious. If so, does this belong right in the docstring of plot_directive.py or is there somewhere else?
• Related to the above, using fnmatch means that you'll have to use a lot of wildcards. This is fine, but took me a second to realize as I switched from regex. Maybe that will come naturally to users who aren't first thinking in regex, but I wanted to flag it.

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 full_match was only added in python 3.13, so we shouldn't use that, right? (As matplotlib supports 3.10 and up.)

match looks like a good solution, so I've gone ahead and changed this to use that method instead.

Hi all, wanted to bump this.

Responded to your comments

Please rebase so that the doc builds work.

I believe I did the rebase, let me know if I did it incorrectly

Following up on

I'm not clear, but assume this works only for documentation source files (i.e. .rst files), not for plot directives in docstrings and not for sphinx-gallery input files. Is that correct?

This works on all three possibilities, as can be seen in my minimal working example. In conf.py, you can see the options required to skip the different possibilities (that should be runnable, I ran it with uv run make html -C docs from the root directory)

The wrinkle here, and this is something we went back and forth on, is that it matches the name of the path (in pathlib's terms), so it excludes all preceding directories. The easiest way to figure out the names to match, for me, was to do a build excluding nothing, and then look at the plot_directive/ folder in the sphinx build directory.

For my MWE, that's docs/_build/plot_directive, which looks like:

and you can see the three names to match there:

• mpl_sphinxext_test: docstring in the package, because I put it in mpl_sphinxext_test/__init__.py
• test_alignment: sphinx-gallery, that's the name of the .py file in the gallery's example directory
• index: rst file in the docs, that's the name of the file itself.

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:

• The containing directory (so you can't match api/ or auto_examples/ to exclude all of sphinx-gallery or API docs), because of how pathlib match works
• The function name for API docs, since that doesn't get represented in the file name (if you use another package to generate your API docs, it's possible it would; here I used sphinx.ext.apidoc, which uses sphinx.ext.autosummary)

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.

On a general note: is filename a good (I.e. easily usable) filter? The alternative could be to give authors the ability to give plots markers and filter on them, similar to pytest markers. In the simplest case you could have a “slow” marker and just exclude them.

Sorry to come in after must of the discussion is done, but I have some skepticism of this, particularly as the usecase is to temporarily edit the conf.py files during development.

Would controlling this via an ENV be better (as that is easier to ensure is transient and not accidentally committed)? Do we need per-file or just "please turn off all plots" enough? If the goal is to opt-in to only running a single plot directive would an "must match" test be better?

particularly as the usecase is to temporarily edit the conf.py files during development.

That's not necessary for Sphinx options; you can pass -Dplot_exclude_patterns=foo*,bar to sphinx-build to override conf.py.

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 pathlib.match, that it's unnecessary to test so many variants.

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?

particularly as the usecase is to temporarily edit the conf.py files during development.

I see this functionality being used by having some logic in conf.py that checks an environment variable or using the -D option that @QuLogic mentioned.

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.

Okay, I went ahead and switched this to now be plot_skip_all, a boolean that just skips all plot directives, rebased onto main, and made the test a single test.

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)?

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 .. versionadded:: 3.11 to the parameter, let me know if that was incorrect.

This made me realize maybe plot_skip_all isn't the best name? Maybe plot_disable or plot_tmp_disable or something?