Sphinx-multiversion扩展无法在HTML导航栏显示标签/分支求助

你遗漏的关键步骤 #

• 未在Sphinx配置文件conf.py中启用sphinx_multiversion扩展，也未设置分支/标签的筛选规则
• 未将自定义的versioning.html模板配置到侧边栏，导致模板无法加载生效
• 未处理两个仓库的关联：你的版本标签都在dev仓库，但sphinx-multiversion默认读取当前文档仓库的分支/标签，需要配置拉取dev仓库的版本源
• ReadtheDocs后台未开启多版本构建，也未适配sphinx-multiversion的构建逻辑

正确显示版本的完整流程 #

一、本地构建调试（先确保本地能正常显示） #

1. 修改conf.py配置

   • 启用扩展：在extensions列表中添加sphinx_multiversion：

     extensions = [
         # 其他已有的扩展
         'sphinx_multiversion'
     ]
     

   • 添加版本筛选规则，指定要展示的分支和标签（比如只包含v开头的正式版本标签）：

     # 只匹配v1.0、v1.1这类格式的标签
     smv_tag_whitelist = r'^v\d+\.\d+$'
     # 只保留main分支作为开发版
     smv_branch_whitelist = r'^main$'
     # 允许读取的远程仓库（后续要添加dev仓作为远程）
     smv_remote_whitelist = r'^(origin|dev)$'
     

   • 配置侧边栏，将自定义的versioning.html加入侧边栏组件：

     html_sidebars = {
         '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html', 'versioning.html']
     }
     

2. 关联dev仓库拉取标签
   进入文档仓库的本地目录，执行以下命令拉取dev仓库的标签：

   git remote add dev https://github.com/dev
   git fetch dev --tags
   

3. 重新构建并验证
   先清理旧构建文件，再执行多版本构建：

   rm -rf build/html
   sphinx-multiversion . build/html
   

   打开build/html/index.html，检查左侧导航栏是否已显示分支和标签入口。

二、ReadtheDocs部署适配 #

1. 配置ReadtheDocs后台

   • 进入项目的「Admin」→「Versions」页面，找到需要展示的标签版本（v1.0、v1.1等），将其标记为「Active」状态
   • 进入「Admin」→「Advanced Settings」，将构建命令修改为：

     sphinx-multiversion docs build/html
     

     注：如果你的文档不在docs目录下，需要对应调整路径

2. 添加RTD构建前的预处理步骤
   在文档仓库根目录创建.readthedocs.yaml文件，添加拉取dev仓库标签的步骤：

   version: 2
   build:
     os: ubuntu-22.04
     tools:
       python: "3.10"
     jobs:
       pre_build:
         - git remote add dev https://github.com/dev
         - git fetch dev --tags
   python:
     install:
       - requirements: docs/requirements.txt  # 确保包含sphinx-multiversion依赖
   

3. 触发构建验证
   在ReadtheDocs后台触发一次新构建，完成后访问站点，检查左侧导航栏是否已显示各版本入口。

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