如何生成分离源码的多版本Sphinx文档并支持侧边栏版本切换？

核心思路是构建每个版本文档时动态加载对应版本的源码到Python运行路径，无需全局安装多版本的目标包，原有autoclass指令可以完全复用。

1. 配置conf.py动态导入对应版本源码 #

在Sphinx项目的conf.py头部添加如下代码，将对应版本的源码根目录加入Python搜索路径：

import os
import sys

# 替换为当前构建版本对应的源码根目录路径
# 若使用sphinx-multiversion，可直接通过内置环境变量/版本参数拼接对应源码路径
# 若文档与源码同仓库不同tag，直接写相对路径即可，比如sys.path.insert(0, os.path.abspath('../src'))
sys.path.insert(0, os.path.abspath("/path/to/current/version/source/root"))

配置完成后，autodoc会直接从指定路径读取对应版本的类、函数定义，不需要提前将包安装到全局Python环境。

2. 适配sphinx-multiversion构建流程 #

• 先在conf.py中完成sphinx-multiversion的基础配置，指定需要构建的版本范围（分支、tag、commit列表）
• 如果文档与源码完全分离，可在构建脚本中增加逻辑：每次构建某一版本前，先拉取对应版本的源码到临时目录，再将临时目录路径传入conf.py的路径配置中
• 原有.. autoclass:: packagename.Classname :members:指令不需要做任何修改，构建时会自动匹配当前版本的源码内容

3. 复杂场景适配 #

如果你的包包含需要编译的C扩展或者特定依赖，可以为每个版本单独创建虚拟环境，提前在对应虚拟环境中安装依赖，sphinx-multiversion支持自定义构建命令，只需将激活对应版本虚拟环境的步骤加入构建钩子即可正常生成文档。

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