Build documentation PR previews only if files under a path have changed

It would be helpful if we could optionally configure a path to our documentation, and have ReadTheDocs only build previews of the docs if files underneath that path were changed. I’d imagine a configuration box in the Admin panel that was something like

Build PR previews only for changes under folder: docs/

For documentation builds that take a while to build, this would reduce the time for PRs that only change code, but no docs, which is probably quite a lot of PRs! I think that it would also reduce the load on ReadTheDocs build servers, since a documentation change is probably more rare than a code change.

(note: I couldn’t find a “feature request” issue template, which makes me wonder if this is not a good place to open suggestions like this, I am happy to direct this issue elsewhere if that’s better)

[astrojuanlu]

I think we could set reasonable expectations like

• Tracking the docs/ directory doesn’t mean that the documentation can’t change by other means. This is true for source code docstrings but also dependencies, external data, and possibly other factors.
• This would only apply for pull request builds, and there would always be a escape hatch to force a build
• Normal versions wouldn’t have this feature and always build on commit

Does this sound like a useful thing?

[humitos]

There are different reasons for that. Mainly, I think it was because it was too complex to it right and handle all the edge cases (as @astrojuanlu mentions) and users would be pretty confused.

With the proposed implementation, we are delivering this responsibility to the user itself. The user is responsible to guarantee the check is correct for their own scenario. As it’s using just an exit code from a custom command, it’s pretty flexible to cover most of the use cases and people can write just a simple command or a complex Python script.