Read the Docs Monorepo 指南：在子目录中使用 `.readthedocs.yaml` 构建配置

后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载本指南讲解如何在 Read the Docsreadthedocs.org中为一个 Git 仓库配置自定义的.readthedocs.yaml构建配置文件路径从而在单个 Monorepo 中管理多个拥有独立构建配置的文档项目。读完本文你将掌握自定义构建配置路径的完整设置流程、路径解析规则、跨版本影响与风险以及与之配套的项目级最佳实践。为什么 Monorepo 需要自定义构建配置路径默认情况下Read the Docs 会在 Git 仓库的顶层目录查找.readthedocs.yaml文件并使用它作为构建配置。对于仓库中只包含一个文档项目的情况这种约定完全够用但当一个 Git 仓库中同时包含多个文档项目、且它们需要不同的构建配置时单一顶层的配置文件就无法满足需求了。典型场景如下your-monorepo/ ├── .readthedocs.yaml # 顶层配置若存在 ├── docs-a/ │ ├── .readthedocs.yaml # 项目 A 的独立构建配置 │ ├── conf.py │ └── requirements.txt └── docs-b/ ├── .readthedocs.yaml # 项目 B 的独立构建配置 ├── mkdocs.yml └── requirements.txt此时你需要在仓库的多个子目录中各放置一个.readthedocs.yaml并在 Read the Docs 中为每个项目指定其对应的配置文件路径。这就是本文要解决的核心问题如何在项目设置中指定一个自定义的构建配置文件路径。两种值得关注的替代方案在决定采用“多份配置文件”的方案之前可以先评估以下两种替代做法Sphinx 多项目扩展sphinx-multiproject如果你只使用 Sphinx 项目并且希望所有子项目共享同一份构建配置可以考虑sphinx-multiproject扩展它可以在单个 Sphinx 构建中输出多个项目。共享配置文件 环境变量如果你的多个文档项目配置模式非常相似、且使用的文档工具相同也可以通过环境变量复用同一份配置文件。Read the Docs 支持在项目设置中为不同项目配置不同的环境变量从而实现“一份配置、多项目差异化”。相关背景可参考 环境变量指南。实现前提与关键限制在动手配置之前需要明确这个功能当前的几个重要约束1. 功能是项目级的project-wide自定义构建配置文件路径是一个项目级project-wide设置该路径一旦设定将应用于该项目的所有版本。也就是说你无法为同一项目的不同版本指定不同的配置文件路径。2. 配置文件内的路径始终相对于仓库根目录这是最容易踩坑的一点无论.readthedocs.yaml文件本身位于仓库的哪个子目录文件内引用的所有路径都始终相对于仓库根目录repository root解析。举例说明假设你的配置文件位于docs/.readthedocs.yaml而 requirements 文件位于docs/requirements.txt那么在配置文件中仍然要写python: install: - requirements: docs/requirements.txt而不是写成requirements.txt。唯一的例外是Sphinx 构建命令本身该命令会从包含conf.py的目录执行。这只会影响 Sphinx 在内部解析的路径例如conf.py中引用的路径不会改变.readthedocs.yaml中路径的解释方式。3. 修改配置路径会影响所有版本警告更改配置文件的路径会应用到所有版本。如果该路径被修改项目中不同版本的文档可能无法再次构建成功——因为旧版本对应的提交中新的配置路径可能并不存在。从同一个仓库添加多个文档项目自定义构建配置路径的完整流程分为两步添加第一个项目通过导入向导Import Wizard将 Git 仓库添加为第一个 Read the Docs 项目具体入口见 导入项目指南。重复添加第二个项目完成第一个项目后需要再次执行同样的导入流程将同一个仓库添加为第二个 Read the Docs 项目。注意每添加一个文档项目都需要重复一次导入流程。每个项目在 Read the Docs 中被视为独立实体从而获得独立的构建配置、版本和发布设置。设置自定义构建配置文件路径导入仓库之后为需要自定义配置路径的项目执行以下操作进入项目的Admin管理页面点击Settings设置在表单中找到Build configuration file构建配置文件字段填入相对于仓库根目录的配置路径例如docs/.readthedocs.yaml点击Save保存。保存之后需要确保项目的相关版本被重新构建新的配置文件才会生效。提示多个不同的构建配置文件会让 Monorepo 变得复杂。建议先在 Monorepo 中搭建 12 个文档项目确保它们能够成功构建并发布再逐步把更多项目加入进来。配置路径的校验规则与源码实现在 readthedocs.org 源码中Build configuration file字段对应的模型字段是Project.readthedocs_yaml_path定义于 readthedocs/projects/models.py。该字段的最大长度为 1024 字符留空时使用默认值.readthedocs.yaml并挂接了validate_build_config_file校验器。校验器实现位于 readthedocs/projects/validators.py它对用户输入做了一系列安全与合法性检查必须以相对路径开头路径不能以/开头它是相对于仓库根目录的不能以/结尾路径不能以/结束因为该字段指向的是文件而非目录禁止..序列不允许出现..防止路径穿越path traversal禁止非法字符不允许出现[]{}()\ %|, 等字符文件名必须合法仅允许文件名恰好为.readthedocs.yaml或以/.readthedocs.yaml结尾即路径必须指向一个名为.readthedocs.yaml的文件。配置加载的底层流程构建时readthedocs.org 通过load_yaml_configreadthedocs/doc_builder/config.py加载构建配置。它会先取得版本的 checkout 路径然后调用readthedocs.config.loadreadthedocs/config/config.py完成解析。load函数的逻辑清晰地体现了两种查找模式自定义路径如果项目设置了readthedocs_yaml_path则将该路径与 checkout 根目录拼接后直接定位文件若文件不存在会抛出CONFIG_PATH_NOT_FOUND错误默认模式在仓库根目录使用正则^\.?readthedocs.ya?ml$定义于 readthedocs/config/config.py查找第一个匹配的配置文件查找逻辑见 readthedocs/config/find.py。解析完成后文件内容经 YAML 解析器readthedocs/config/parser.py校验为合法的 mapping再由BuildConfigV2.validate()对formats、build、python、conda、sphinx、mkdocs、submodules、search等配置键逐一校验。其中python.install.requirements、sphinx.configuration、mkdocs.configuration等路径型配置项都会通过validate_path以base_path配置文件的目录为基准解析为绝对路径——这也从源码层面印证了“配置内路径相对仓库根目录”的规则因为base_path是由source_file的目录推导出的而配置文件的路径本身是相对仓库根目录给出的。相关测试用例位于 readthedocs/projects/tests/test_build_tasks.py其中TestBuildTask.test_config_file_is_loaded等用例验证了自定义配置文件路径被正确传入并加载例如在测试中通过readthedocs_yaml_pathunique.yaml模拟自定义路径API v3 的测试 readthedocs/api/v3/tests/test_projects.py 也覆盖了带有readthedocs_yaml_path的项目导入场景。为每个文档项目配置独立的项目设置Monorepo 方案落地并验证通过后你还可以充分利用 Read the Docs “每个项目独立”的平台能力为每一个文档项目单独配置维护者团队为每个项目设置独立的维护者集合商业版还可使用 组织Organizations 功能自定义重定向规则见 自定义域名与重定向指南自定义域名为不同文档绑定各自的域名自动化规则见 自动化规则文档流量分析见 流量分析文档独立的文档工具与构建流程一个项目可能使用 Sphinx另一个项目可能使用 Asciidoctor 等工具各自拥有独立的构建过程见 构建自定义文档。以及更多——Read the Docs 中所有项目级设置都可以应用到每个独立项目上。补充如果希望将一个文档项目嵌套在另一个项目内部例如作为子项目展示仍然可以在同一 Monorepo 基础上使用子项目Subprojects功能详见 子项目指南。其他建议条件构建取消规则对于 Monorepo 而言一个不理想的行为是与某个文档无关的其他子目录变更也会触发该文档项目的重新构建造成不必要的构建资源消耗。为此建议为每个文档项目配置条件构建取消规则conditional build cancellation rules。这些规则写在每个文档项目各自的.readthedocs.yaml中从而可以为 Monorepo 中的每一个文档项目编写一条独立的“何时跳过/取消构建”规则例如只在相关目录发生变化时才触发构建。配置方法见 跳过或取消构建指南。小结Monorepo 构建配置清单将以上内容整理为一份可执行的落地清单在仓库的每个文档子目录中放置各自的.readthedocs.yaml通过导入向导为同一个仓库创建多个 Read the Docs 项目在每个项目的Admin → Settings中将Build configuration file指向对应的配置文件相对仓库根目录牢记配置文件内所有路径相对仓库根目录解析Sphinx 构建命令除外保存后重新构建相关版本并验证每个项目都能独立发布先在 12 个项目上跑通再推广到全部项目为每个项目配置独立的维护者、域名、重定向、自动化规则与构建工具在每个配置文件中添加条件构建取消规则避免无关变更触发构建。遵循以上步骤你就能在单个 Git 仓库中以清晰、可控的方式托管多个文档项目同时保留 Read the Docs 平台每个项目独有的全部灵活性。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐在 Read the Docs 上部署 Antora 文档站点.readthedocs.yaml 最小配置与构建原理在 Read the Docs 上部署 Antora 文档站点.readthedocs.yaml 最小配置与构建原理 本指南讲解如何在 Read the Do后端文档Read the Docs 配置全解从零编写 .readthedocs.yaml 到源码级校验原理Read the Docs 配置全解从零编写 .readthedocs.yaml 到源码级校验原理 .readthedocs.yaml 是 Read the后端文档在 Read the Docs 上部署 Docusaurus 站点配置、构建与集成指南在 Read the Docs 上部署 Docusaurus 站点配置、构建与集成指南 导读 本文基于 Read the Docs 官方文档 docs/use后端文档上一篇MediaPipe光流估计重塑视频运动分析的终极解决方案下一篇终极文件编码检测与转换指南EncodingChecker工具完全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考