Repository navigation
[MNT]: Idea to accelerate docs contributions with Build changes only docs. #22956
Description
Summary
Contributing small docs changes has one bottleneck in my perception: CircleCI takes LONG to build new changes in examples.
When I execute the python script locally, it takes about 0.2 seconds.
The CircleCI docs build takes more than 30 minutes.
I know that the sphinx rendering must also take some seconds, but it would be amazing if there was a way to bring the build time down to e.g. only 1 minute by only rendering relevant parts of the docs.
This could accelerate the review process a lot.
Proposed fix
Here is an idea: Only nodes that connect to green lines are rendered, everything else is ignored.
In a pull request, it can look like this: In every new commit, the (not yet existing?) GitHub action Build changes only docs is triggered.
This action will execute the above diagram.
For the current complete docs build with CircleCI, I see two options:
- It could be additional active all the time.
- It could be activated after the iteration phase in the last commit, to make sure that the whole docs build without error. This activation could be triggered e.g. when a pull request is getting the "Approved" status, or when there is a certain keyword in the commit. I would prefer the later one, as this saves resources.
Note, that this is issue is not a Matplotlib specific, but also applies to other rendering intensive docs like napari, manim and scikit-image.
Activity
timhoffm commentedon May 2, 2022
Speeding up doc builds is highly desirable. If this could be made to work this would be awesome.
You are very welcome to dig into the build process and try to make it faster. However, I suppose this is more complicated than one thinks. A very basic distinction could be made whether changes are in examples (generated via sphinx-gallery) or the api docs or other .rst pages. Then build only that part of the docs. However, even there, we have cross-references which may be broken if other parts of the docs are not available. One could alternatively, try to cache the doc build of the main branch and only do incremental builds based on this cache for the feature branches. That's faster but for some reason even a rebuild without changes takes some minutes (which IMHO should be possible much faster).
timhoffm commentedon Apr 4, 2024
Current CircleCI build times are around 22min, so slightly better than above, but still annoyingly slow.
Nevertheless, partial doc builds are difficult and I don't think we have the capacity or competency to pull this off. This may be good for a Numfocus small development grand.
jklymak commentedon Apr 5, 2024
We now have
make html-skip-subdirs(see https://matplotlib.org/devdocs/devel/document.html#build-the-docs). That works really well to speed things up if you are doing lots of work in one subsection of the docs. Of course we cannot do that in CI.tacaswell commentedon Apr 5, 2024
I question the value of a "broken" docs build on CI (one of the things that is most likely to go wrong is the cross links). While it might be possible to automaticaclly generate an exclude file that blanks everything but the files change + their direct parents, but I don't think it is possible to sort out which files we would need to include to make all the cross references (recursively?) work would require building the docs, which defeats the purpose.
I think the path to speeding up the docs build is to get clever with circleci caching and let PRs do incremental builds. I would propose the rules:
We may also need a mechanism to clear the cache on a PR if it makes changes that break incremental builds. a "no-doc-cache" label is probably the easiest way to pass information from the Github UI -> the CI jobs.
timhoffm commentedon Apr 5, 2024
I also believe there’s some significant inefficiency in Sphinx and maybe the pydata-sphinx-theme. Also, figrure/Axes creation time should be a relevant quantity because of all the examples.
Unfortunately, improving any of these is a hard problem at least of the size of a small development grant.
AlexSzatmary commentedon Apr 7, 2024
I think that the improvement would best happen within Sphinx. This Sphinx issue gives some explanation for why CI builds of Sphinx can take a long time.
timhoffm commentedon Jan 20, 2025
Current CI doc builds are down to 11-12min due to some other optimizations, which is okish and faster than some unit test runs.
One thing to note is that we have ~3min infrastructure time:
The actual doc build is 7.5-8min.
One “partial” build that could help and should not produce broken doc links would be to not run the Sphinx gallery examples (https://sphinx-gallery.github.io/stable/advanced.html#id4) if they have not been modified. This would save us several hundred plots, which I assume are some minutes in doc build time.
Edit: Test results from #29493
The pure build time was 4min compared to 7.5-8min previously. So there's a potential saving of ~3.5-4min. However, such build still produces warnings in the form of
because we reuse figures from the gallery via the
.. figure::directive such asmatplotlib/doc/users/prev_whats_new/whats_new_1.0.rst
Lines 29 to 32 in 06548d2
These would need fixing one way or the other.
Test doc build time on CI without sphinx-gallery
SilverRainZ commentedon Jun 5, 2025
Hi all, I am the author of https://github.com/sphinx-notes/pages, a GitHub Action for building Sphinx documentation with incremental build support. Recently, I split the "incremental build support" into a single small script and I'm verifying that it's universal.
I am glad to help speed up the building of the matplotlib docs. Now I am testing in my personal CircleCI workspace. Once I have good news, I will file a PR.