DOC: Add a release mode tag #20730
DOC: Add a release mode tag #20730
Conversation
|
Seems good, but can we document the tag in the developer guide so folks can build the full-res version? |
|
I have a slight preference that default should be a full build and a "dev mode" tag should be used for the reduced version. This may also have the advantage that we could later add additional variants (e.g. maybe it may make sense to have different settings for CI and lokal builds). There can only be one release build but possibly different shortcut variations. |
|
I suppose we could expand it, but I think the fast build is the one most developers would like by default. Most of the addons don't affect things for test builds (except maybe 2x images if you have a hidpi screen?) |
|
I think there is a compelling argument to keep the HiDpi, as it does affect how the docs appear. I also think it is not a huge slowdown, if at all. (Perhaps a sad testament to how efficient we are otherwise if more than twice the i/o doesn't affect doc build speeds very much, or a happy testament to disk caching) |
OT: It would be quite beneficial if somebody could dig into why the docs build takes so long. I started once but didn't have time to follow up. From my observation, more than have the time is spent in sphinx gallery, which may or may not be surprising because we have lots of examples. Part of that may fall back on us because the gallery has to generate several hundreds of figures, and we know we're quite slow with figure creation. But it would be really helpful to see where the time goes and be able to speed up doc builds by that. (One a tangent, I'd also like to speed up incremental doc builds so that I can check faster what I'm writing.) Could we e.g. get a small dev grant for someone to speedup or doc builds (maybe also by improving sphinx / sphinx-gallery)? IMHO that would be a significant improvement for the development process. |
|
I'm ok with sticking to the release mode tag. Agreed that we should keep HiDPI if it's not a significant performance impact. |
|
Bumped to draft for now... |
This toggles defaults for the image compression, HiDPI images, theme navigation, and analytics.
But not for PRs.
398972f to
3e29c69
Compare
…730-on-v3.5.x Backport PR #20730 on branch v3.5.x (DOC: Add a release mode tag)
DOC: Add a release mode tag
DOC: Add a release mode tag
PR Summary
This adds a release mode tag, which encapsulates all the things we disabled for CircleCI, as well as other things we'd put in tagged release docs. It disables these by default, so local development will be quicker as well. And then it re-enables release mode when building devdocs.
This covers image compression, HiDPI images, the theme navigation, analytics, and plot directive formats.
PR Checklist
pytestpasses).flake8on changed files to check).flake8-docstringsand runflake8 --docstring-convention=all).doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).