Repository navigation
ENH,DOC: Only render plot directive formats the Sphinx builder can use - #32584
agriyakhetarpal wants to merge 12 commits into
Conversation
Co-authored-by: Melissa Weber Mendonça <3949932+melissawm@users.noreply.github.com> Co-authored-by: Aditi Juneja <91629733+Schefflera-Arboricola@users.noreply.github.com>
Co-authored-by: Melissa Weber Mendonça <3949932+melissawm@users.noreply.github.com> Co-authored-by: Aditi Juneja <91629733+Schefflera-Arboricola@users.noreply.github.com>
Co-authored-by: Melissa Weber Mendonça <melissawm@gmail.com>
timhoffm
left a comment
There was a problem hiding this comment.
Thanks, this is really a great finding! 🚀
One question for understanding: Is the following correct?
Before we just rendered every format in plot_formats and the renderer just picked the suitable one - and exactly only one. In practice a user would put all formats they need in plot_format.
Exception: With plot_html_show_formats the HTML builder uses all formats because it embeds them as links.
This is inefficient as more files are created than needed.
Also, we may have overlapping concerns in plot_formats: Say I want png and svg in HTML with plot_html_show_formats, but I also want latex, which needs pdf - that pdf is inadvertedly also picked up by the HTML reader.
The proposed solution is to subset plot_formats with the supported formats of the builder.
Wouldn't it be cleaner to turn plot_formats into a per-builder dict? i.e.
default_plot_formats = {
'html': ['png'],
'latex': ['pdf'],
...
}and
- if
plot_formatis given and a dict, useplot_format[builder] - if
plot_formatis given and not a dict, useplot_formatas is (backward compatibility - maybe warn? - otherwise use
default_plot_formats[builder]
Optionally, warn if the formats contain a file that is not supported by the builder.
Advantage: There's less magic in selecting the files, configuration is clearer and can be explicitly done per builder.
Co-Authored-By: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
d38b523 to
1b25a48
Compare
|
Hi @timhoffm, thanks for the feedback!
Yes, this is correct! A per-builder dict seems sensible to me, too, so I added that in 8a12b54, along with a warning for unsupported file formats in 5b9a15b. Could you PTAL when you have a chance? I kept the default as the current list instead of the dict, because there are currently many projects using a list (see code search results, though there is a lot of noise too), and I think it might be better to not bother them with a warning :D The dict is purely additive, so that projects can switch to it at their convenience. However, I can still add a warning suggesting they switch their lists to a dict if you insist. Additionally, I asked Claude Code to review my diff, and it caught a latent regression that the PR's behaviour surfaced, namely that we now need to record which documents contain plot directives. This is because it found that a PDF build which ran after an HTML build, i.e., with a reused doctree directory, failed to find previously generated PDFs (when we were building all formats, prior to this PR), and as a result ended up embedding low-quality raster PNGs instead of vector PDF figures into the PDF output. This is the case, for example, for users building documentation with plot directives on Read the Docs with PDF outputs enabled, since builds there rely on such caching. I have fixed this in 9c07cff. Thanks again! |
|
There's a decent amount of complexity here. I'll try to think this through from scratch, because I feel incrementally attaching more and more logic makes this hard to comprehend. Simple/standard case: one build
ValidationFor the selected builder, it should be verified that Multiple buildersThe cache reuse across builders complicates the situation. I can see two approaches: a. as proposed above, track the files and build missing files in the second run. I'm undecided here. (a) is a bit cleaner, but more complex and costly. (b) would be as simple as an optional I'm leaning towards (b) What do you think? |
I would not assume that to be the case for Sphinx, cf, e.g., sphinx-doc/sphinx#12646 (comment) |
While this is true, I'd dare to take the risk. This only affects doc builds, so no production code. If this gets broken, we can quickly add a fix (worst case: hardcoding the supported formats). The build speed up is defitively worth it. |
PR summary
This PR makes the
.. plot::directive render only the formats the active Sphinx builder can use. In practice, this means that the Sphinx HTML builder keeps the first entry of the list, and the remaining entries are kept only whenplot_html_show_formatsisTrue. This is since the HTML template only reaches those files through the download links it emits in that case.Every other Sphinx builder keeps the entries whose MIME type appears in its
supported_image_types, so a LaTeX/PDF build would get its PDFs, but a texinfo build would not. The MIME type comes fromsphinx.util.images.guess_mimetype: https://github.com/sphinx-doc/sphinx/blob/035a07c32c3241fd3356f4d827800c1f88525272/sphinx/util/images.py#L69Doing this showcases some speedups for projects that set
plot_html_show_formats = Falseand leaveplot_formatsat its default. Until now, their HTML documentation builds also wrote a PDF and a high-resolution PNG of every figure into theplot_directivebuild directory, which were left redundant. The rendered output is unchanged across builders. Only the contents of that intermediate directory differ.In Matplotlib's own
doc/conf.py, I noticed that this was being worked around by inspecting the command-line arguments for the build target. Since the directive now does the selection, we include a more principled fix for the same.This PR is a continuation/generalisation of what @Schefflera-Arboricola, @melissawm, and I recently did for the PyWavelets project, via PyWavelets/pywt#884, to speed up its documentation builds. I primarily found this scope for optimisation via the
sphinx-benchmarkproject, which @Schefflera-Arboricola developed and released as part of her internship at Quansight this year – where @melissawm and I were involved as mentors. All credits go to @melissawm for suggesting that this could possibly be generalised in Matplotlib itself, after which we discussed it, and I took over the change. Also, please read Aditi's blog post; it's a great read! https://labs.quansight.org/blog/sphinx-benchmark.Through a GitHub search of public
conf.pyfiles, mostly coordinated with a Claude Code Opus 5.5 session, I found around 330 projects in the affected configuration, while SciPy, pandas, seaborn, scikit-learn, and several others already avoid the extra cost by pinningplot_formatsto PNG by hand.That said, however, by the means of some wilful cherry-picking (:P), I found speedups for some projects. Here is a benchmark table, via results from
hyperfine, with some runs on my MacBook Pro (M3 Pro) if that is useful:Benchmark results
Each project's documentation website was built with its own pinned requirements and its own build command. The only difference between the two variants is this PR's diff applied to the installed
plot_directive.py. To ensure the correctness of this benchmark, I (i) checked patched runs and noticed that they had zero written PDFs, and (ii) I always ran clean builds with no.pycfiles or previously-stored doctrees by entirely wiping any built/stored folders withgit clean -xdff.make htmlmake htmlsphinx-build -b htmlmake htmlmake htmltox -e docscommandspin docsHere, the savings track how expensive the figures are to render as PDF. We do not count how many figures there are or how large the files end up after being built.
pcolormeshfigures.getdist, there are a number of grids drawn of filled contours.AI Disclosure
My search of public GitHub projects was coordinated with a Claude Code Opus 5.5 session. I prepared an initial draft of the changes to the directive. Through a review, the agent found Sphinx's
util.guess_mimetypesmethod for me, which I did not know about—I was hardcoding a map of file formats and their MIME types initially—since the method is not really documented as such in the Sphinx documentation website, but it is still de facto part of the public API.I also consulted this session to quickly set up the projects for development by following their developer guides and installing their dependencies as documented by them, and setting up the benchmarking infrastructure required on my machine between runs. I provided instructions to the agent on how to do so reliably via
hyperfine, including the commands. I have provided them below if you would like to reproduce the results, working with your own agent:Benchmarking instructions and how to reproduce
For any project using the plot directive:
Per project, we found that PyWavelets, qutip, and data-morph used
make htmlwithmake clean. getdist usedsphinx-build -T -b html docs/source docs/_build/htmlwithrm -rf docs/_build. Qiskit usedsphinx-buildin itstox.inidocs environment without-W, after a one-timemake cheaderanddoxygen docs/Doxyfile, withrm -rf docs/_build. NumPy usedspin docswithSPHINXOPTSunset to avoid-W, removingdoc/buildand the generated reference directories between runs.PR quality check