Read the Docs 子项目（Subprojects）完全指南：多项目文档聚合、自定义域名共享与跨项目联合搜索

后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载Read the Docs 提供的子项目Subprojects机制让你可以把多个相互独立维护的文档项目嵌套聚合到同一个主项目网站下统一呈现共享搜索索引、命名空间与自定义域名同时各项目仍保持各自的版本与发布节奏。本文以官方文档 docs/user/subprojects.rst 为骨架融合 docs/user/guides/subprojects.rst 的操作指南与本仓库的源码实现ProjectRelationship模型、URL Resolver、搜索 API系统讲解子项目的 URL 结构、别名机制、域名共享与联合搜索原理并给出可复现的添加、更新、删除完整流程。什么是子项目子项目Subprojects是 Read the Docs 中一种项目到项目的关系把其他project配置为main project主项目的subproject使其文档通过主项目的域名与命名空间对外提供。这样做的好处是共享一个搜索索引与命名空间或自定义域名读者无需在多个站点间跳转文档项目仍可独立维护主项目与子项目各自拥有独立的代码仓库、构建配置与版本管理聚合统一入口一套域名即可承载整套生态文档。该功能主要适用于以下三类场景需要把所有项目集中展示在一个文档门户或落地页的组织需要为多个包或扩展分别撰写、发布文档的项目希望为多套文档提供统一搜索功能的组织或项目。以一个主项目example-project为例其子项目example-project-plugin的 URL 形态如下主项目https://example-project.readthedocs.io/en/latest/ 子项目https://example-project.readthedocs.io/projects/plugin/en/latest/可以看到子项目的文档挂在主项目域名的/projects/别名/路径下而不是自己的独立域名。子项目的 URL 结构与其底层解析原理子项目 URL 的核心规律是文档永远从父项目主项目的域名下提供服务路径前缀为/projects/alias/。这一逻辑在本仓库的 URL Resolver 中直接体现。在 readthedocs/core/resolver.py 的base_resolve_path方法中路径由以下几个部分依次拼接而成若传入project_relationship即该请求属于某个子项目关系则先拼上project_relationship.subproject_prefix若项目配置了自定义前缀custom_prefix再拼接该前缀最后依据版本化方案versioning scheme拼接lang/version/filename或version/filename或仅filename。因此常见的解析结果包括# 默认多版本、多语言 /projects/subproject_alias/lang/version/filename # 单版本模式Single Version /projects/subproject_alias/filename其中subproject_prefix定义在 readthedocs/projects/models.py 的ProjectRelationship模型中cached_property def subproject_prefix(self): prefix self.parent.custom_subproject_prefix or /projects/ return unsafe_join_url_path(prefix, self.alias, /)即默认前缀固定为/projects/若父项目配置了自定义子项目前缀custom_subproject_prefix则优先使用它。get_subproject_url_prefix见 readthedocs/core/resolver.py则负责生成形如https://docs.example.com/projects/project-slug/的前缀 URL。从源码结构看Read the Docs最多支持两层嵌套子项目 翻译_get_canonical_projectreadthedocs/core/resolver.py的注释明确说明不支持超过两层的子项目/翻译嵌套——即主项目可下挂子项目子项目本身不能再作为其他项目的父项目嵌套更深层级。共享自定义域名子项目最常见的用途之一就是让多套文档共享同一个自定义域名。配置方式如下选定一个项目作为主项目为其配置自定义域名例如docs.example.com把其他项目作为子项目添加到主项目下。沿用前文的例子若example-project配置了自定义域名docs.example.com且example-project-plugin以别名plugin挂载则两者的访问地址分别为example-project https://docs.example.com/en/latest/ example-project-plugin https://docs.example.com/projects/plugin/en/latest/自定义域名的共享机制并不复杂既然子项目永远从父项目的域名提供服务父项目配置的域名自然就覆盖了所有子项目读者只需记住一个域名即可访问整套文档。子项目上的自定义域名是不允许的与主项目不同给子项目单独添加自定义域名是不被允许的。原因正如官方文档所解释的子项目的文档永远从父项目的域名下提供服务为其配置独立域名在架构上既不必要也不支持。如果你希望某套文档拥有独立的品牌域名正确做法是把它设计为主项目再将其余项目作为子项目挂载到它下面。使用别名Aliases精细化控制 URL默认情况下子项目在 URL 中暴露的是其 Read the Docs 项目slug即example-project-plugin这样的标识符。通过为子项目设置别名Alias你可以覆盖访问它的 URL 路径段更自由地设计项目间的 URL 结构。命名建议主项目名-前缀官方文档建议子项目的项目名与 slug 可以任意设置但最好以主项目名作为前缀。典型做法是主项目名为example-project子项目名为plugin子项目的 Read the Docs 项目 slug 即为example-project-plugin添加子项目时把别名设置为plugin于是访问 URL 变为example-project.readthedocs.io/projects/plugin。这样既能在项目列表中清晰看出从属关系又能让对外 URL 保持简短、可读。添加子项目后原域名自动重定向一个容易忽略的行为是当你把某个项目添加为子项目后它就不再从自己的独立域名直接提供服务了。例如example-project-plugin.readthedocs.io/会重定向到example-project.readthedocs.io/projects/plugin。换句话说子项目的家从自己的域名搬到了主项目的/projects/路径下——这正是共享命名空间与统一入口的实现方式。别名的底层校验与默认值别名的行为在 readthedocs/projects/models.py 的ProjectRelationship.alias字段中定义字段允许为空nullTrue, blankTrue但save()方法会在未提供别名时自动回退为子项目的 slugself.alias self.child.slug保证 URL 始终稳定可用别名通过正则校验器约束错误提示为Aliases can contain letters, numbers, underscores, and hyphens.即只允许字母、数字、下划线与连字符从字段注释还可以看到别名支持形如api/python的多段路径由/连接让主项目可以在/projects/api/python/下呈现出嵌套子项目的效果——但该能力仅在项目启用ALLOW_SLASHES_IN_SUBPROJECT_ALIAS特性开关时才可用。此外readthedocs/projects/forms.py 中的ProjectRelationshipForm负责添加/更新关系的表单校验clean_alias会检查主项目下是否已存在相同别名的子项目若冲突则抛出 A subproject with this alias already exists 校验错误确保同一父项目内别名唯一。自定义/projects/前缀默认的子项目前缀是/projects/而在 Read the Docs 商业版 Pro 计划及更高版本上你可以自定义甚至完全移除该前缀详见 docs/user/url-path-prefixes.rst。这一能力对应Project.custom_subproject_prefix字段并会直接作用于上文提到的subproject_prefix计算逻辑从而改变所有子项目对外 URL 的形态。独立的发布周期与版本管理子项目的另一大价值是解耦发布周期主项目拥有自己的版本与发布releases每个子项目也各自维护独立的版本与发布官方建议文档跟随其描述的软件本身的发布节奏因此子项目应自由采用自己的发布周期而不必与主项目对齐。这种各管各的版本的体验是通过独立的 flyout menu版本切换菜单实现的当读者在主项目页面时看到的是主项目的版本列表与离线格式offline formats当导航进入某个子项目时flyout menu 会自动切换为该子项目自己的版本列表与离线格式。也就是说切换文档项目的同时版本选择器也随之切换到对应项目的版本集合。关于每个项目各自的版本构建、激活与发布行为可参考 docs/user/versions.rst 与 docs/user/offline-formats.rst。跨项目的联合搜索子项目关系在搜索层面带来了一项独特能力在主项目上搜索结果会同时包含其所有子项目的内容并且读者可以直接在搜索弹窗中按子项目过滤结果。版本匹配规则联合搜索在版本上的行为遵循一套明确的规则官方文档表述若在主项目的v1版本上搜索会包含各子项目v1版本的结果对于没有v1版本的子项目则回退到使用该子项目的默认版本。这一逻辑在源码中有直接对应实现readthedocs/search/api/v2/views.py 的_get_projects_to_search方法先确定主项目及其当前版本通过Project.objects.filter(superprojects__parent_idmain_project.id)取出所有子项目对每个子项目先尝试按主项目的版本 slug如v1获取对应版本若该子项目不存在此版本则回退到subproject.default_version最后用_has_permission校验权限后加入待搜索项目集合。也就是说主项目搜v1、子项目无v1则用默认版本的规则是搜索引擎的实际执行逻辑而非仅停留在文档层面。共享搜索的边界需要特别留意的是联合搜索目前是项目间共享搜索结果的唯一途径。Read the Docs 暂不支持在兄弟子项目之间或任意两个项目之间直接共享搜索结果——想实现多项目统一搜索就必须通过主项目-子项目的关系把它们组织起来。关闭搜索弹窗中的子项目过滤如果你不希望读者在搜索弹窗中看到子项目过滤器可以进入主项目的Settings左侧边栏Search分类下关闭Show subprojects filter in search modal选项。这一设置对应的模型字段为search_show_subprojects_filter见 readthedocs/projects/forms.py 及其迁移 readthedocs/projects/migrations/0158_add_search_subproject_filter_option.py属于项目级配置。注意关闭过滤器只影响搜索弹窗中过滤入口的显示并不改变子项目结果本身参与联合搜索的行为。实战添加、更新与删除子项目下面按 docs/user/guides/subprojects.rst 给出子项目全生命周期的管理步骤。添加子项目将两个已有项目建立关联步骤如下进入将要作为**父项目主项目**的项目的Settings -- Subprojects页面点击Add subproject在弹出的Subproject下拉框中选择要连接为子项目的项目可选若希望子项目在 URL 中使用与项目名不同的名字填写Alias字段否则留空系统会自动使用子项目的 slug 作为别名点击Add subproject完成添加。添加完成后子项目的访问 URL 会立即变为列表中显示的新 URL即主项目域名下的/projects/alias/路径。权限要求务必注意对 Read the Docs 组织版org用户你必须是该子项目的maintainer才能在主项目中选中它对 Read the Docs 商业版com用户你对该子项目需要拥有admin管理员访问权限才能在主项目中选中它。更新子项目在子项目列表中点击配置按钮编辑图标进入更新页可以通过Subproject下拉框更换关联的子项目修改Alias字段调整其 URL 路径别名然后点击Update subproject保存。保存后该子项目文档的服务 URL 会同步更新为新的路径。删除子项目在子项目列表中点击删除按钮并在弹出的确认框中确认删除即可。删除后子项目关系被移除原本作为子项目的项目恢复从它自己的独立域名提供服务例如回到example-project-plugin.readthedocs.io两个项目本身都不会被删除被移除的只是主项目—子项目这一层关联关系。延伸阅读docs/user/subprojects.rst子项目特性的官方总览本文主体文档docs/user/guides/subprojects.rst子项目的创建与管理操作指南docs/user/guides/intersphinx.rst如何在不同的 Sphinx 项目之间例如子项目之间建立交叉引用docs/user/url-path-prefixes.rst自定义或移除/projects/前缀Pro 计划及以上readthedocs/projects/models.pyProjectRelationship模型子项目关系的存储与别名默认值逻辑readthedocs/core/resolver.py子项目 URL 的路径解析实现readthedocs/search/api/v2/views.py联合搜索中子项目版本匹配的实现。总结来说子项目是 Read the Docs 组织多套文档的核心机制它用一个主项目域名聚合全部文档、共享搜索与命名空间同时让每个子项目保有独立的版本与发布节奏理解其 URL 解析、别名规则与搜索版本回退逻辑你就能在门户式文档站点的规划中做出正确的架构决策。赞分享后端文档【免费下载链接】readthedocs.orgThe source code that powers readthedocs.org项目地址https://gitcode.com/gh_mirrors/re/readthedocs.org点击查看免费下载相关推荐Read the Docs 子项目Subprojects管理与自定义域名共享实战指南Read the Docs 子项目Subprojects管理与自定义域名共享实战指南 子项目Subprojects是 Read the Docs 提供的后端文档Read the Docs自定义域名终极指南5分钟让你的文档拥有专业域名想要为你的技术文档打造专业形象吗Read the Docs自定义域名功能让你的文档摆脱默认子域名的束缚使用完全属于你自己的域名 无论你是个人开发者还是后端文档Read the Docs 自定义域名完整指南配置、SSL、DNS 与故障排查Read the Docs 自定义域名完整指南配置、SSL、DNS 与故障排查 本文基于 readthedocs.org 仓库中的官方指南 docs/user后端文档上一篇Solidus 开源电商平台使用指南下一篇快速SQL备忘录项目文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考