HTML 主题

Sphinx 提供了许多用于 HTML 和基于 HTML 的格式的构建器。

构建器

主题

版本 0.6 中新增。

注意

本节提供了有关使用预先存在的 HTML 主题的信息。如果您希望创建自己的主题，请参阅 HTML 主题开发。

Sphinx 支持通过主题更改其 HTML 输出的外观。主题是 HTML 模板、样式表和其他静态文件的集合。此外，它还有一个配置文件，该文件指定要继承哪个主题，要使用哪个突出显示样式，以及主题外观和风格的自定义选项。

主题旨在与项目无关，因此它们可以在不同的项目中使用而无需更改。

使用主题

使用 Sphinx 提供的主题 很容易。由于这些不需要安装，您只需要设置 html_theme 配置值。例如，要启用 classic 主题，请将以下内容添加到 conf.py 中

html_theme = "classic"

您还可以使用 html_theme_options 配置值设置特定于主题的选项。这些选项通常用于更改主题的外观和风格。例如，要将侧边栏放置在右侧，并将关系栏（页面顶部和底部的导航链接栏）设置为黑色背景，请将以下内容添加到 conf.py 中

html_theme_options = {
    "rightsidebar": "true",
    "relbarbgcolor": "black"
}

如果主题没有随 Sphinx 一起提供，它可以以两种静态形式或作为 Python 包存在。对于静态形式，支持目录（包含 theme.toml 和其他所需文件）或具有相同内容的 zip 文件。目录或 zip 文件必须放在 Sphinx 可以找到它的地方；为此，可以使用配置值 html_theme_path。这可以是目录列表，相对于包含 conf.py 的目录，这些目录可以包含主题目录或 zip 文件。例如，如果您在文件 blue.zip 中有一个主题，您可以将其直接放在包含 conf.py 的目录中，并使用以下配置

html_theme = "blue"
html_theme_path = ["."]

第三种形式是 Python 包。如果您要使用的主题作为 Python 包分发，则可以在安装后使用它

# installing theme package
$ pip install sphinxjp.themes.dotted

安装后，可以像使用基于目录或 zip 文件的主题一样使用它

html_theme = "dotted"

有关主题设计的更多信息，包括有关编写自己的主题的信息，请参阅 HTML 主题开发。

内置主题

主题概述
alabaster	classic
sphinxdoc	scrolls
agogo	traditional
nature	haiku
pyramid	bizstyle

Sphinx 附带了一系列可供选择的主题。

请注意，在这些主题中，只有 Alabaster 和 Scrolls 主题经过移动设备优化，其他主题如果屏幕太窄则会使用水平滚动。

这些主题是

基本的

这是一种基本上没有样式的布局，用作其他主题的基础，也可作为自定义主题的基础。HTML 包含所有重要的元素，如侧边栏和关系栏。它有以下选项（其他主题会继承这些选项）

• nosidebar（true 或 false）：不包含侧边栏。默认为 False。

• sidebarwidth（int 或 str）：侧边栏的宽度，以像素为单位。这可以是一个整数，解释为像素，也可以是一个有效的 CSS 尺寸字符串，例如 '70em' 或 '50%'。默认为 230 像素。

• body_min_width（int 或 str）：文档正文的最小宽度。这可以是一个整数，解释为像素，也可以是一个有效的 CSS 尺寸字符串，例如 '70em' 或 '50%'。如果不想设置宽度限制，请使用 0。默认值可能取决于主题（通常为 450px）。

• body_max_width（int 或 str）：文档正文的最大宽度。这可以是一个整数，解释为像素，也可以是一个有效的 CSS 尺寸字符串，例如 '70em' 或 '50%'。如果不想设置宽度限制，请使用 'none'。默认值可能取决于主题（通常为 800px）。

• navigation_with_keys（true 或 false）：允许使用以下键盘快捷键进行导航

  • 左 箭头：上一页

  • 右 箭头：下一页

  默认为 False。

• enable_search_shortcuts（true 或 false）：允许使用 / 跳到搜索框，并允许使用 Esc 移除搜索高亮。

  默认为 True。

• globaltoc_collapse（true 或 false）：仅在 globaltoc.html 中展开当前文档的子部分（请参阅 html_sidebars）。默认为 True。

  版本 3.1 中新增。

• globaltoc_includehidden（true 或 false）：即使在 globaltoc.html 中（请参阅 html_sidebars）也显示那些使用 toctree 指令的 :hidden: 标记包含的子部分。默认为 False。

  版本 3.1 中新增。

• globaltoc_maxdepth（int）：globaltoc.html 中 toctree 的最大深度（请参阅 html_sidebars）。将其设置为 -1 以允许无限深度。默认为在 toctree 指令中选择的最大深度。

  版本 3.2 中新增。

alabaster

Alabaster 主题 是 @kennethreitz 的修改版“Kr” Sphinx 主题（尤其是在其 Requests 项目中使用），该主题本身最初基于 @mitsuhiko 用于 Flask 及相关项目的主题。有关如何配置 html_sidebars 以供其使用，请参阅其 安装页面。

classic

这是经典主题，看起来像 Python 2 文档。它可以通过以下选项进行自定义

• rightsidebar（true 或 false）：将侧边栏放在右侧。默认为 False。

• stickysidebar（true 或 false）：使侧边栏“固定”，以便在较长的正文内容中不会滚动出视野。这可能不适用于所有浏览器。默认为 False。

• collapsiblesidebar（true 或 false）：添加一个实验性的 JavaScript 代码片段，该片段可以通过其侧面的按钮使侧边栏可折叠。默认为 False。

• externalrefs（true 或 false）：以与内部链接不同的方式显示外部链接。默认为 False。

还有各种颜色和字体选项，可以更改配色方案，而无需编写自定义样式表

• footerbgcolor（CSS 颜色）：页脚行的背景颜色。

• footertextcolor（CSS 颜色）：页脚行的文本颜色。

• sidebarbgcolor（CSS 颜色）：侧边栏的背景颜色。

• sidebarbtncolor（CSS 颜色）：侧边栏折叠按钮的背景颜色（当collapsiblesidebar 为 True 时使用）。

• sidebartextcolor（CSS 颜色）：侧边栏的文本颜色。

• sidebarlinkcolor（CSS 颜色）：侧边栏的链接颜色。

• relbarbgcolor（CSS 颜色）：关系栏的背景颜色。

• relbartextcolor（CSS 颜色）：关系栏的文本颜色。

• relbarlinkcolor（CSS 颜色）：关系栏的链接颜色。

• bgcolor（CSS 颜色）：正文的背景颜色。

• textcolor（CSS 颜色）：正文的文本颜色。

• linkcolor（CSS 颜色）：正文的链接颜色。

• visitedlinkcolor（CSS 颜色）：正文中已访问链接的颜色。

• headbgcolor（CSS 颜色）：标题的背景颜色。

• headtextcolor（CSS 颜色）：标题的文本颜色。

• headlinkcolor（CSS 颜色）：标题的链接颜色。

• codebgcolor（CSS 颜色）：代码块的背景颜色。

• codetextcolor（CSS 颜色）：代码块的默认文本颜色，如果突出显示样式未设置其他颜色。

• bodyfont（CSS 字体系列）：普通文本的字体。

• headfont（CSS 字体系列）：标题的字体。

sphinxdoc

此文档最初使用的主题。它在右侧有一个侧边栏。目前除了nosidebar 和sidebarwidth 之外没有其他选项。

注意

Sphinx 文档现在使用 调整后的 sphinxdoc 主题版本。

scrolls

一个更轻量级的主题，基于 Jinja 文档。以下颜色选项可用

• headerbordercolor

• 副标题颜色

• 链接颜色

• 已访问链接颜色

• 警告颜色

agogo

由 Andi Albrecht 创建的主题。支持以下选项

• bodyfont（CSS 字体系列）：普通文本的字体。

• headerfont（CSS 字体系列）：标题的字体。

• pagewidth（CSS 长度）：页面内容的宽度，默认为 70em。

• documentwidth（CSS 长度）：文档的宽度（不包括侧边栏），默认为 50em。

• sidebarwidth（CSS 长度）：侧边栏的宽度，默认为 20em。

• rightsidebar（true 或 false）：将侧边栏放在右侧。默认为 True。

• bgcolor（CSS 颜色）：背景颜色。

• headerbg（CSS 的“background”值）：页眉区域的背景，默认为灰色渐变。

• footerbg（CSS 的“background”值）：页脚区域的背景，默认为浅灰色渐变。

• linkcolor（CSS 颜色）：正文的链接颜色。

• headercolor1、headercolor2（CSS 颜色）：<h1> 和 <h2> 标题的颜色。

• headerlinkcolor（CSS 颜色）：标题中反向引用链接的颜色。

• textalign（CSS text-align 值）：正文的文本对齐方式，默认为 justify。

nature

一个绿色的主题。目前除了 nosidebar 和 sidebarwidth 之外没有其他选项。

pyramid

来自 Pyramid Web 框架项目的主题，由 Blaise Laflamme 设计。目前除了 nosidebar 和 sidebarwidth 之外没有其他选项。

haiku

受 Haiku OS 用户指南 启发的无侧边栏主题。支持以下选项

• full_logo（true 或 false，默认为 False）：如果为 true，则页眉将仅显示 html_logo。对于大型徽标，请使用此选项。如果为 false，则徽标（如果存在）将显示在右侧，并且文档标题将放在页眉中。

• textcolor、headingcolor、linkcolor、visitedlinkcolor、hoverlinkcolor（CSS 颜色）：各种正文元素的颜色。

traditional

一个类似于旧版 Python 文档的主题。目前除了 nosidebar 和 sidebarwidth 之外没有其他选项。

epub

epub 构建器的主题。此主题尝试节省视觉空间，这是电子书阅读器上的稀缺资源。支持以下选项

• relbar1（true 或 false，默认为 True）：如果为 true，则 relbar1 块将插入到 epub 输出中，否则将省略。

• footer（true 或 false，默认为 True）：如果为 true，则 footer 块将插入到 epub 输出中，否则将省略。

bizstyle

一个简单的蓝色主题。除了 nosidebar 和 sidebarwidth 之外，还支持以下选项

• rightsidebar（true 或 false）：将侧边栏放在右侧。默认为 False。

版本 1.3 中新增： ‘alabaster’、‘sphinx_rtd_theme’ 和 ‘bizstyle’ 主题。

版本 1.3 中更改： ‘default’ 主题已重命名为 ‘classic’。‘default’ 仍然可用，但它会发出一个通知，说明它是新 ‘alabaster’ 主题的别名。

第三方主题

有很多为 Sphinx 创建的第三方主题。其中一些供通用使用，而另一些则特定于某个项目。

sphinx-themes.org 是一个展示各种 Sphinx 主题的图库，每个主题下都渲染了演示文档。主题也可以在 PyPI（使用分类器 Framework :: Sphinx :: Theme）、GitHub 和 GitLab 上找到。

上一页

sphinx.ext.viewcode – 添加到突出显示源代码的链接

下一页

国际化