HTML主题化

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

Builders

待处理

当“构建者”文档被拆分时填充。

主题

Added in version 0.6.

备注

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

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

主题意味着项目不知道，所以它们可以用于不同的项目而不改变。

使用主题

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

html_theme = "classic"

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

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

如果主题不随sphinx一起提供，它可以是两种静态形式，也可以是一个python包。对于静态窗体，目录（包含 theme.conf 以及其他需要的文件），或者支持内容相同的zip文件。目录或zipfile必须放在sphinx可以找到它的地方；为此，有config值 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

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

html_theme = "dotted"

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

建筑主题

主题概述
雪白石膏	经典
SphinxDOC	卷轴
阿盖奥	传统的
自然	俳句
金字塔	双柱式

Sphinx有多种主题可供选择。

请注意，在这些主题中，只有Alabaster和Scrolls主题是移动优化的，如果屏幕太窄，其他主题会求助于水平滚动。

这些主题包括：

basic

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

• 不带边框的 （对或错）：不包括侧边栏。默认为 False .

• 边宽 （int或str）：边栏的宽度（像素）。这可以是一个int，它被解释为像素或有效的css维度字符串，如“70em”或“50%”。默认为230像素。

• body_min_width （int或str）：文档正文的最小宽度。这可以是一个int，它被解释为像素或有效的css维度字符串，如“70em”或“50%”。如果不需要宽度限制，请使用0。默认值可能取决于主题（通常是450像素）。

• body_max_width （int或str）：文档正文的最大宽度。这可以是一个int，它被解释为像素或有效的css维度字符串，如“70em”或“50%”。如果不需要宽度限制，请使用“无”。默认值可能取决于主题（通常为800px）。

• navigation_with_keys (真或假)：允许使用以下键盘快捷键导航：

  • Left arrow ：上一页

  • Right arrow ：下一页

  默认为 False .

• enable_search_shortcuts (真或假)：允许跳转到搜索框 / 并允许使用以下命令删除搜索突出显示 Esc 。

  默认为 True 。

• globaltoc_collapse （正确或错误）：仅在 globaltoc.html （见 html_sidebars ）默认为 True .

  Added in version 3.1.

• globaltoc_includehidden （正确或错误）：甚至在 globaltoc.html （见 html_sidebars )包括在 :hidden: 旗 toctree 指令。默认为 False .

  Added in version 3.1.

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

  Added in version 3.2.

alabaster

Alabaster theme 是来自@kennethreitz的一个修改过的“kr”sphinx主题（特别是在他的请求项目中使用），它最初是基于@mituhiko用于烧瓶和相关项目的主题。参考其 installation page 有关如何配置的信息 html_sidebars 以供使用。

classic

这是经典的主题，看起来像 the Python 2 documentation . 它可以通过以下选项进行定制：

• 右导航 （正确或错误）：将侧边栏放在右侧。默认为 False .

• 粘滞边栏 （正确或错误）：将侧边栏设为“固定”，这样它就不会滚动出长正文内容的视图。这可能不适用于所有浏览器。默认为 False .

• 可折叠的侧栏 （对或错）：添加 实验的 一个JavaScript代码段，它通过侧边的按钮使侧边栏可折叠。默认为 False .

• 外部参考文献 （正确或错误）：显示不同于内部链接的外部链接。默认为 False .

还有各种颜色和字体选项，可以在不编写自定义样式表的情况下更改颜色方案：

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

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

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

• 边框颜色 （CSS颜色）：侧边栏折叠按钮的背景色（用于 可折叠的侧栏 是 True ）

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

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

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

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

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

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

• 字体颜色 （CSS颜色）：正文文本颜色。

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

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

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

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

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

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

• 钴色 （CSS颜色）：代码块的默认文本颜色，如果突出显示样式没有不同的设置。

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

• 头型字体 （css字体系列）：标题字体。

sphinxdoc

此文档最初使用的主题。它在右边有一个侧边栏。目前没有其他选择 不带边框的 和 边宽 .

备注

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

scrolls

一个更轻量级的主题，基于 the Jinja documentation 。有以下颜色选项可用：

• headerbordercolor

• subheadlinecolor

• linkcolor

• visitedlinkcolor

• admonitioncolor

agogo

安迪·阿尔布雷特创作的主题。支持以下选项：

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

• 头字型 （css字体系列）：标题字体。

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

• 文档宽度 （css length）：文档宽度（不带侧边栏），默认为50em。

• 边宽 （css length）：边栏的宽度，默认为20em。

• 右导航 （正确或错误）：将侧边栏放在右侧。默认为 True .

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

• 头标 （css value for“background”）：标题区域的背景，默认为灰色渐变。

• 福特伯格 （css value for“background”）：页脚区域的背景，默认为浅灰色渐变。

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

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

• 头色 （css color）：标题中的backreference链接的颜色。

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

nature

绿色主题。目前没有其他选择 不带边框的 和 边宽 .

pyramid

由BlaiseLaflamme设计的金字塔网络框架项目的主题。目前没有其他选择 不带边框的 和 边宽 .

haiku

没有侧边栏的主题灵感来自 Haiku OS user guide . 支持以下选项：

• full_logo （正确或错误，默认 False ）：如果为真，则标题将仅显示 html_logo . 大标志用这个。如果这是错误的，标志（如果存在）将显示为浮动右，文档标题将放在标题中。

• 字体颜色 ， 标题颜色 ， 链接颜色 ， 可见链接颜色 ， 霍夫林颜色 （CSS颜色）：各种身体元素的颜色。

traditional

类似于旧的Python文档的主题。目前没有其他选择 不带边框的 和 边宽 .

epub

EPUB生成器的主题。这个主题试图节省可视空间，这是电子书阅读器上的一个稀疏资源。支持以下选项：

• relbar1 (真或假，默认 True )：如果这是真的， relbar1 块插入到epub输出中，否则将被省略。

• footer (真或假，默认 True )：如果这是真的， footer 块插入到epub输出中，否则将被省略。

bizstyle

一个简单的蓝色主题。除此之外，还支持以下选项 不带边框的 和 边宽 ：

• 右导航 （正确或错误）：将侧边栏放在右侧。默认为 False .

Added in version 1.3: “alabaster”、“Sphinx”和“商业风格”主题。

在 1.3 版本发生变更: “默认”主题已重命名为“经典”。默认值“仍然可用，但是它会发出一个通知，说明它是新“alabaster”主题的别名。

第三方主题

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

sphinx-themes.org 是一个展示Sphinx的各种主题的图库，每个主题下都有演示文档。主题也可以在 PyPI (使用分类器 Framework :: Sphinx :: Theme ), GitHub 和 GitLab.