后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载本指南面向在 Read the Docsreadthedocs.org上托管文档的开发者围绕 docs/user/guides/reproducible-builds.rst 展开文档的构建依赖众多若构建不可重复依赖的一次意外升级就可能在最不合适的时刻弄坏构建或让线上文档与你本地版本不一致。读完本文你将掌握三件事在.readthedocs.yaml中显式固定操作系统与工具链版本、用 requirements 文件固定顶层 Python 依赖、以及用 pip-tools 固定全部传递依赖从而让文档构建在多年跨度内保持稳定、可复现把精力放回内容本身。说明本文涉及的版本号仅为示意既不是最新版本也不是推荐版本具体选择哪个版本取决于你的项目实际情况需要你自行确认与验证。什么是可重复构建为什么重要按 docs/user/glossary.rst 中的术语定义reproducible可重复一个文档项目在 Read the Docs 上能够在多年时间内始终正确构建就被称为可重复的。也可以把它理解为健壮robust或有韧性resilient。pinning固定/钉住版本显式指定依赖应使用的版本。文档在构建时软件依赖会按固定规则所允许的最新版本安装由于软件包发布频繁我们通常要避免某个新版本的兼容性问题突然弄坏文档构建。精确固定exact pinning即sphinx5.3.0这种写法是 Read the Docs 推荐的做法。三种固定粒度对比摘自 glossary写法含义实际安装结果sphinx5.3.0精确固定只允许 Sphinx 5.3.0sphinx5.3,5.4宽松固定允许安装最新的 5.3.xsphinx5,6极宽松固定允许安装最新的 5.x宽松与极宽松固定仍然会让依赖在构建时浮动到最新小版本无法保证与本地构建完全一致因此建议精确固定。一个不可重复的文档项目其构建会因为外部因素依赖发版、镜像更新等而随时中断需要频繁排查和手工修复——这正是本指南要帮你规避的。第一步在 .readthedocs.yaml 中显式固定 OS 与工具链版本Read the Docs 推荐使用仓库根目录的.readthedocs.yaml配置文件显式声明构建所用的操作系统与工具版本。这个文件按版本per version提供设置且这些设置随你的 Git 仓库一起保存因此可以用 Pull Request 预览构建 来验证配置改动确保所有版本都能从一个可重复的配置重建。一个完整的最小示例# .readthedocs.yaml version: 2 # 显式指定操作系统与 Python 版本 build: os: ubuntu-24.04 tools: nodejs: 20 python: 3.12build.os构建用操作系统build.os对应 Read the Docs 构建文档所用的 Docker 镜像镜像名即构建服务器的操作系统。当前仓库中可用的 OS 选项定义在 readthedocs/builds/constants_docker.py 的RTD_DOCKER_BUILD_SETTINGS[os]中ubuntu-22.04ubuntu-24.04ubuntu-26.04ubuntu-lts-latest指向 Read the Docs 当前最新的 Ubuntu LTS 镜像的别名配置参考 docs/user/config-file/v2.rst 中build.os一节明确指出不支持任意 Docker 镜像ubuntu-lts-latest是Read the Docs 上可用的最新 Ubuntu LTS不一定与 Ubuntu 官方最新 LTS 一致而且使用latest别名可能在你项目不兼容新版本时意外弄坏构建。所以追求可重复构建时应像示例一样使用具体的镜像名如ubuntu-24.04而不是浮动别名。build.tools构建工具链版本build.tools是一个字典用于为 python、nodejs、ruby、rust、golang 指定版本且必须至少包含一个工具。每种工具在配置文件中写的短版本号会由 Read the Docs 映射为镜像中通过 asdf 安装的完整版本映射表同样位于 readthedocs/builds/constants_docker.py例如python:3.12→3.12.13、3.13→3.13.14也支持miniconda3-3.12-24.9、mambaforge-23.11、miniforge3-26.3等 Conda/Mamba 解释器版本nodejs:20→20.20.2、22→22.23.1ruby:3.4→3.4.9rust:1.82→1.82.0golang:1.23→1.23.12。每种工具还提供latest别名以及python: 3表示最新 3.x。与ubuntu-lts-latest同理latest是Read the Docs 上可用的最新版本会在至少每六个月一次的更新中前移使用它同样可能意外弄坏构建。可重复构建的要点就是避开这些浮动别名写死具体版本号。底层是如何校验的config 模块源码视角从源码看这份 YAML 会经过以下链路readthedocs/config/parser.py 使用yaml.safe_load解析文件非 YAML 语法、非 mapping 或空配置都会抛出ParseErrorreadthedocs/config/config.py 的load()在仓库中查找.readthedocs.yaml或你显式指定的自定义配置路径校验version必须为2然后实例化并validate()BuildConfigV2.validate_build_config_with_os()readthedocs/config/config.py会校验build.os必须是RTD_DOCKER_BUILD_SETTINGS[os]的键之一、build.tools的每个工具与版本必须在RTD_DOCKER_BUILD_SETTINGS[tools]中合法并且build.tools与build.commands至少提供其一最终通过 readthedocs/config/models.py 的BuildWithOspydantic 模型承载其中BuildTool同时保存短版本号与映射后的完整版本号readthedocs/config/models.py。对应的测试见 readthedocs/config/tests/test_config.py例如test_load_version2验证带build.osbuild.tools的 v2 配置可被正确加载为BuildConfigV2readthedocs/builds/tests/test_buildconfig.py 还验证了不同配置如ubuntu-22.04python3.11与ubuntu-24.04python3.10会分别生成独立的BuildConfig记录——这正是配置随仓库保存、每个版本一套可重建配置的实现基础。第二步用 requirements 文件固定 Python 依赖固定了操作系统和工具链之后下一步是固定 Python 依赖本身。Read the Docs 推荐使用 Pip 的requirements 文件参考 docs/user/config-file/v2.rst 中python.install的 requirements 一节或 Conda 的environment 文件conda.environment来固定 Python 依赖确保顶层依赖与扩展不会悄悄变化。在.readthedocs.yaml中指定依赖文件的配置# .readthedocs.yaml # 显式指定 Python 版本及其 requirements 文件 python: install: - requirements: docs/requirements.txt对应的docs/requirements.txt# 定义精确版本确保构建不被依赖更新破坏 sphinx5.3.0 sphinx_rtd_theme1.1.1 sphinx-notfound-page1.0.2这里python.install是一个列表支持多个条目requirements键的值是相对于仓库根目录的路径。除 requirements 文件外python.install还支持method: pip/method: setuptools已弃用/method: uv配合path安装本地包以及extra_requirements安装可选的 extra例如pip install .[docs]见 docs/user/config-file/v2.rst。提示每隔一段时间记得更新文档依赖以获取新的改进与修复当某个版本到达其生命周期终点end of support时也方便统一管理升级。构建时到底怎么安装python_environments 源码视角配置解析完成后构建阶段由 readthedocs/doc_builder/python_environments.py 的install_requirements()驱动它会遍历config.python.install列表对 requirements 文件类型调用install_requirements_file()对包路径类型调用install_package()对 uv 类型调用install_uv()。其中install_requirements_file()readthedocs/doc_builder/python_environments.py实际执行的命令等价于python -m pip install --exists-actionw --no-cache-dir -r docs/requirements.txt注意--exists-actionw表示覆盖已存在的文件--no-cache-dir禁用 pip 缓存。由于 requirements 文件中的精确固定pip 只会安装你写死的版本传递依赖则受上游包的约束浮动——这正是第三步要解决的问题。第三步用 pip-tools 固定传递依赖transitive dependencies一旦固定了顶层依赖下一个需要担心的是依赖的依赖即传递依赖。如果你不把这些包也固定下来它们可能在毫无征兆的情况下自动升级。Read the Docs 推荐使用pip-tools解决这个问题你在requirements.in中只写顶层依赖pip-tools 的pip-compile命令会为你生成一份包含全部传递依赖且均已固定版本的requirements.txt。docs/requirements.insphinx5.3.0执行pip-compile docs/requirements.in后生成的docs/requirements.txt节选完整文件见原文档 docs/user/guides/reproducible-builds.rst# # This file is autogenerated by pip-compile with Python 3.10 # by the following command: # # pip-compile docs/requirements.in # alabaster0.7.12 # via sphinx babel2.11.0 # via sphinx certifi2022.12.7 # via requests charset-normalizer2.1.1 # via requests docutils0.19 # via sphinx idna3.4 # via requests imagesize1.4.1 # via sphinx jinja23.1.2 # via sphinx markupsafe2.1.1 # via jinja2 packaging22.0 # via sphinx pygments2.13.0 # via sphinx pytz2022.7 # via babel requests2.28.1 # via sphinx snowballstemmer2.2.0 # via sphinx sphinx5.3.0 # via -r docs.in sphinxcontrib-applehelp1.0.2 # via sphinx sphinxcontrib-devhelp1.0.2 # via sphinx sphinxcontrib-htmlhelp2.0.0 # via sphinx sphinxcontrib-jsmath1.0.1 # via sphinx sphinxcontrib-qthelp1.0.3 # via sphinx sphinxcontrib-serializinghtml1.1.5 # via sphinx urllib31.26.13 # via requests这份由 pip-compile 自动生成的文件有两大优点每个包都被精确固定连# via sphinx这样的来源注释都保留了方便日后排查这个包是从哪来的顶层依赖与传递依赖分离管理日常只维护requirements.in需要升级时重新运行pip-compile即可生成的新文件同样可重复、可审查。生成后把docs/requirements.txt交给 Read the Docs 安装即可即第二步中的python.install[].requirements。类似地仓库自身的部署依赖也用同一思路管理根目录的 requirements/pip.in 与 requirements/pip.txt 就是 pip-tools 工作流pip-compile 编译后的固定文件在 readthedocs.org 项目自身中的实际应用。补充Conda 环境的可重复构建如果你使用 Conda/Mamba 管理构建环境应使用conda.environment指向一个 environment 文件来固定依赖。配置示例docs/user/config-file/v2.rstversion: 2 build: os: ubuntu-24.04 tools: python: mambaforge-22.9 conda: environment: environment.yml注意使用 Conda 时必须通过build.tools.python指定使用 Conda 还是 Mamba 来创建环境如miniconda3-...或mambaforge-...。从源码看readthedocs/config/config.py 的validate_conda()会强制要求conda.environment路径存在且相对于项目根目录合法而python_interpreter属性readthedocs/config/config.py正是根据build.tools.python的版本前缀mamba/miniconda/miniforge判定解释器类型的。若声明了 Conda 工具却未提供conda.environment校验会直接报CONDA_KEY_REQUIRED错误。常见误区与注意事项不要用latest或浮动别名ubuntu-lts-latest、python: latest、python: 3、nodejs: latest等别名会随 Read the Docs 每半年左右的镜像更新而前移违背可重复构建的初衷build.os也不支持任意 Docker 镜像。版本号要真实存在配置文件中的工具短版本必须命中 readthedocs/builds/constants_docker.py 的映射表否则validate_choice校验会报错选择版本时请以该表或 docs/user/config-file/v2.rst 的选项列表为准。系统级包优先用 pip/conda构建服务器运行 Ubuntu LTS 并带默认软件源虽可用build.apt_packages安装 APT 包见 docs/user/config-file/v2.rst但应尽量避免用 apt 安装 Python 包如python3-numpy改用 pip 或 conda 固定版本否则同样会引入版本漂移。用 Pull Request 验证配置改动.readthedocs.yaml保存在仓库中配合 Pull Request 预览构建可以在合并前验证新配置、新依赖不会破坏构建。requirements 文件是顶层依赖清单如果团队习惯手写requirements.txt且只含顶层依赖请务必引入 pip-tools或等效的pip freeze工作流把传递依赖一并钉死否则依赖的依赖仍会浮动。相关阅读配置文件完整参考build、python、conda、formats等全部键的完整说明与类型/默认值/选项列表构建过程Read the Docs 的标准构建流程构建过程定制通过build.jobs、build.commands扩展或完全自定义构建步骤术语表pinning、reproducible等核心术语的精确定义Conda 使用指南Conda 环境的完整用法环境变量参考构建时可用的环境变量如$READTHEDOCS_OUTPUT赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐GoReleaser 可重现构建Reproducible Builds完整实战指南GoReleaser 可重现构建Reproducible Builds完整实战指南 GoReleaser 内置了对可重现构建的原生支持通过固定编译时间戳、开发工具CI/CD构建工具Dora Hub 可复现构建Reproducible Builds实战指南从 lockfile 锁定到离线镜像Dora Hub 可复现构建Reproducible Builds实战指南从 lockfile 锁定到离线镜像 DORADataflow Oriente机器人人工智能ROS消息路由如何快速获取yuzu模拟器最新版本完整下载与配置指南如何快速获取yuzu模拟器最新版本完整下载与配置指南 还在为寻找yuzu模拟器稳定版本而烦恼吗想要在PC上流畅运行Switch游戏却不知从何入手yuzu游戏开发上一篇Minecraft服务器性能优化终极指南用Spark快速解决卡顿问题下一篇YOLOv8目标检测实战基于Bingsu/adetailer的深度优化与生产部署架构创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考