Implement Sphinx-Gallery's make html-noplot
#23870
Conversation
|
The speed up is good, the warnings are not. We run with "warnings are errors" because if you do not then we will eventually accumulate a huge backlog of warnings (most of which are things like broken cross references or otherwise broken rst). The best thing would be if SG could detect what images it would make and then drop in a place holder...but I suspect that the only way to detect that is to run the examples which defeats the purpose. Is it possible to use custom warning filters in this mode and only ignore warnings about cross references to the gallery files? |
46331a2 to
55b3991
Compare
|
I did a little digging... The warnings about missing images are Sphinx does have a config option to suppress warnings. "image.not_readable" in this list will suppress the first warning but for all images rather than just the gallery. I can't see the second warning in the list. Note also that this option is marked as experimental. So I'm not really sure where to go from here! |
|
While the error filtering would be amazing, I think as is this is still an improvement over using |
|
Isn't it the case, though, that the Sphinx gallery pain is only felt once? Subsequent doc builds are substantially faster because SG doesnt rerun all the examples? |
dunno, I always use the WARNING: The config value `plot_gallery' has type `str', defaults to `bool'.which is something this PR fixes according to the discussion on sphinx 913 that Ruth linked to. PS. I'd find fixing that in itself super helpful since I totally wasn't sure I was using that flag correctly cause of that error message. |
|
How hard would it be to put a check in our From testing it takes like 7:30 to build the docs from scratch on my system and 1:40 to build them a second time. Running with When you said "A lot" I read "one per image in the gallery", but it is a much more tractable number. A very brute-force way to fix this is to write a script to generate a "This is not the plot you are looking for" or other similar place holder image and then copy it to all these places in the output. At least for the whats_new entries, it also does not seem like the worst thing to have a duplicate copy of the code...it might even be advantageous so old whats new entries do not change when we update an example! I'm not super stoked that we have recommended a way to build the docs that produces so many errors (it makes it harder to see the actual errors we need fixed) and am pretty 👎🏻 on adding a make target that we know is going to fail. As noted above, just absorbing the one-time cost of building the examples is not terrible (we should document that!) and I think there are a number of ways to squash these warnings. |
|
This all feels like workarounds, but may still be a thing we want to do short-term. Long-term I see other ways to increase doc build speed.
|
|
It turns out that SG will automatically create dummy images for you, but you need a comment in each example file telling it how many images to create. So I went through and added enough comments to satisfy all the existing links. In a separate commit for now, so it's easy to revert if needed... |
|
If we wanted to really nail it down, we could have a test that searches through the rst files to find the figure links and checks the required comments are in the relevant examples. Maybe here: https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/tests/test_doc.py |
|
I'm not super happy that we have to manually track the number of images. And then write a test so that we don't get it wrong. This does not feel right. Can we/sg do better? To summarize the issue:
The best solution would be to prevent the warnings in 3), as suggested by @tacaswell. And @rcomer's inspires a possible fix:
This is a great insight. I agree that the "image.not_readable" config is not specific enough. If we are adventurous this might work: We get hold of the above mentioned logger and add a filter that filters out missing image warnings on the images in our gallery directories. |
|
I think if anyone is going to spend time doing something complex, it should be to parallelize the gallery build. If someone really doesn't want to build the gallery, they should just do what @story645 does and run with plots turned off and error-on-warning turned off. However I don't think that should be the recommended way to build the docs (is that really what we are recommending?) |
No, we just document it as an option. The reason I approved this PR in the first place is cause far as I could tell this was the sphinx-gallery replacement for that argument that gets rid of the confusing to me string/bool warning. I don't think providing the make recipe is necessarily recommending that folks use it either, it's just providing an existing option in a more user friendly way. We can always document something like `..Note: we do not recommend this because you may miss important warnings. You must turn off exit on warnings when using this" or we turn off exit on warnings as part of the make recipe. ETA: So the reason I'm advocating documenting/including it even w/ a not recommended note is that there are folks on machines where the docs take a really long for them time to build and therefore they find this argument helpful and it's not a thing that I think is necessarily easily discoverable without knowing it exists. |
|
Great - I'm not suggesting we can't list optional ways to build the docs, just that I wouldn't be happy to see our conf.py getting complicated to magically suppress warnings for an optimization that only has an effect on the first doc build.
Really? That is super fast - my machine must be pretty slow to run python! |
I think it’s far less complicated than the discussion here may suggest. A hand full of lines should do. and if that works we can upstream the code to Sphinx gallery. I mean, logically this is what should happen: in this mode, sg does not provide images. Since this is intentional we don’t want warnings for the missing images. It should be the task of sg to prevent these. Currently, they do it via the dummy crutch, but I think filtering is better (simpler/faster/more user friendly).
Maybe, but you could try a fresh setup of your dev environment. In my case that brought 50% speed up. Not exactly sure why, but I suppose some lib have improved. |
I have a pretty new machine (12th gen i7 with a nvme drive (I have in the past benchmarked this and I/O was a surprisingly big part of this...for a while I did silly things like try to build the docs on a ramdisk...)). I also ran that with py311 which has some decent speed improvements (there has been a lot of work upstream making CPython faster). |
c3d1a35 to
1374e34
Compare
|
Thanks all for your thoughts. Following @timhoffm's suggestion I have added a filter in
Full disclosure: I am doing this on an 11-year-old laptop and it takes over half an hour to build the full docs. It could be argued that it's my own silly fault for trying to do that in the first place! I don't think I ever looked at the "how to build the docs" section of the dev guide until this PR - just saw that there was a |
Absolutely not! It takes about 20+ minutes on my 5? year old machine and I'm not building many backend or any of the font specific examples. That's why I use the flag! And the not building api sounds 👀 'cause I think my machine spends like 10 minutes there. |
|
Thanks a lot @rcomer! This is a great addition. Doc build times are a nuisance and I assume they are discouraging people from working on the docs. Anythinhg we can do to improve that is a win. |
|
I have opened sphinx-gallery/sphinx-gallery#1006 to see if Sphinx-Gallery want to include the filter a their level. |
The make option `-Dplot_gallery=0` is superseeded by `make html-noplot`. While we have removed it from the simple calls (matplotlib#23870), it was still present in examples with multiple options. Remove it here and replace it by a still used option.
The make option `-Dplot_gallery=0` is superseeded by `make html-noplot`. While we have removed it from the simple calls (matplotlib#23870), it was still present in examples with multiple options. Remove it here and replace it by a still used option.
PR Summary
Adds an
html-noplotoption to the Makefile, following the Sphinx-Gallery documentation. With this option the gallery structure is still generated, but we do not get the gallery images. On my laptop this option takes about a third of the time it takes to runmake html. I think this would be useful for contributors who want to check other aspects of the documentation besides the gallery.This option does trigger a lot of warnings, where various rst files link to the gallery images, so I'm not sure whether it makes sense to include the
SPHINXOPTSvariable used in the other options. I have for now.The change to
conf.pyfollows advice at sphinx-gallery/sphinx-gallery#913 (comment).PR Checklist
Tests and Styling
pytestpasses).flake8-docstringsand runflake8 --docstring-convention=all).Documentation
doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).