执行摘要

• 一句话：优化文档构建跳过时的日志输出
• 推荐动作：建议阅读以了解 ReadTheDocs CI 的 gate 机制。如需复用类似模式（提取 CI 脚本），可参考此 PR 的结构。但对于 reviewer 提出的性能与错误处理问题，建议在后续跟进。

功能与动机

当 docs 构建因 pre-run-check 失败被跳过时，原日志只显示“skipping docs build”，缺乏失败原因的链接。PR 动机在于提供直接的原因链接，帮助 contributors 快速定位问题。PR body 中明确说明："so contributors with skipping docs build have a direct link to the reason why their docs build was skipped"。

实现拆解

1. 提取脚本：将 .readthedocs.yaml 中 post_checkout 步骤的内联 shell 代码完整移动到新的文件 docs/pre_run_check.sh。
2. 改善日志：在 docs/pre_run_check.sh 中新增 CHECK_URL 变量，通过解析 GitHub API 响应中的 html_url 字段获取 check run 详情链接。当结论为失败/取消/超时时，除了打印“did not pass; skipping docs build”，还额外输出一行 pre-run-check failure reason: $CHECK_URL。
3. 配置简化：.readthedocs.yaml 中原本约 38 行的内联逻辑被替换为一行的 bash docs/pre_run_check.sh 调用。
4. 无其他配套改动：没有修改测试、文档或其他基础设施文件。

关键文件：

• .readthedocs.yaml（模块 CI 配置；类别 config；类型 configuration）: 将内联的 pre-run-check 逻辑替换为外部脚本调用，大幅精简配置。
• docs/pre_run_check.sh（模块 文档构建；类别 other；类型 core-logic）: 新脚本包含了原有 pre-run-check 逻辑，并新增了 CHECK_URL 日志打印，是核心变更文件。

关键符号：未识别

关键源码片段

docs/pre_run_check.sh

新脚本包含了原有 pre-run-check 逻辑，并新增了 CHECK_URL 日志打印，是核心变更文件。

#!/usr/bin/env bash
# pre-run-check 脚本：轮询 GitHub Check Runs API，
# 当 check 结论为 failure/cancelled/timed_out 时，
# 打印结论和失败链接，并以非零退出码中止构建。
​
if [ "$READTHEDOCS_VERSION_TYPE" = "external" ]; then
  MAX_WAIT=300
  INTERVAL=60
  ELAPSED=0
  while :; do
    RAW=$(curl -sS -w "\n%{http_code}" \
      "https://api.github.com/repos/vllm-project/vllm/commits/${READTHEDOCS_GIT_COMMIT_HASH}/check-runs?check_name=pre-run-check&filter=latest")
    HTTP_CODE=$(printf "%s" "$RAW" | tail -n1)
    BODY=$(printf "%s" "$RAW" | sed '$d')
    if [ "$HTTP_CODE" != "200" ]; then
      echo "GitHub API returned HTTP $HTTP_CODE (likely rate-limited); skipping pre-run-check gate."
      break
    fi
    STATUS=$(printf "%s" "$BODY" | python3 -c \
      "import sys, json; r=json.load(sys.stdin).get('check_runs',[]); print((r[0].get('status') or '') if r else 'none')")
    CONCLUSION=$(printf "%s" "$BODY" | python3 -c \
      "import sys, json; r=json.load(sys.stdin).get('check_runs',[]); print((r[0].get('conclusion') or '') if r else '')")
    # 新增：提取 check run 的 html_url，用于失败时打印直接链接
    CHECK_URL=$(printf "%s" "$BODY" | python3 -c \
      "import sys, json; r=json.load(sys.stdin).get('check_runs',[]); print((r[0].get('html_url') or '') if r else '')")
    if [ "$STATUS" = "none" ]; then
      echo "no pre-run-check found for this commit; skipping gate."
      break
    fi
    if [ -n "$CONCLUSION" ]; then
      echo "pre-run-check conclusion: $CONCLUSION"
      if [ "$CONCLUSION" = "failure" ] || [ "$CONCLUSION" = "cancelled" ] || [ "$CONCLUSION" = "timed_out" ]; then
        echo "pre-run-check did not pass; skipping docs build."
        # 新增：打印失败原因链接
        if [ -n "$CHECK_URL" ]; then
          echo "pre-run-check failure reason: $CHECK_URL"
        fi
        exit 1
      fi
      break
    fi
    if [ "$ELAPSED" -ge "$MAX_WAIT" ]; then
      echo "pre-run-check status=$STATUS after ${MAX_WAIT}s; skipping gate."
      break
    fi
    echo "pre-run-check status=$STATUS; waiting ${INTERVAL}s..."
    sleep "$INTERVAL"
    ELAPSED=$((ELAPSED + INTERVAL))
  done
else
  echo "Not a PR build (version type=$READTHEDOCS_VERSION_TYPE); skipping pre-run-check gate."
fi

评论区精华

Review 中 gemini-code-assist[bot] 提出了两个改进建议：

• 减少重复 Python 调用：建议将多次 python3 解析 JSON 合并为一次，并添加对 JSON 解析失败的错误处理，以避免因 API 返回异常导致脚本 fail-open。

• 日志措辞修正：指出现有日志“skipping docs build”与后续 exit 1 矛盾（实际是构建失败），建议改回原来的“failing docs build”以准确反映状态。
  两个建议均未被合并者采纳，PR 以现有变更合并。

• 减少重复 Python 进程调用并添加错误处理 (performance): 未被采纳；现有变更保持原样合并。

• 日志措辞：skipping vs failing (correctness): 未被采纳；合并时保留 "skipping docs build"。

风险与影响

• 风险：变更仅涉及 CI/build 脚本提取和日志增强，不编码逻辑。原有 inline 逻辑被原样移出，唯一新增的是打印 CHECK_URL。风险极低：

  • 若 CHECK_URL 为空，额外日志无影响。
  • 抽取脚本可能因路径或执行环境差异引入问题，但 ReadTheDocs 环境与 CI 一致，该风险小。
  • 没有修改核心推理/模型/服务代码，不影响 vLLM 运行时行为。
  • 影响：影响范围：仅影响 ReadTheDocs 构建过程，不改变功能行为。contributors 在 docs 构建被跳过时将获得更清晰的失败原因链接，减少排查时间。
    影响程度：低。对最终用户无感，仅改进开发者体验和 CI 可见性。

• 风险标记：仅 CI/文档构建变更, review 建议未采纳

关联脉络

• 暂无明显关联 PR