版本切换器下拉菜单#

您可以在您的站点上添加按钮，允许用户在文档的不同版本之间切换。版本切换器中的链接会根据所查看的文档页面而有所不同。例如，在页面 https://mysite.org/en/v2.0/changelog.html 上，切换器链接将指向其他版本文档中的 changelog.html。当点击时，切换器将检查该页面是否存在，如果不存在，则将重定向到主页（在请求的文档版本中）。

切换器需要以下配置步骤：

  1. 添加 JSON 文件，其中包含切换器应在每个页面上显示的文档版本列表。

  2. 在 conf.py 中的 html_theme_options 字典中添加名为 switcher 的配置字典。switcher 应包含 2 个键：

    • json_url：上述 JSON 文件的持久位置。

    • version_match：字符串，表示当前正在浏览的文档版本。

  3. 指定切换器在页面布局中的位置。例如，将 "version-switcher" 模板添加到 html_theme_options 中的某个布局列表中（例如 navbar_end、footer_start 等）。

以下是这些配置步骤的更详细说明。

警告

现代网络浏览器不允许在通过 file: 协议加载的页面发出请求时加载数据。这意味着如果您在本地构建文档并直接在浏览器中打开其中一个页面，版本切换器将无法加载其 JSON 数据源，最终您将得到空的切换器菜单。可能的解决方法包括：

  1. 通过本地 Web 服务器查看本地构建的文件（Python 为此提供了内置模块：https://docs.python.org/3/library/http.server.html）。

  2. 禁用浏览器的安全设置（通过在启动浏览器时传递命令行标志，或通过浏览器插件）。

添加 JSON 文件来定义切换器的版本#

首先，编写 JSON 文件，说明切换器的下拉菜单中将列出哪些版本的文档。该文件应包含条目列表，每个条目可以包含以下字段：

  • version：版本字符串。这将与 switcher['version_match'] 进行比对，以提供切换器的样式。

  • url：此版本的 URL。

  • name：可选名称，用于在切换器下拉菜单中显示，而不是版本字符串（例如，“latest”、“stable”、“dev”等）。

  • 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 文件时，所有旧版本文档都将获得指向新版本的切换器下拉菜单条目。这可以通过几种不同的方式完成：

  • 该位置可以始终与最新文档构建相关联（即，如果您的文档服务器将“latest”别名为最新版本，它可以指向版本“latest”的构建树中的某个位置）。例如：

    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() }}

将版本切换器插入到主要侧边栏的顶部，同时仍保留其下方的默认导航。有关更多信息，请参阅 主题结构与布局。

设置切换器按钮的样式#

您可以通过 CSS 将样式应用于任何切换器按钮以控制其外观和感觉。每个按钮都有两个 HTML 数据集条目，您可以使用它们将 CSS 规则应用于按钮的子集。这些条目是：

data-version
data-version-name

例如，具有 version="0.2" 和 name="My version" 的条目的链接将具有如下元数据：

<a data-version-name="My version" data-version="0.2" class="<classes...>">

您可以创建选择此元数据的 CSS 规则，如下所示：

// Style all links with a specific subset of versions
.version-switcher__container a[data-version="0.2"],
.version-switcher__container a[data-version="0.3"] {
   background-color: red;
}
// Style all links with `stable` in the version name
.version-switcher__container a[data-version-name*="stable"] {
   background-color: green;
}

此外，下拉列表的父按钮包含有关 当前版本 的类似元数据。这可以用于根据活动版本为整个下拉列表设置特定颜色。

例如，如果您希望在下拉按钮是 dev 版本时使用主题的次要颜色（默认为 PyData 橙色）设置其样式，您可以使用以下 CSS 选择器：

// If the active version has the name "dev", style it orange
.version-switcher__button[data-active-version-name*="dev"] {
   background-color: var(--pst-color-secondary);
}

参见

有关使用和设置这些属性的更多信息，请参阅 MDN 数据集属性文档。