# PR #41926 完整报告

- 仓库：`vllm-project/vllm`
- 标题：Make docs environment deterministic
- 合并时间：2026-05-08 18:13
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/41926

---

# 执行摘要

- 一句话：使用 pip-compile 锁定文档依赖，增强构建确定性
- 推荐动作：值得合入。将文档依赖纳入统一管理流程是基础设施成熟度的体现。对于开发者，理解 `docs.in` + `pip-compile` 的运作模式即可；对于 CI 维护者，注意 `python-platform` 与构建目标环境的匹配性。

# 功能与动机

文档构建已开始超时，而可用构建者仅 4 个，严重影响其他文档构建。PR 作者指出，虽然锁定依赖可能不会直接修复超时，但实施这些最佳实践将使调试更容易。正如 PR body 所述：“Docs builds have started timing out during the mkdocs build stage. Since we only have 4 docs builders available, this effectively reduces the number of builders available to other docs builds. This PR:
- Uses pip-compile for docs dependencies so that they are all pinned. This likely won't fix the timeouts, but implementing these best practises will make debugging easier.”

# 实现拆解

1. **创建依赖声明文件 **(`requirements/docs.in`)：将被锁定的直接依赖写入该文件，格式与传统 `requirements/common.in` 一致，作为单一事实来源。
2. **生成锁定文件 **(`requirements/docs.txt`)：运行 `pip-compile` 将 `docs.in` 编译为带有精确版本的锁定文件，包含所有传递依赖及其来源注释。
3. **添加 pre-commit hook**( `.pre-commit-config.yaml`)：新增 `pip-compile-docs` 钩子，当 `docs.in` 或 `docs.txt` 被修改时自动重新编译，确保两者始终同步。
4. **删除旧构建跳过脚本 **(`docs/maybe_skip_pr_build.sh`)：该脚本曾用于检查 PR 是否带有 `documentation` 或 `ready` 标签以跳过构建，但当前流程已不再需要，因此删除。
5. **清理 ReadTheDocs 配置 **(`.readthedocs.yaml`)：移除 `maybe_skip_pr_build.sh` 被注释掉的调用行，使配置文件更加整洁。

关键文件：
- `requirements/docs.in`（模块 依赖管理；类别 other；类型 core-logic）: 新增文件，作为文档依赖的单一声明源，是本次变更的设计核心。
- `.pre-commit-config.yaml`（模块 代码检查；类别 config；类型 configuration）: 新增 pip-compile-docs hook，确保文档依赖文件始终同步，是关键的自动化保障。
- `requirements/docs.txt`（模块 依赖管理；类别 other；类型 documentation）: 生成的锁定文件，所有依赖的精确版本均在其中，是构建确定性的产出。
- `docs/maybe_skip_pr_build.sh`（模块 构建脚本；类别 infra；类型 deletion）: 删除旧的跳过 PR 构建脚本，简化构建流程。
- `.readthedocs.yaml`（模块 部署配置；类别 config；类型 configuration）: 清理残留注释，保持配置文件简洁。

关键符号：未识别

## 关键源码片段

### `requirements/docs.in`

新增文件，作为文档依赖的单一声明源，是本次变更的设计核心。

```python
# requirements/docs.in - 文档构建依赖声明文件
# 用法：pip-compile requirements/docs.in -o requirements/docs.txt
# 添加钩子后，pre-commit 会自动保持同步

mkdocs<2.0.0                    # MkDocs 主框架
mkdocs-api-autonav              # API 自动导航
mkdocs-material                 # Material 主题
mkdocstrings-python             # Python 文档字符串生成
mkdocs-gen-files                # 按约定生成页面
mkdocs-awesome-nav              # 增强导航
mkdocs-glightbox                # 图片灯箱
mkdocs-git-revision-date-localized-plugin  # 最后修改日期
mkdocs-minify-plugin             # 压缩插件
mkdocs-redirects                # URL 重定向
regex                           # 正则支持
ruff                            # 代码检查（用于文档示例）
pydantic                        # 数据校验（用于文档代码）

# 以下为构建 argparse 文档所需
msgspec  # 因为需要继承 msgspec.Struct

```

# 评论区精华

- **glibc 平台兼容性**：`gemini-code-assist[bot]` 指出 `.pre-commit-config.yaml` 中的 `--python-platform x86_64-manylinux_2_39` 与 ReadTheDocs `ubuntu-22.04` 环境的 glibc 2.35 不匹配，可能导致错误的 wheel 被选中。作者在后续提交中将其修正为 `x86_64-manylinux_2_28`。
- **未来版本号问题**：同一 bot 发现 `requirements/docs.txt` 中出现了 `certifi==2026.4.22`、`regex==2026.4.4` 等无效的未来版本号，会导致安装失败。作者通过重新生成锁定文件解决了该问题（最终提交的锁定文件版本号正常）。

 - 构建平台 glibc 兼容性 (correctness): 作者在后续 commit "use older glibg platform for docs pip compile" 中将平台调整为 x86_64-manylinux_2_28。
 - 未来版本号导致安装失败 (correctness): 作者后续重新生成了锁定文件，合并版本中的版本号已恢复正常。

# 风险与影响

- 风险：
 - **锁定膨胀**：`pip-compile` 会锁定所有传递依赖，可能导致依赖升级时需手动处理更多冲突。但文档依赖通常较少，影响有限。
 - **版本漂移**：如果 `docs.in` 长期不更新，锁定版本可能积累安全隐患。但 pre-commit hook 并不能自动升级，需依赖人力。
 - **环境差异**：`--python-platform` 指定为 `x86_64-manylinux_2_28` 可能与某些第三方依赖的最低要求冲突，但当前选择与项目其他部分一致，风险可控。
- 影响：
 - **用户 / 系统**：文档构建流程更加确定性和可复现，开发者调试构建问题更容易。
 - **团队**：新增一个 pre-commit hook，开发者需确保本地安装了 `pip-compile`（通过 pre-commit 自带）。对日常开发影响很小。
 - **构建时间**：锁定版本可能避免因上游意外发布导致的不兼容，但不会直接缩短构建时间。
 - 风险标记：依赖锁定维护成本 , 环境版本漂移风险

# 关联脉络

- 暂无明显关联 PR