Summary

Someone writing a Sphinx Gallery example needs to wait a long time for it to build through make html or do make html-skip-subdirs (which requires editing .mpl_skip_subdirs.yaml and still leads to a lot of unhhelpful warnings).

Proposed fix

It isn't easy to figure out how to efficiently rebuild a single example. This use case is important because people developing gallery entries are focused on a single file and have to preview it many times. Also, writing a gallery entry can be a good way for beginners to enter a project but beginners are likely to struggle—but making this experience better will help projects gain contributors. A tweak to the docs would have made things a lot easier for me, and some adjustment to how Sphinx Gallery gets configured might make a better process automatic.

The Sphinx Gallery docs helpfully point out that you can build a single do

sphinx-build -D sphinx_gallery_conf.filename_pattern=plot_specific_example\.py ...

but I found setting include_patterns to also be essential for that goal.

I added the following to conf.py:

include_patterns = ["index.rst",
"users/explain/axes/legend_guide.rst",
]
suppress_warnings = ["toc.not_readable", "ref.doc", "ref.obj", "ref.func", "ref.meth",
"ref.class"]
gallery_dirs = ["users/explain/axes"]

and run with python -msphinx -b html -D sphinx_gallery_conf.filename_pattern=../galleries/users_explain/axes/legend_guide.py . build/html

Each of those tweaks to conf.py was important.

• include_patterns was needed to stop Sphinx from spending a lot of time on unrelated files. Without having the rst file being included, the html never gets built.
• suppress_warnings is nice to add because, while it's understandable that building only one file would trigger a lot of warnings, it's helpful to turn them off so that the relevant ones stand out.
• gallery_dirs drops the build time for a single file by a few seconds, which is nice.

1. I'd like the docs to give these hints on how to build a single file.
2. We could add another build target in the doc Makefile, which would trigger the relevant logic within conf.py.

I'm willing and able to take on both of these tasks and would like to confirm that this approach makes sense before proceeding.