配置

主题选项

以下选项可以在项目的 conf.py 文件中定义，使用 html_theme_options 配置选项。

例如

html_theme_options = {
    'analytics_id': 'G-XXXXXXXXXX',  #  Provided by Google in your dashboard
    'analytics_anonymize_ip': False,
    'logo_only': False,
    'prev_next_buttons_location': 'bottom',
    'style_external_links': False,
    'vcs_pageview_mode': '',
    'style_nav_header_background': 'white',
    'flyout_display': 'hidden',
    'version_selector': True,
    'language_selector': True,
    # Toc options
    'collapse_navigation': True,
    'sticky_navigation': True,
    'navigation_depth': 4,
    'includehidden': True,
    'titles_only': False
}

目录选项

以下选项会更改 toctree 指令生成文档导航的方式。

collapse_navigation

启用此选项后，导航条目不可展开 - 每个条目旁边的 [+] 图标将被移除。

类型:: 布尔值
默认值:: True

注意

将 collapse_navigation 设置为 False 并在具有许多文件和深度文件结构的项目上对 navigation_depth 使用较高的值可能会导致编译时间过长，并可能导致 HTML 文件的大小显着增加。

sticky_navigation

在您滚动页面时，将导航与主页面内容一起滚动。

类型:: 布尔值
默认值:: True

navigation_depth

目录树的最大深度。将其设置为 -1 以允许无限深度。

类型:: 整数
默认值:: 4

includehidden

指定导航是否包含隐藏的目录 - 即任何标记有 :hidden: 选项的 toctree 指令。

类型:: 布尔值
默认值:: True

titles_only

启用后，页面副标题不会包含在导航中。

类型:: 布尔值
默认值:: False

其他选项

analytics_id

如果指定，则 Google Analytics 的 gtag.js 将包含在您的页面中。将值设置为 Google 提供给您的 ID（例如 UA-XXXXXXX 或 G-XXXXXXXXXX）。

类型:: 字符串

自版本 3.0.0 起已弃用: analytics_id 选项已弃用，请改用 sphinxcontrib-googleanalytics 扩展。

analytics_anonymize_ip

在 Google Analytics 中匿名化访客 IP 地址。

类型:: 布尔值
默认值:: False

自版本 3.0.0 起已弃用: analytics_anonymize_ip 选项已弃用，请改用 sphinxcontrib-googleanalytics 扩展。

canonical_url

这将指定一个规范 URL 元链接元素，以告诉搜索引擎哪个 URL 应被评为文档的主要 URL。如果您有多个 URL 可用于您的文档，这一点非常重要。该 URL 指向文档的根路径，并且需要尾部斜杠。

类型:: URL

自版本 0.6.0 起已弃用: 请改用 html_baseurl。

display_version

如果 True，则版本号将显示在侧边栏顶部。

类型:: 布尔值
默认值:: False

自版本 3.0.0 起已弃用: 已删除，取而代之的是 version_selector 和 language_selector。

logo_only

仅显示徽标图像，不要在侧边栏顶部显示项目名称

类型:: 布尔值
默认值:: False

prev_next_buttons_location

显示下一个和上一个按钮的位置。这可以是 bottom、top、both 或 None。

类型:: 字符串
默认值:: bottom

style_external_links

在外部链接旁边添加一个图标。

类型:: 布尔值
默认值:: False

vcs_pageview_mode

更改使用 display_github、display_gitlab 等时查看文件的方式。使用 GitHub 或 GitLab 时，这可以是：blob（默认）、edit 或 raw。在 Bitbucket 上，这可以是：view（默认）或 edit。

类型:: 字符串
默认值:: blob 或 view

style_nav_header_background

更改导航栏中搜索区域的背景。该值可以在 CSS background 属性中使用任何有效值。

类型:: 字符串
默认值:: #2980B9

flyout_display

指定如何显示浮出层（语言和版本选择器）。这可以是 attached 或 hidden。attached 表示它将在侧边栏底部显示浮出层。您需要禁用默认的 Read the Docs 浮出层以避免显示两个浮出层。

类型:: 字符串
默认值:: hidden

version_selector

在标题下方显示版本选择器。此功能利用 Read the Docs 附加组件实现，因此需要将文档托管在 Read the Docs 上。只有当有多个活动版本时才会出现。

类型:: 布尔值
默认值:: True

language_selector

在标题下方显示语言选择器。此功能利用 Read the Docs 附加组件实现，因此需要在 Read the Docs 上提供文档服务。只有当有多种活动语言时才会出现。

类型:: 布尔值
默认值:: True

文件级元数据

以下选项可用作文件级元数据

github_url: 强制在 GitHub 上编辑按钮使用配置的 URL。

bitbucket_url: 强制在 Bitbucket 上编辑按钮使用配置的 URL。

gitlab_url: 强制在 GitLab 上编辑按钮使用配置的 URL。

其他配置

添加徽标

使用 Sphinx 标准选项 html_logo，您可以设置一个图像文件作为侧边栏顶部的徽标。主题选项 logo_only 还允许仅显示徽标在侧边栏顶部。

添加自定义 CSS 或 Javascript

添加自定义 CSS 或 Javascript 可以帮助您更改此主题的外观，而无需为本地使用派生主题。

为了添加自定义 CSS 或 Javascript 而不干扰现有的主题文件，您可以添加要包含在文档输出中的文件。

目录显示方式

当前，左侧菜单将根据源文件中定义的任何 toctree 指令构建。它默认输出 4 个级别的深度，以便快速浏览主题。如果未定义任何 TOC 树，则 Sphinx 的默认行为是改为使用页面标题。

需要注意的是，如果您在不同文档中没有遵循相同的 reST 标题样式，TOC 树将构建不正确，并且生成的菜单在渲染时可能无法显示正确的深度。

另请注意，默认情况下，目录设置为 includehidden=True。这允许您在索引文件中使用 :hidden: 属性设置隐藏的 TOC，这将允许您构建 TOC 而无需在索引中渲染它。

默认情况下，导航在您滚动时会“粘贴”到屏幕上。但是，如果您的 TOC 不够高，它将恢复为静态定位。要完全禁用粘性导航，请更改 sticky_navigation 主题选项。