Improve docs build times

[tcmetzger]

Building the docs can take a lot of time, both with CI and when building locally. Two thoughts:

• It would be helpful to add an option only to build parts of the docs when building locally (only build the user guide, instead of always building all docs, for example). This could be something like a command-line argument or an environment variable.
• It would be great to cut down the overall docs build time (including CI)

cc @bryevdv

[mattpap]

It would be great to cut down the overall docs build time

Any initial ideas?

[bryevdv]

There are two cases: speeding up local development, and speeding up CI

The first is probably somewhat easy to make some quick improvements for. We can add flags to suppress different parts of the build, i.e. don't build the sitemap, or the formatted source, or even skip building plots. So if you just need to see how some new edited text renders, that should help significantly.

Additionally, I think our invalidation of built plots is probably overly aggressive. I suspect it is possible to make things smarter in ways that will not trigger full rebuilds of plots as often. That would also help local development.

Improving CI is another matter, and would require some actual investigation. It's possible we are doing some things with sphinx in ways that could be more intrinsically efficient, or it's even possible that there are improvements we could make to sphinx itself and push upstream. But this is a more involved case, for sure.

[tcmetzger]

This thread seemed to be another great candidate for "transfer to discussion"! Based on what we have discussed so far, I have created two specific issues:

1. An issue to add flags to suppress different parts of the build ([FEATURE] Add flags to speed uplocal docs build #11270)
2. An issue to make invalidation of built plots less aggressive (Make invalidation of built plots less aggressive for local docs #11271)

I believe improvements to the CI would warrant more discussion first, so I have not opened an issue on that.