Speed up documentation builds done via GitHub Actions in CI by caching previous build #2258

Right now our documentation builds currently take ∼10–15 minutes. A consequence of this is that we often have to push a minor change to a reStructuredText file to try to resolve a warning in the documentation, and then wait ∼10—15 minutes to see if it goes through.

It would be really helpful if we could speed up the documentation build in CI. One possibility would be to have a GitHub Action that would cache the output of the previous documentation build, and then rebuild the documentation from that. Doing this would allow Sphinx to only regenerate the documentation pages that correspond to files that have changed, which should greatly speed things up.

There are a few things we would need to be careful about. For example, there will be occasions where we would want to do a fresh rebuild of everything, like possibly when we edit configuration stuff in docs/conf.py and want to make sure that everything gets updated. For that, we could potentially create a label that would make Sphinx rebuild the docs from scratch, or manually remove the cached build. It's also possible that errors could be hidden by rebuilding the docs from scratch. The RTD build should be able to take care of that, in particular if we require that the RTD build doesn't have any warnings.