[doc][ci] Skip RTD builds for PRs that don't touch doc sources (ray-project#63431)

## Description

Adds a `build.jobs.post_checkout` block to `.readthedocs.yaml` that
exits with code 183 on PR ("external") builds when the diff doesn't
touch any files that affect documentation output. Tag and branch builds
(master, stable, etc.) always run.

## Why

Today, every PR to `ray-project/ray` triggers a full Sphinx build on
Read the Docs, regardless of what the PR touches. A PR that only changes
C++, Java, Bazel, release tooling, or CI config produces the same docs
build as a PR that rewrites `doc/`.

When several PRs land in quick succession, this overflows the project's
concurrent build slots on RTD. RTD's `finish_inactive_builds` periodic
task then marks the older queued builds as `FAILED` with the message
*"This build was terminated due to inactivity"* (see
[readthedocs.org#4386](readthedocs/readthedocs.org#4386)
— the name is misleading; the build isn't inactive, it just couldn't get
a worker within ~1080 seconds). Contributors then see red checks on
their PRs that have nothing to do with their changes.

[Auto-cancellation of older builds for the same
PR](https://blog.readthedocs.com/cancel-old-builds/) has been on by
default in RTD since October 2022, but that only helps when you push
twice to one PR — not across multiple open PRs. This change complements
that by reducing the load from cross-PR concurrency.

## What the filter does

On every PR build, it computes the diff against `origin/master` and
exits 183 — RTD's [skip-build
sentinel](https://docs.readthedocs.com/platform/stable/guides/build/skip-build.html)
— only when **none** of the changed files match:

- `doc/` — Sphinx sources, BUILD files, doc-only requirements.
- `python/ray/` — anything `autodoc` could pull (kept intentionally
broad).
- `rllib/` — same.
- `.readthedocs.yaml` — this config itself, so changes to it always
test.

If even one file falls in the allow-list, the build runs as before. If
the diff can't be computed (shallow clone, fetch failure), the build
runs.

## What this skips in practice

PRs that don't touch any of the four paths above. Concrete examples:

- C++ / Cython changes under `src/`, `cpp/`.
- Java changes under `java/`.
- Bazel changes under `bazel/`, top-level `BUILD.bazel`, `WORKSPACE`.
- CI changes under `ci/`, `.buildkite/` (except
`.buildkite/doc.rayci.yml` which isn't read by Sphinx but is excluded
from the allow-list since it doesn't change RTD output).
- Release tooling under `release/`.
- Docker changes under `docker/`.
- Top-level scripts and configs.

## What still triggers a build

- All content under `doc/`.
- Any `python/ray/**` change, because `autodoc` could pick it up.
- Any `rllib/**` change, same reason.
- The RTD config itself.

The filter is deliberately conservative — broad inclusion, narrow
exclusion. Better to do an unnecessary build than to miss a doc change.

## Test plan

- Manual trace of the bash logic against representative paths: ✅ passes
(Ray serve, RLlib, doc content, `.readthedocs.yaml`, mixed PRs all
trigger BUILD; Java+C++, Docker, release, `python/setup.py`, empty diff
all SKIP).
- YAML syntax validated locally with `yaml.safe_load`.
- This PR itself touches `.readthedocs.yaml`, so it will exercise the
BUILD path on the RTD preview.

## Future work

If queue pressure persists after this lands, two further levers:

1. Narrow the `python/ray/**` allow-list to exclude paths that don't
appear in any `autodoc` directive (`python/ray/tests/`,
`python/ray/_private/` candidates). Higher maintenance cost.
2. File an RTD support request to ask about the project's
concurrent-build limit on the current plan.

## Related issues

None linked.

---------

Signed-off-by: Douglas Strodtman <douglas@anyscale.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 2 people

.readthedocs.yaml

@@ -10,6 +10,37 @@ build:
   os: ubuntu-24.04
   tools:
     python: "3.10"
+  jobs:
+    # On PR builds, skip the Sphinx build when the PR doesn't touch any
+    # files that affect documentation output. Reduces queue pressure on
+    # the shared RTD build slots when several PRs are open at once.
+    # Tag/branch builds (master, stable, etc.) always run.
+    # See https://docs.readthedocs.com/platform/stable/guides/build/skip-build.html
+    #
+    # Some constructs are avoided deliberately because RTD's job runner
+    # silently drops scripts that contain them: use echo (not printf
+    # with a backslash-escape format string), avoid backslash escapes
+    # in general, and keep shell comments out of this block so that
+    # backticks/$() inside comments don't confuse the preprocessor.
+    post_checkout:
+      - |
+        if [ "${READTHEDOCS_VERSION_TYPE:-}" != "external" ]; then
+          echo "Not a PR build (version type: '${READTHEDOCS_VERSION_TYPE:-unset}'); building docs."
+          exit 0
+        fi
+        git fetch --depth=500 origin master 2>/dev/null || true
+        if ! git merge-base origin/master HEAD >/dev/null 2>&1; then
+          echo "Could not determine merge-base with origin/master; building docs to be safe."
+          exit 0
+        fi
+        if git diff --quiet origin/master...HEAD -- doc/ python/ray/ rllib/ .readthedocs.yaml; then
+          echo "No doc-affecting files changed in this PR; skipping Sphinx build."
+          echo "Files changed in PR:"
+          git diff --name-only origin/master...HEAD
+          exit 183
+        fi
+        echo "Doc-affecting files changed; building docs. Changed doc-relevant paths:"
+        git diff --name-only origin/master...HEAD -- doc/ python/ray/ rllib/ .readthedocs.yaml
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx: