执行摘要

• 一句话：使用 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

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

# 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