HTML主题

Sphinx提供了许多构建器，用于HTML格式，以及基于HTML的其它格式。

构建器

主题

在 0.6 版本加入.

备注

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

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

主题是指不受项目影响的，因此它们可以用于不同的项目而无需更改。

使用一个主题

使用 theme provided with Sphinx 很容易。由于不需要安装这些文件，因此您只需要设置 html_theme 配置值即可。 例如，要启用 经典 主题，请将以下内容添加到 conf.py

html_theme = "classic"

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

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

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

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

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

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

安装后，可以与基于目录或基于zipfile的主题相同的方式使用：

html_theme = "dotted"

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

内置主题

主题概览

alabaster

alabaster

经典

经典

sphinxdoc

sphinxdoc

滚动

scrolls

阿戈戈铃

agogo

传统

传统

自然

自然

haiku

haiku

金字塔

金字塔

商务风

商务风

sphinx 有多种主题可供选择

请注意，在这些主题中，只有汉白玉和滚动主题是针对移动设备优化的，如果屏幕过窄，其他主题将进行水平滚动。

这些主题是：

基础

这是一个基本上没有样式的布局，用作其他主题的基础，也可用作自定义主题的基础。HTML包含所有重要元素，如侧边栏和关系栏。有这些选项(由其他主题继承)：

  • 无侧边栏 (true or false)：不包括侧边栏。 默认为 False。

  • 侧边栏宽度 (int或str)：侧边栏的宽度(以像素为单位)。这可以是 int，它被解释为像素或有效的CSS维度字符串，例如 '70em' 或 ‘50％’。默认为230像素。

  • 正文最小宽度 (int或str)：文档正文的最小宽度。这可以是int，它被解释为像素或有效的CSS维度字符串，例如’70em’或’50％’。如果您不想要宽度限制，请使用0，默认值可能取决于主题(通常为450px)。

  • 正文最大宽度  (int或str)：文档正文的最大宽度。这可以是int，它被解释为像素或有效的CSS维度字符串，例如’70em’或’50％’。如果您不想要宽度限制，请使用 none。默认值可能取决于主题(通常为800px)。

  • 使用键导航 (true或false)：允许使用以下键盘快捷键进行导航：

    • 左箭头：上一页

    • 右箭头：下一页

    默认为 False。

  • 启用搜索快捷键 (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 theme 是 @kennethreitz修改后的“Kr” Sphinx主题（尤其是在他的Requests项目中使用的主题），其本身最初是基于 @mitsuhiko的Flask及其相关项目的主题。 有关如何配置 html_sidebars 的信息，请参见其 installation page。

经典

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

  • 右侧边栏 (true或false)：将侧边栏放在右侧。默认 False。

  • 固定侧边栏 (true 或 false)：使侧边栏“固定” , 以便它不会滚出视图以获取长身体内容。这可能不适用于所有浏览器。默认为“False”。

  • 可折叠边栏 (true或false)： 实验 JavaScript代码段，用侧边按钮折叠边栏。默认 False 。

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

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

  • 页脚线颜色 (CSS色)：页脚线的背景颜色。

  • 页脚文本颜色 (CSS 颜色)：页脚行的文本颜色。

  • 边栏背景色 (CSS色)：侧边栏的背景颜色。

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

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

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

  • 相关栏背景色 （CSS色）：相关栏的背景色。

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

  • 相关栏链接色 (CSS色)：相关栏的链接颜色。

  • 背景色 （CSS色）：主体背景颜色。

  • 文本色 （CSS色）：主体文本颜色。

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

  • 访问链接颜色 （CSS色）：所访问链接的主体颜色。

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

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

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

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

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

  • 正文字体 （CSS字体家族）：普通文本的字体。

  • 标题字体 （CSS字体家族）：标题字体。

sphinx文档

本文档最初使用的主题。它在右侧具有侧边栏。目前仅有 无边栏 和 侧边栏宽度 选项。

备注

Sphinx文档现在使用了 an adjusted version of the sphinxdoc theme 。

滚动

更轻量的、基于 the Jinja documentation 的主题。提供以下颜色选项：

  • 标题边界颜色

  • 副标题行颜色

  • 链接颜色

  • 访问链接颜色

  • 警示色

阿戈戈

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

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

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

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

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

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

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

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

  • 标题背景 （“背景”的CSS值）：标题区域的背景，默认为灰色渐变。

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

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

  • 标题颜色1 ，标题颜色2 （CSS色）：标题<h1>和<h2>的颜色。

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

  • 文本对齐 （CSS 文本对齐 值）：正文的文本对齐方式，默认为“两端对齐”。

自然

绿色主题。目前仅有 无边栏 和 边栏宽度 选项。

金字塔

金字塔Web框架项目的主题，由Blaise Laflamme设计。目前仅有 无边栏 和 边栏宽度 选项。

haiku

受 Haiku OS user guide 启发的一个没有侧边栏的主题。 支持以下选项：

  • 完整_标识 （true或false，默认为False）：如果为true，则标头将仅显示 html_logo。 将其用于大徽标。 如果为false，标识（如果存在）将以向右浮动的形式显示，并且文档标题将放在标题中。

  • 文本色, 标题色, 链接色, 访问链接色, hoverlinkcolor (CSS色)：各种正文元素的颜色。

传统

一个类似于旧的Python文档的主题。目前仅有 无边栏 和 边栏宽度 选项。

epub

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

  • relbar1 (true or false, default True)：如果为true，则 relbar1 块将插入epub输出，否则将省略。

  • 页脚 (true或false，默认为“True”): 如果为true，则 footer 块将插入epub输出，否则将省略。

商务风

一个简单的蓝色主题。 目前仅有 无边栏 和 边栏宽度 选项。

  • 右侧边栏 (true或false)：将侧边栏放在右侧。默认 False。

在 1.3 版本加入: '汉白玉'， 'sphinx_rtd_theme' 和 '商务风' 主题.

在 1.3 版本发生变更: '默认'主题已重命名为'经典'。'默认'仍然可用，但它会发出通知，告知它是新'汉白玉'主题的别名。

第三方主题

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

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