# PR #43972 完整报告

- 仓库：`vllm-project/vllm`
- 标题：Skip docs build if PR doesn't affect docs
- 合并时间：2026-05-29 20:09
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/43972

---

# 执行摘要

- 一句话：PR 无文档变更时跳过 ReadTheDocs 构建
- 推荐动作：建议合并。这是一次精益的 CI 优化，改动小、收益明确、风险可控。代码注释清晰（第二 commit 补充了路径说明），后续维护成本低。

# 功能与动机

PR body 指出：If PRs don't touch files that change the docs output we can skip the docs build. This will:
- Reduce the time to merge for those specific PRs - Reduce resource contention for PRs that need the docs built。

# 实现拆解

1. **定义文档影响路径**：在 `docs/pre_run_check.sh` 中定义了数组 `DOCS_PATHS`，包含 `docs/`、`examples/`、`vllm/`、`requirements/test/cuda.txt`、`mkdocs.yaml`、`.readthedocs.yaml`、`requirements/docs.txt`、`requirements/docs.in` 共 8 个路径，这些路径的变更会影响文档输出。

2. **构建早停逻辑**：脚本首先检查 `$READTHEDOCS_VERSION_TYPE` 是否为 external（PR 构建），若不是则直接退出。然后通过 `git diff --quiet origin/main -- "${DOCS_PATHS[@]}"` 判断是否有文档影响文件被修改；若无修改，则以退出码 183 退出（ReadTheDocs 约定退出码 183 表示取消构建）；若有修改，则继续原有的 pre-run-check 等待和校验逻辑。

3. **调整构建配置**：修改 `.readthedocs.yaml` 中 post_checkout 阶段的命令顺序，将 `git fetch origin main --unshallow --no-tags --filter=blob:none || true` 移到 `bash docs/pre_run_check.sh` 之前，确保脚本执行时能正确获取 `origin/main` 历史。

关键文件：
- `docs/pre_run_check.sh`（模块 文档构建；类别 other；类型 core-logic）: 核心实现文件：新增了基于 git diff 的文档影响检测逻辑和提前取消构建的退出码机制。
- `.readthedocs.yaml`（模块 构建配置；类别 config；类型 configuration）: 调整了 post_checkout 阶段命令顺序，确保 git fetch 在 pre_run_check.sh 之前执行，使 diff 能正常工作。

关键符号：未识别

## 关键源码片段

### `docs/pre_run_check.sh`

核心实现文件：新增了基于 git diff 的文档影响检测逻辑和提前取消构建的退出码机制。

```bash
# docs/pre_run_check.sh

if [ "$READTHEDOCS_VERSION_TYPE" != "external" ]; then
  echo "Not a PR build (version type=$READTHEDOCS_VERSION_TYPE); skipping pre-run-check gate."
  exit 0
fi

echo "Checking for changes to docs-affecting files vs origin/main..."
# 定义哪些文件 / 目录的变更会触发文档构建
DOCS_PATHS=(
  docs/                                # 实际文档内容
  examples/                            # 示例会渲染到文档中
  vllm/                                # API & CLI 引用
  requirements/test/cuda.txt           # CLI 引用 (see docs/mkdocs/hooks/generate_argparse.py)
  mkdocs.yaml                          # 影响构建过程
  .readthedocs.yaml                    # 影响构建过程
  requirements/docs.txt                # 影响构建过程
  requirements/docs.in                 # 影响构建过程
)
if git diff --quiet origin/main -- "${DOCS_PATHS[@]}"; then
  echo "No docs-affecting files changed vs origin/main; cancelling build."
  # 退出码 183 是 ReadTheDocs 约定用于取消构建的代码
  exit 183
fi
echo "Docs-affecting files changed; continuing pre-run-check."
# 以下为原有的 pre-run-check 等待和校验逻辑 ...

```

# 评论区精华

本 PR 无 review 评论。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险极低。核心逻辑在 shell 脚本中，采用显式路径列表和退出码机制，不涉及生产代码变更。唯一可能的风险是 DOCS_PATHS 列表不完整导致文档构建被错误跳过，但 PR 作者已在第二 commit 中添加注释说明路径来源，且后续可随时补充。
- 影响：**用户 / 开发者**：非文档 PR 的 merge 等待时间减少，CI 资源释放。
**系统**：ReadTheDocs 构建请求减少，尤其是对于大量以代码为主的 PR。
**团队**：需注意今后若新增影响文档输出的文件时，需同步更新 `DOCS_PATHS` 数组。

- 风险标记：暂无

# 关联脉络

- 暂无明显关联 PR