Sphinx Read the Docs主题侧边栏版本功能启用及配置问题

一、修复versions.html侧边栏不显示的问题 #

你遇到的html_sidebars设置不生效，大概率是因为Read the Docs（RTD）主题本身自带默认侧边栏配置，直接用**覆盖会和主题内置逻辑冲突。试试这两个方案：

• 保留主题默认侧边栏，追加versions.html
  不要直接替换所有侧边栏项，先获取主题默认的侧边栏列表，再把versions.html加进去。在conf.py里这么写：

  from sphinx_rtd_theme import get_html_theme_options
  
  # 获取RTD主题默认的侧边栏配置
  default_sidebars = get_html_theme_options().get('sidebars', [])
  # 将versions.html追加到默认侧边栏末尾
  html_sidebars = {
      '**': default_sidebars + ['versions.html']
  }
  

• 确认versions.html模板存在
  要确保你的项目_templates目录下有versions.html（如果是自定义模板），或者RTD主题自带这个模板。如果是自定义模板，别忘了在conf.py中设置：

  templates_path = ['_templates']
  

二、在conf.py中声明不同版本（无需sphinxcontrib-versioning） #

既然sphinxcontrib-versioning不符合需求，这里提供几种手动管理版本的方式：

1. 直接在conf.py中硬编码版本信息 #

适合版本较少的场景，在conf.py里定义相关变量，供模板调用：

# 当前文档的版本号
version = '1.0'
release = '1.0.1'
# 所有可用的版本列表
available_versions = ['1.0', '0.9', '0.8']
# 标记最新版本
latest_version = '1.0'

然后在自定义的versions.html模板中使用这些变量生成版本链接：

<h3>Versions</h3>
<ul>
  {% for v in available_versions %}
    <li>
      <a href="/docs/{{ v }}/">
        {{ v }}{% if v == latest_version %} (latest){% endif %}
      </a>
    </li>
  {% endfor %}
</ul>

2. 从外部文件加载版本列表 #

如果版本较多不想硬编码，可以把版本信息存在JSON文件（比如versions.json），再在conf.py中读取：

import json

with open('versions.json', 'r') as f:
    version_data = json.load(f)

available_versions = version_data['versions']
latest_version = version_data['latest']

versions.json的示例内容：

{
  "versions": ["1.0", "0.9", "0.8", "0.7"],
  "latest": "1.0"
}

3. 结合Read the Docs环境变量（托管在RTD平台时） #

如果你的文档在Read the Docs平台部署，RTD会自动提供环境变量，可动态获取版本信息：

import os

# 当前构建的版本
version = os.environ.get('READTHEDOCS_VERSION', 'latest')
# 所有可用版本（RTD返回逗号分隔的字符串）
available_versions = os.environ.get('READTHEDOCS_VERSIONS', 'latest').split(',')

在versions.html中可以用RTD的标准链接格式生成跳转：

<h3>Versions</h3>
<ul>
  {% for v in available_versions %}
    <li>
      <a href="https://your-project.readthedocs.io/en/{{ v }}/">
        {{ v }}{% if v == 'latest' %} (latest){% endif %}
      </a>
    </li>
  {% endfor %}
</ul>

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