Read the Docs 默认构建依赖版本解析：从“固定版本“到“始终最新“的构建策略与可复现实践

后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载本文围绕 docs/user/build-default-versions.rst 展开结合 readthedocs.org 仓库中 python_environments.py、director.py、constants_docker.py 等源码系统讲解 Read the Docs 默认安装的 Python 环境依赖、Conda 环境依赖及其版本策略演变并给出可复现构建的最佳实践。一、背景为什么默认依赖改为安装最新版本Read the Docs 支持使用几乎任何文档工具来构建文档但平台为Sphinx与MkDocs提供了预定义pre-defined的构建器这两类项目开箱即用。过去很长一段时间Read the Docs 会把若干依赖固定安装到某个特定版本并在一段时间后批量升级。这种固定默认版本的做法带来了两个现实问题破坏既有构建当默认依赖被升级到新版本时许多项目尤其是未显式声明依赖版本的项目会在未做任何改动的情况下突然构建失败阻碍新项目使用新特性新项目如果希望使用依赖的最新版本能力必须额外覆盖默认版本增加了使用门槛。因此当前策略本仓库所反映的实现改为默认只安装最小必要的依赖并且统一使用其最新版本latest version by default。关于历史默认依赖版本清单及迁移建议原文档指向了该变更的公告博客文章。说明该策略针对的是默认安装行为。原文档与 builds.rst 中的 install 步骤都反复强调为了保证构建可复现reproducible强烈建议项目显式声明依赖及其版本详见 reproducible-builds 指南。二、Python 环境virtualenv的默认依赖2.1 默认安装清单在使用 Pythonvirtualenv环境构建时Read the Docs 默认安装以下依赖全部为最新版本依赖默认行为说明Sphinx最新版本当项目 doctype 为 Sphinx 时安装MkDocs最新版本当项目 doctype 为 MkDocs 时安装pip最新版本先于其他依赖升级setuptools最新版本先于其他依赖升级2.2 源码层面的安装流程Virtualenv.install_core_requirements()python_environments.py是这条默认安装路径的核心实现其执行顺序为先升级 pip 与 setuptools 到最新版本pip install --upgrade --no-cache-dir pip setuptools根据 doctype 选择核心构建工具doctype mkdocs时追加mkdocs其余情况追加sphinx若为 GENERIC通用项目则不再安装任何 Sphinx/MkDocs 默认依赖。对应地在构建流程的调度层 director.py 中install()步骤会先调用install_core_requirements()安装这些默认核心依赖再调用install_requirements()安装用户通过python.install配置的项目依赖。值得注意的细节安装命令使用了--upgrade --upgrade-strategy only-if-needed等参数见install_package确保以按需升级的方式安装虚拟环境通过python -m virtualenv创建python_environments.py环境路径由$READTHEDOCS_VIRTUALENV_PATH指定若项目使用 uv 管理环境UvEnv则跳过 RTD 默认的 pip/sphinx 引导安装install_core_requirements为空实现见 python_environments.py改由uv sync或uv pip install安装项目声明的依赖。三、Conda 环境的默认依赖3.1 默认安装清单使用 Conda 环境时默认安装情况如下依赖默认行为说明CondaMiniconda固定为 Miniconda24.6.14未来可能改为默认使用最新版本MkDocs最新版本通过conda安装Sphinx最新版本通过conda安装sphinx-rtd-theme最新版本通过conda安装2023-08-07 之后创建的项目默认不再安装mock最新版本通过pip安装2023-08-07 之后创建的项目默认不再安装pillow最新版本通过pip安装2023-08-07 之后创建的项目默认不再安装recommonmark最新版本通过conda安装2023-08-07 之后创建的项目默认不再安装需要特别说明两点Miniconda 版本是当前唯一的固定版本默认依赖4.6.14其余默认依赖均为最新版本原文档明确指出这一固定版本未来可能也会改为默认最新原文档中标注Projects created after August 7, 2023 wont install this dependency by default的四个依赖sphinx-rtd-theme、mock、pillow、recommonmark意味着新项目不再获得这些额外默认依赖用户需要显式在environment.yml或 requirements 中声明它们。3.2 源码层面的 Conda 处理逻辑Conda类python_environments.py的默认依赖注入逻辑与 virtualenv 路径有明显不同_append_core_requirements()会在构建前把核心依赖直接写入用户的environment.ymlconda 依赖追加到dependencies顶层pip-only 依赖追加到dependencies.pip中_get_core_requirements()决定追加内容当doctype mkdocs时通过 pip 追加mkdocs否则通过 conda 追加sphinx随后setup_base()执行conda env create --quiet --name slug --file environment.yml一次性创建环境并安装全部依赖因此install_core_requirements()与install_requirements_file()在 Conda 环境下均为空实现pass——因为依赖已在环境创建阶段全部安装完毕无需二次安装。这种把默认依赖写进用户环境文件再统一创建环境的设计相关讨论见仓库 PR #5631 注释既能让用户精确地固定自己的依赖版本又避免了二次conda install时可能的版本覆盖问题。从源码结构还可以推断环境管理支持mamba/conda两种解释器conda_bin_name()返回config.python_interpreter。四、版本策略背后的构建流程定位默认依赖安装位于整个构建流程的install 步骤。在 builds.rst 描述的构建作业pre-defined build jobs中checkout从 Git 仓库检出代码system_dependencies安装操作系统与运行时依赖语言版本、apt 包create_environment创建隔离的 Python 环境virtualenv 或 Condainstall安装默认依赖 项目依赖本主题的落点build根据 doctype 调用 Sphinx 或 MkDocs 构建各格式产物upload上传产物并刷新 CDN。从源码看create_environment与install步骤对于 GENERIC 项目且未使用 uv 时会直接跳过director.py因为通用项目不需要默认安装 Sphinx/MkDocs。另外可以补充的是Read the Docs 的构建运行在 Docker 容器中容器内语言工具链Python、Node.js、Rust、Go 等的版本映射由 constants_docker.py 中的RTD_DOCKER_BUILD_SETTINGS定义例如python3.10→3.10.20、miniconda3-4.7→miniconda3-4.7.12并支持latest别名。用户可通过 config-file/v2 的build.os与build.tools显式指定这些工具版本——这与默认依赖用最新、项目级依赖显式固定的整体思路一脉相承。五、实战建议如何在默认最新策略下构建可复现文档原文档明确给出如下建议为了让构建可复现强烈建议显式声明依赖及其版本。完整实操可参考 reproducible-builds 指南核心要点如下。5.1 在.readthedocs.yaml中固定 OS 与工具版本# .readthedocs.yaml version: 2 build: os: ubuntu-24.04 tools: python: 3.12 nodejs: 20通过build.os与build.tools明确构建环境使所有版本都能从同一份可复现配置重建。5.2 用 requirements 文件固定 Python 依赖# .readthedocs.yaml python: install: - requirements: docs/requirements.txt# docs/requirements.txt # 显式固定版本避免默认最新版意外升级导致构建失败 sphinx5.3.0 sphinx_rtd_theme1.1.1 sphinx-notfound-page1.0.2对于 Conda 项目则通过conda.environment指向environment.yml并在其中显式列出依赖Read the Docs 会自动把 Sphinx/MkDocs 核心依赖追加进该文件。5.3 固定传递依赖transitive dependencies即使固定了顶层依赖其传递依赖仍可能悄悄升级。原指南推荐使用pip-tools# docs/requirements.in声明顶层依赖 sphinx5.3.0# docs/requirements.txtpip-compile 生成固定全链路版本 alabaster0.7.12 babel2.11.0 docutils0.19 sphinx5.3.0 # ... 其余均为锁定版本运行pip-compile docs/requirements.in即可生成完整的锁定清单。5.4 与构建流程的配合默认依赖pip、setuptools、sphinx/mkdocs始终为最新版这是平台级行为无法通过配置文件关闭但用户声明的 requirements 会在默认依赖之后安装因此只要显式固定版本即可完全覆盖默认版本行为Conda 项目请务必注意sphinx-rtd-theme、mock、pillow、recommonmark四个依赖2023-08-07 之后创建的新项目不再默认安装它们若项目仍依赖这些包请显式写入environment.yml如遇依赖升级导致的构建问题优先通过上述显式固定方式解决而不是依赖平台默认版本。六、小结Read the Docs 默认构建依赖的版本策略经历了从固定版本、定期升级到仅安装最小必要依赖、默认使用最新版本的转变。在 Pythonvirtualenv环境中默认依赖仅包括 pip、setuptools 与按 doctype 选择的 Sphinx/MkDocs在 Conda 环境中除固定版本的 Miniconda24.6.14外其余默认依赖均为最新且 2023-08-07 后创建的项目不再默认安装 sphinx-rtd-theme、mock、pillow、recommonmark。这套策略的落点在于 python_environments.py 的install_core_requirements/_append_core_requirements实现与 director.py 的 install 调度。对开发者而言理解平台默认用最新、项目显式固定版本的分层原则并配合.readthedocs.yaml requirements 文件 pip-tools 实践即可在享受新版本特性的同时获得稳定、可复现的文档构建体验。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐Read the Docs 可重复构建Reproducible Builds实战指南用 .readthedocs.yaml 与依赖固定让文档多年稳定可构建Read the Docs 可重复构建Reproducible Builds实战指南用 .readthedocs.yaml 与依赖固定让文档多年稳定可构建后端文档Swift大数运算最佳实践BigInt在金融与密码学中的应用Swift大数运算最佳实践BigInt在金融与密码学中的应用 BigInt是一个基于纯Swift实现的任意精度算术库为开发者提供了处理超出标准数据类型范围的Read the Docs 术语表全解析从 CI/CD 到可复现构建的核心概念与实践指南Read the Docs 术语表全解析从 CI/CD 到可复现构建的核心概念与实践指南 Read the Docs 是一套面向文档的 CI/CD 平台其官后端文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考