如何基于多Python仓库在Read the Docs构建单页Sphinx文档？

背景 #

我有一个拆分至多个仓库的开源Python项目，希望在Read the Docs上构建单页Sphinx文档（例如使用sphinx.ext.autosummary）。目前Sphinx的conf.py和主toctree文档存放在独立的docs仓库中，目录结构如下：

docs
├── index.rst
├── conf.py
└── ...
foobar
├── foo
│   └── __init__.py
└── bar
    ├── __init__.py
    └── baz
        └── __init__.py

本地构建文档时，我可以下载所有仓库并使用相对路径（如sys.path.insert(0, os.path.abspath('../foobar'))）引导Sphinx访问不同仓库，但这种方式在Read the Docs上无法生效。我查找后仅找到一种方案：将所有包复制到临时文件夹供文档工具扫描生成文档，还有一种变体是使用符号链接。这些方案似乎并非最优，请问我是否遗漏了Sphinx的某些基础功能？

可行方案 #

1. 配置Read the Docs拉取多仓库 #

利用Read the Docs的构建配置，在构建前拉取所有依赖的代码仓库，让构建环境的目录结构和本地保持一致，这样原有的sys.path配置就能直接复用。

创建或修改.readthedocs.yaml文件，添加仓库克隆步骤：

version: 2

build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
  commands:
    # 将代码仓库克隆到docs的同级目录
    - git clone https://github.com/your-username/foobar.git ../foobar
    # 执行常规Sphinx构建
    - sphinx-build -b html . _build/html

sphinx:
  configuration: conf.py

2. 用sphinx-apidoc指定模块路径 #

如果依赖sphinx-apidoc生成API文档，可以直接通过--module-path参数指定代码仓库位置，无需手动调整sys.path。在conf.py中添加自动生成逻辑：

import subprocess
import os

# 自动生成API文档
subprocess.run([
    "sphinx-apidoc",
    "--module-path", "../foobar",  # 指定模块根路径
    "--output-dir", "./source/api",  # 生成文件的存放目录
    "../foobar/foo",
    "../foobar/bar"
])

3. 可编辑安装代码仓库 #

将各个代码仓库以可编辑模式安装到构建环境，让Python通过包管理直接识别模块，彻底摆脱路径配置。

在项目的requirements.txt中添加：

-e ../foobar

或者在.readthedocs.yaml中配置依赖安装：

python:
  install:
    - requirements: requirements.txt
    - method: pip
      path: ../foobar

关于Sphinx基础功能的说明 #

Sphinx本身没有专门针对多仓库场景的特殊功能，但结合Read the Docs的构建流程和Python的包管理机制，就能实现比复制/符号链接更优雅的方案。核心思路是让构建环境能通过路径识别或包管理找到所有模块，不需要额外的文件移动操作。

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