Conditional documentation builds

Some projects have long build times for documentation; but, many PRs don’t modify the documentation. Does anyone have any recommendations or best practices about how to configure the CI system (e.g., if you are using GH actions) so that the build is only triggered if the PR modifies the documentation?

1 Like

One idea would be to cache the sphinx build directory across CI runs. In principle you would then benefit from sphinx’s build caching, which might help especially for the case where the documentation doesn’t change at all. Of course, the devil’s in the details so I’m not sure how well this would work in practice.

1 Like

I never managed to have Sphinx build caching working in CI. I don’t know how the mechanism works exactly but seems like there is more than just files being present. Seems like timestamp and other things need to be aligned. I had some PR attempts for that on SciPy and I and others that pass by could never make it work. Which is stupid as it should work.

1 Like

For projects using Read the Docs, see discussion at Build documentation PR previews only if files under a path have changed · Issue #8545 · readthedocs/readthedocs.org · GitHub and especially my last comment there. Feel free to upvote and also drop a message.