[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>
Harry Mellor committed
Sep 30, 2026 at 13:41 UTC
b22494cc0cb4bd9db4a62fb107d92429a4a3249d
3 files changed
+6
-10
.github/mergify.yml
-1
@@ -5,7 +5,6 @@ pull_request_rules:
5
- label != stale
6
- -closed
7
- or:
8
- - files~=^[^/]+\.md$
8
- files~=^docs/
9
- files~=^examples/
10
actions:
docs/contributing/README.md
+3
@@ -135,6 +135,9 @@ API_AUTONAV_EXCLUDE=vllm mkdocs serve # API ref off (~15 seconds)
135
Once you see a `Serving on http://<address>:<port>/` line in the logs, the live preview is ready!
136
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`.
137
138
+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.
139
+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.
140
+
141
For additional features and advanced configurations, refer to the:
142
143
- [MkDocs documentation](https://www.mkdocs.org/)
docs/pre_run_check.sh
+3
-9
@@ -1,4 +1,3 @@
1
-# shellcheck disable=SC2317 # code after the exit/exit-183 gate below is intentionally dead pending re-enablement (see line comment)
1
if [ "$READTHEDOCS_VERSION_TYPE" != "external" ]; then
2
echo "Not a PR build (version type=$READTHEDOCS_VERSION_TYPE); skipping pre-run-check gate."
3
exit 0
@@ -11,24 +10,19 @@ if [ -n "$GITHUB_TOKEN" ]; then
10
CURL_AUTH=(-H "Authorization: Bearer $GITHUB_TOKEN")
11
fi
12
14
-# Docs builds are now manually enabled via the 'build-docs' label.
13
+# The 'build-docs' label forces a docs build, bypassing the checks below.
14
echo "Checking for the 'build-docs' label on PR #${READTHEDOCS_VERSION_NAME}..."
15
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)))")
16
if printf '%s\n' "$LABELS" | grep -qx "build-docs"; then
18
- echo "PR has the 'build-docs' label; continuing build."
17
+ echo "PR has the 'build-docs' label; forcing build."
18
exit 0
20
-else
21
- echo "PR does not have the 'build-docs' label; cancelling build."
22
- # See https://docs.readthedocs.com/platform/latest/guides/build/skip-build.html for info on exit code
23
- exit 183
19
fi
20
26
-# Everything below this line is effectively disabled as a temporary measure.
21
echo "Checking for changes to docs-affecting files vs origin/main..."
22
DOCS_PATHS=(
23
docs/ # Actual docs content
24
examples/ # Examples are rendered in docs
31
- vllm/ # API & CLI reference
25
+ # vllm/ # API & CLI reference (too broad, use 'build-docs' label)
26
requirements/test/cuda.txt # CLI reference (see docs/mkdocs/gen_files/generate_argparse.py)
27
mkdocs.yaml # Affects build process
28
.readthedocs.yaml # Affects build process