Read the Docs私有GitHub仓库Intersphinx配置问题排查

我正在为多个私有GitHub仓库搭建Read the Docs（Basic Business订阅），想要实现跨项目的intersphinx引用，但遇到了一系列配置问题：

• 报错FileNotFoundError: submodules/project-2/build/html/objects.inv
• 来自https://readthedocs-hosted.com的invalid inventory header导致ValueError
• Intersphinx清单URL重定向错误

已尝试的方案：

• Sphinx multiproject + intersphinx
• 子项目结合intersphinx
• 子模块结合intersphinx（同时将子模块配置为RTD子项目）

当前环境与状态：

• 项目结构：主仓库嵌套子模块形式的子项目
• intersphinx_mapping配置同时指向远程URL和本地objects.inv路径
• 已将RTD公钥添加到主仓库及所有子模块，使用Machine User账号授权RTD访问私有仓库
• 部分引用生效，但多数标签无法识别，RTD输出存在加载intersphinx清单及_static路径不存在的警告

核心疑问：

1. 为什么intersphinx映射无法正确使用本地objects.inv文件？
2. 如何让RTD定位到正确的文件路径？

本地objects.inv无法识别的核心原因 #

1. RTD构建环境路径不匹配
   本地开发的相对路径在RTD的临时构建容器中完全无效——RTD会将仓库克隆到独立的临时目录，子模块的实际存储路径和你本地配置的submodules/project-2/build/html/objects.inv完全不同。更关键的是，RTD默认不会自动构建子模块的文档，所以即使路径正确，objects.inv也根本没有生成。

2. intersphinx本地路径配置逻辑错误
   intersphinx的本地路径是相对于当前Sphinx项目conf.py所在目录的，但RTD中每个子项目的构建流程是独立的，主项目构建时无法直接访问子项目的构建产物目录。

3. 无效清单与重定向的根源
   你配置的远程URL可能指向了未授权的私有文档地址或无效预览链接，导致返回的不是标准objects.inv文件（比如重定向到登录页、404页面），进而触发invalid inventory header错误。

修复步骤 #

1. 放弃本地路径，统一使用RTD远程inventory URL #

既然已将子模块配置为RTD子项目，直接用子项目的正式文档URL配置intersphinx_mapping，格式如下：

intersphinx_mapping = {
    'project2': ('https://project-2.readthedocs.io/en/latest/', None)
}

• 无需指定本地路径，intersphinx会自动从远程拉取objects.inv
• 确保子项目的RTD文档已成功构建，且同属一个RTD团队的私有项目（Basic Business订阅支持跨私有项目的intersphinx访问）

2. 修正子项目的RTD构建配置 #

• 每个子模块对应的RTD项目必须开启私有文档选项，且使用同一个Machine User账号授权
• 子项目的构建触发条件设置为「主项目构建时同步触发」，或手动确保子项目的文档版本与主项目引用的版本一致

3. 完善主项目的子模块克隆配置 #

• 在主项目的RTD设置中，进入Advanced Settings，勾选「Clone submodules」并选择「Recursively clone submodules」（若子模块有嵌套）
• 主项目仅负责自身文档构建，跨项目引用完全通过RTD远程inventory实现，不要依赖子模块的本地构建产物

4. 排查重定向与无效清单问题 #

• 手动访问子项目的objects.inv URL（例如https://project-2.readthedocs.io/en/latest/objects.inv），确认能下载到有效文件（打开后开头应为# Sphinx inventory version 2）
• 若访问跳转到登录页，检查子项目的RTD权限设置：确保主项目所属团队被添加到子项目的「Permissions」列表中

5. 开启intersphinx调试日志 #

在主项目的conf.py中添加以下代码，构建时会输出intersphinx拉取清单的详细日志，方便定位问题：

import logging
logging.basicConfig(level=logging.INFO)

内容的提问来源于stack exchange，提问作者CodeWanderer42