[Docs] Reinstate docs build gate for PRs (#59411)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

.github/mergify.yml

@@ -5,7 +5,6 @@ pull_request_rules:
     - label != stale
     - -closed
     - or:
-      - files~=^[^/]+\.md$
       - files~=^docs/
       - files~=^examples/
   actions:

docs/contributing/README.md

@@ -135,6 +135,9 @@ API_AUTONAV_EXCLUDE=vllm mkdocs serve  # API ref off (~15 seconds)
 Once you see a `Serving on http://<address>:<port>/` line in the logs, the live preview is ready!
 Open that address in your browser to see it — `http://127.0.0.1:8000/` by default, or whichever host/port you passed to `-a`.
 
+On pull requests, Read the Docs builds a documentation preview only if the PR changes files that affect the docs (e.g. `docs/`, `examples/` or `mkdocs.yaml`) and the `pre-commit` checks have not failed.
+Changes to `vllm/` alone do not trigger a build, so if your PR changes the API or CLI reference, add the `build-docs` label to force one.
+
 For additional features and advanced configurations, refer to the:
 
 - [MkDocs documentation](https://www.mkdocs.org/)

docs/pre_run_check.sh

@@ -1,4 +1,3 @@
-# shellcheck disable=SC2317  # code after the exit/exit-183 gate below is intentionally dead pending re-enablement (see line comment)
 if [ "$READTHEDOCS_VERSION_TYPE" != "external" ]; then
   echo "Not a PR build (version type=$READTHEDOCS_VERSION_TYPE); skipping pre-run-check gate."
   exit 0
@@ -11,24 +10,19 @@ if [ -n "$GITHUB_TOKEN" ]; then
   CURL_AUTH=(-H "Authorization: Bearer $GITHUB_TOKEN")
 fi
 
-# Docs builds are now manually enabled via the 'build-docs' label.
+# The 'build-docs' label forces a docs build, bypassing the checks below.
 echo "Checking for the 'build-docs' label on PR #${READTHEDOCS_VERSION_NAME}..."
 LABELS=$(curl -sS "${CURL_AUTH[@]}" "https://api.github.com/repos/vllm-project/vllm/issues/${READTHEDOCS_VERSION_NAME}/labels" | python3 -c "import sys, json; print('\n'.join(l.get('name', '') for l in json.load(sys.stdin)))")
 if printf '%s\n' "$LABELS" | grep -qx "build-docs"; then
-  echo "PR has the 'build-docs' label; continuing build."
+  echo "PR has the 'build-docs' label; forcing build."
   exit 0
-else
-  echo "PR does not have the 'build-docs' label; cancelling build."
-  # See https://docs.readthedocs.com/platform/latest/guides/build/skip-build.html for info on exit code
-  exit 183
 fi
 
-# Everything below this line is effectively disabled as a temporary measure.
 echo "Checking for changes to docs-affecting files vs origin/main..."
 DOCS_PATHS=(
   docs/                       # Actual docs content
   examples/                   # Examples are rendered in docs
-  vllm/                       # API & CLI reference
+  # vllm/                     # API & CLI reference (too broad, use 'build-docs' label)
   requirements/test/cuda.txt  # CLI reference (see docs/mkdocs/gen_files/generate_argparse.py)
   mkdocs.yaml                 # Affects build process
   .readthedocs.yaml           # Affects build process