版本切换下拉菜单#
您可以向您的网站添加一个按钮，允许用户在文档的不同版本之间切换。版本切换器中的链接将根据查看文档的页面而有所不同。例如，在页面 https://mysite.org/en/v2.0/changelog.html 上，切换器链接将指向您文档其他版本中的 changelog.html。单击时，切换器会检查该页面的存在性，如果不存在，则会重定向到主页（在您请求的文档版本中）。
切换器需要以下配置步骤
添加一个 JSON 文件，其中包含切换器应在每个页面上显示的文档版本列表。
在
conf.py中的html_theme_options字典中添加一个名为switcher的配置字典。switcher应该有两个键json_url：上述 JSON 文件的持久位置。version_match：一个字符串，说明当前正在浏览的文档版本。
指定在页面布局中放置切换器的位置。例如，将
"version-switcher"模板添加到html_theme_options中的某个布局列表（例如，navbar_end、footer_start等）。
下面将更详细地描述每个配置步骤。
添加 JSON 文件以定义切换器的版本#
首先，编写一个 JSON 文件，说明您文档的哪些版本将列在切换器下拉菜单中。该文件应包含一个条目列表，每个条目可以包含以下字段
version：一个版本字符串。这将与switcher['version_match']进行检查，以便为切换器提供样式。url：此版本的 URL。name：一个可选的名称，在切换器下拉菜单中显示，而不是版本字符串（例如，“最新”、“稳定”、“开发”等）。preferred：一个可选字段，在 JSON 文件中的最多一个条目上出现。它指定哪个版本被认为是“最新稳定版”，用于自定义 版本警告横幅 上使用的消息（如果已启用）。
这是一个 JSON 文件示例
[
{
"name": "v2.1 (stable)",
"version": "2.1",
"url": "https://mysite.org/en/2.1/"
},
{
"version": "2.1rc1",
"url": "https://mysite.org/en/2.1rc1/"
},
{
"version": "2.0",
"url": "https://mysite.org/en/2.0/"
},
{
"version": "1.0",
"url": "https://mysite.org/en/1.0/"
}
]
有关将 JSON 文件保存在何处的选项，请参见下面的 switcher['json_url'] 讨论。
配置 switcher['json_url']#
JSON 文件需要位于稳定的、持久的、完全解析的 URL 上（即，不要指定为相对于当前文档构建的 Sphinx 根目录的路径）。您文档的每个版本都应指向同一个 URL，以便在向 JSON 文件中添加新版本时，所有旧版本文档都将获得指向新版本的切换器下拉菜单条目。这可以通过几种不同的方式完成
该位置可能始终与最新的文档构建相关联（即，如果您的文档服务器将“最新”别名为最新版本，它可以指向版本“最新”的构建树中的某个位置）。例如
html_theme_options = { ..., "switcher": { "json_url": "https://mysite.org/en/latest/_static/switcher.json", } }
在这种情况下，JSON 与文档页面的其余部分一起进行版本控制，但仅加载最新版本（即使是旧版本的文档）。
JSON 可以存储在文档构建树之外。这可能意味着它将位于软件仓库之外，并且您需要在发布过程中手动将新版本条目添加到 JSON 文件中。例如
html_theme_options = { ..., "switcher": { "json_url": "https://mysite.org/switcher.json", } }
理论上，JSON 可以保存在您网站
html_static_path配置下列出的文件夹中，但不推荐这样做。如果您想以这种方式执行此操作，请参阅 Sphinx 静态路径文档 了解详细信息，但请注意我们不支持此用例。
默认情况下，主题会测试提供的 .json 文件，并在 Sphinx 构建中输出警告。如果此测试破坏了您文档的流水线，则可以通过在 conf.py 中配置 check_switcher 参数来禁用此测试
html_theme_options = {
# ...
"check_switcher": False
}
配置 switcher['version_match']#
此配置值告诉切换器当前正在查看哪个文档版本，用于为切换器设置样式（即，在切换器下拉菜单中突出显示当前文档版本，并更改切换器按钮上显示的文本）。
通常，您可以将 Sphinx 变量 version 或 release 中的其中一个作为 switcher['version_match'] 的值重复使用；您使用哪个取决于文档版本控制的粒度。有关详细信息，请参阅 Sphinx “项目信息” 文档。例如
version = my_package_name.__version__.replace("dev0", "") # may differ
html_theme_options = {
...,
"switcher": {
"version_match": version,
}
}
指定切换器显示的位置#
最后，告诉主题您希望在网站页面的哪个位置显示切换器。这里有很多选择：您可以将 "version-switcher" 添加到 html_theme_options 中的某个位置（例如，navbar_end、footer_start 等）。例如
html_theme_options = {
...,
"navbar_start": ["navbar-logo", "version-switcher"]
}
或者，您可以覆盖其他某个模板，以在侧边栏中包含版本切换器。例如，您可以将 _templates/sidebar-nav-bs.html 定义为
{%- include 'version-switcher.html' -%}
{{ super() }}
在主侧边栏顶部插入版本切换器，同时保留其下方的默认导航。有关详细信息，请参阅 主题结构和布局。