Make docs environment deterministic (#41926)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>

.pre-commit-config.yaml

@@ -131,6 +131,16 @@ repos:
         --python-version, "3.12",
       ]
       files: ^requirements/(common|xpu|test/xpu)\.(in|txt)$
+    - id: pip-compile
+      alias: pip-compile-docs
+      name: pip-compile-docs
+      args: [
+        requirements/docs.in,
+        -o, requirements/docs.txt,
+        --python-platform, x86_64-manylinux_2_28,
+        --python-version, "3.12",
+      ]
+      files: ^requirements/docs\.(in|txt)$
 - repo: local
   hooks:
   - id: format-torch-nightly-test

.readthedocs.yaml

@@ -9,7 +9,6 @@ build:
     python: "3.12"
   jobs:
     post_checkout:
-      # - bash docs/maybe_skip_pr_build.sh
       - git fetch origin main --unshallow --no-tags --filter=blob:none || true
     pre_create_environment:
       - pip install uv

docs/maybe_skip_pr_build.sh

@@ -1,24 +0,0 @@
-#!/bin/bash
-# SPDX-License-Identifier: Apache-2.0
-# Skip PR builds unless the PR has the "documentation" or "ready" label.
-# Used by Read the Docs (see .readthedocs.yaml).
-
-if [[ "$READTHEDOCS_VERSION_TYPE" != "external" ]]; then
-  exit 0
-fi
-
-PR_URL="https://api.github.com/repos/vllm-project/vllm/pulls/${READTHEDOCS_VERSION}"
-CURL_ARGS=(-s -o /tmp/pr_response.json -w "%{http_code}")
-if [[ -n "$GITHUB_TOKEN" ]]; then
-  CURL_ARGS+=(-H "Authorization: token ${GITHUB_TOKEN}")
-fi
-HTTP_CODE=$(curl "${CURL_ARGS[@]}" "$PR_URL")
-
-if [[ "$HTTP_CODE" -ne 200 ]]; then
-  echo "GitHub API returned HTTP ${HTTP_CODE}, proceeding with build."
-elif grep -qE '"name": *"(documentation|ready)"' /tmp/pr_response.json; then
-  echo "Found required label, proceeding with build."
-else
-  echo "PR #${READTHEDOCS_VERSION} lacks 'documentation' or 'ready' label, cancelling build."
-  exit 1
-fi

requirements/docs.in

@@ -0,0 +1,17 @@
+mkdocs<2.0.0
+mkdocs-api-autonav
+mkdocs-material
+mkdocstrings-python
+mkdocs-gen-files
+mkdocs-awesome-nav
+mkdocs-glightbox
+mkdocs-git-revision-date-localized-plugin
+mkdocs-minify-plugin
+mkdocs-redirects
+regex
+ruff
+pydantic
+
+# For generating argparse docs.
+# Adding requirements here should only be used as a last resort.
+msgspec  # Need for multiple inheritance involving msgspec.Struct

requirements/docs.txt

@@ -1,17 +1,182 @@
-mkdocs<2.0.0
-mkdocs-api-autonav
-mkdocs-material
-mkdocstrings-python
-mkdocs-gen-files
-mkdocs-awesome-nav
-mkdocs-glightbox
-mkdocs-git-revision-date-localized-plugin
-mkdocs-minify-plugin
-mkdocs-redirects
-regex
-ruff
-pydantic
-
-# For generating argparse docs.
-# Adding requirements here should only be used as a last resort.
-msgspec  # Need for multiple inheritance involving msgspec.Struct
+# This file was autogenerated by uv via the following command:
+#    uv pip compile requirements/docs.in -o requirements/docs.txt --python-platform x86_64-manylinux_2_28 --python-version 3.12
+annotated-types==0.7.0
+    # via pydantic
+babel==2.18.0
+    # via
+    #   mkdocs-git-revision-date-localized-plugin
+    #   mkdocs-material
+backrefs==7.0
+    # via mkdocs-material
+bracex==2.6
+    # via wcmatch
+certifi==2026.4.22
+    # via requests
+charset-normalizer==3.4.7
+    # via requests
+click==8.3.3
+    # via
+    #   mkdocs
+    #   properdocs
+colorama==0.4.6
+    # via mkdocs-material
+csscompressor==0.9.5
+    # via mkdocs-minify-plugin
+ghp-import==2.1.0
+    # via
+    #   mkdocs
+    #   properdocs
+gitdb==4.0.12
+    # via gitpython
+gitpython==3.1.50
+    # via mkdocs-git-revision-date-localized-plugin
+griffelib==2.0.2
+    # via mkdocstrings-python
+htmlmin2==0.1.13
+    # via mkdocs-minify-plugin
+idna==3.13
+    # via requests
+jinja2==3.1.6
+    # via
+    #   mkdocs
+    #   mkdocs-material
+    #   mkdocstrings
+    #   properdocs
+jsmin==3.0.1
+    # via mkdocs-minify-plugin
+markdown==3.10.2
+    # via
+    #   mkdocs
+    #   mkdocs-autorefs
+    #   mkdocs-material
+    #   mkdocstrings
+    #   properdocs
+    #   pymdown-extensions
+markupsafe==3.0.3
+    # via
+    #   jinja2
+    #   mkdocs
+    #   mkdocs-autorefs
+    #   mkdocstrings
+    #   properdocs
+mergedeep==1.3.4
+    # via
+    #   mkdocs
+    #   mkdocs-get-deps
+mkdocs==1.6.1
+    # via
+    #   -r requirements/docs.in
+    #   mkdocs-api-autonav
+    #   mkdocs-autorefs
+    #   mkdocs-awesome-nav
+    #   mkdocs-gen-files
+    #   mkdocs-git-revision-date-localized-plugin
+    #   mkdocs-material
+    #   mkdocs-minify-plugin
+    #   mkdocs-redirects
+    #   mkdocstrings
+mkdocs-api-autonav==0.4.0
+    # via -r requirements/docs.in
+mkdocs-autorefs==1.4.4
+    # via
+    #   mkdocstrings
+    #   mkdocstrings-python
+mkdocs-awesome-nav==3.3.0
+    # via -r requirements/docs.in
+mkdocs-gen-files==0.6.1
+    # via -r requirements/docs.in
+mkdocs-get-deps==0.2.2
+    # via mkdocs
+mkdocs-git-revision-date-localized-plugin==1.5.1
+    # via -r requirements/docs.in
+mkdocs-glightbox==0.5.2
+    # via -r requirements/docs.in
+mkdocs-material==9.7.6
+    # via -r requirements/docs.in
+mkdocs-material-extensions==1.3.1
+    # via mkdocs-material
+mkdocs-minify-plugin==0.8.0
+    # via -r requirements/docs.in
+mkdocs-redirects==1.2.3
+    # via -r requirements/docs.in
+mkdocstrings==1.0.4
+    # via mkdocstrings-python
+mkdocstrings-python==2.0.3
+    # via
+    #   -r requirements/docs.in
+    #   mkdocs-api-autonav
+msgspec==0.21.1
+    # via -r requirements/docs.in
+natsort==8.4.0
+    # via mkdocs-awesome-nav
+packaging==26.2
+    # via
+    #   mkdocs
+    #   properdocs
+paginate==0.5.7
+    # via mkdocs-material
+pathspec==1.1.1
+    # via
+    #   mkdocs
+    #   properdocs
+platformdirs==4.9.6
+    # via
+    #   mkdocs-get-deps
+    #   properdocs
+properdocs==1.6.7
+    # via
+    #   mkdocs-gen-files
+    #   mkdocs-redirects
+pydantic==2.13.4
+    # via
+    #   -r requirements/docs.in
+    #   mkdocs-awesome-nav
+pydantic-core==2.46.4
+    # via pydantic
+pygments==2.20.0
+    # via mkdocs-material
+pymdown-extensions==10.21.2
+    # via
+    #   mkdocs-material
+    #   mkdocstrings
+python-dateutil==2.9.0.post0
+    # via ghp-import
+pyyaml==6.0.3
+    # via
+    #   mkdocs
+    #   mkdocs-api-autonav
+    #   mkdocs-get-deps
+    #   properdocs
+    #   pymdown-extensions
+    #   pyyaml-env-tag
+pyyaml-env-tag==1.1
+    # via
+    #   mkdocs
+    #   properdocs
+regex==2026.4.4
+    # via -r requirements/docs.in
+requests==2.33.1
+    # via mkdocs-material
+ruff==0.15.12
+    # via -r requirements/docs.in
+selectolax==0.4.8
+    # via mkdocs-glightbox
+six==1.17.0
+    # via python-dateutil
+smmap==5.0.3
+    # via gitdb
+typing-extensions==4.15.0
+    # via
+    #   pydantic
+    #   pydantic-core
+    #   typing-inspection
+typing-inspection==0.4.2
+    # via pydantic
+urllib3==2.6.3
+    # via requests
+watchdog==6.0.0
+    # via
+    #   mkdocs
+    #   properdocs
+wcmatch==10.1
+    # via mkdocs-awesome-nav