HTML 主题

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

生成器

待处理

在拆分“生成器”文档时填充。

主题

Added in version 0.6.

备注

本节提供有关使用预先存在的HTML主题的信息。 如果您想创建自己的主题，请参考 HTML theme development。

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

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

使用一个主题

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

html_theme = "classic"

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

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

If the theme does not come with Sphinx, it can be in two static forms or as a Python package. For the static forms, either a directory (containing theme.toml and other needed files), or a zip file with the same contents is supported. The directory or zipfile must be put where Sphinx can find it; for this there is the config value html_theme_path. This can be a list of directories, relative to the directory containing conf.py, that can contain theme directories or zip files. For example, if you have a theme in the file blue.zip, you can put it right in the directory containing conf.py and use this configuration:

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

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

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

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

html_theme = "dotted"

有关主题设计的更多信息（包括有关编写自己的主题的信息），请参考:doc:/development/theming。

内置主题

主题概览

|汉白玉|

汉白玉

|经典|

经典

|sphinx文档|

sphinx文档

|滚动|

滚动

|阿戈戈铃|

阿戈戈铃

|传统|

传统

|自然|

自然

haiku

haiku

|金字塔|

金字塔

|商务风|

商务风

sphinx 有多种主题可供选择

Note that from these themes only the Alabaster and Scrolls themes are mobile-optimated, the other themes resort to horizontal scrolling if the screen is too narrow.

这些主题是：

基础

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

  • **无侧边栏r**(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)。

  • navigation_with_keys (true or false): Allow navigating with the following keyboard shortcuts:

    • Left arrow: previous page

    • Right arrow: next page

    默认为“False”。

  • enable_search_shortcuts (true or false): Allow jumping to the search box with / and allow removal of search highlighting with Esc.

    Defaults to True.

  • globaltoc_collapse (true 或 false): 仅在“globaltoc.html”中扩展当前文档的小节（请参阅:confval:html_sidebars）。 默认为``True’’。

    Added in version 3.1.

  • globaltoc_includehidden (true 或 false)：甚至显示在globaltoc.html中的那些小节（请参见:confval:html_sidebars），这些小节已包含在:rst:dir:`toctree`指令的“:hidden:”标志中。 默认为“False”。

    Added in version 3.1.

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

    Added in version 3.2.

汉白玉

汉白玉主题`_是@kennethreitz修改后的“ Kr”Sphinx主题（尤其是在他的Requests项目中使用的主题），其本身最初是基于@mitsuhiko的Flask及其相关项目的主题。 有关如何配置:confval:`html_sidebars`的信息，请参见其`安装页面。

经典

这是经典主题，看起来像Python 2文档<https://docs.python.org/2/>`_。 可以通过以下选项进行自定义：

  • 右侧边栏 (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文档现在使用了`sphinx文档主题的调整版本<https://github.com/sphinx-doc/sphinx/tree/master/doc/_themes/sphinx13>`_。

滚动

基于Jinja文档 <https://jinja.palletsprojects.com/>`_ 的更轻量的主题。 提供以下颜色选项：

  • 标题边界颜色

  • **副标题行颜色*

  • 链接颜色

  • 访问链接颜色

  • 警示色

阿戈戈

由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用户指南<https://www.haiku-os.org/docs/userguide/zh-cn/contents.html>`_”启发了一个没有侧边栏的主题。 支持以下选项：

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

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

传统

一个类似于旧的Python文档的主题。 除*无边兰*和*边栏宽度*外，目前没有其他选项。

epub

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

  • relbar1 (true or false, default True): If this is true, the relbar1 block is inserted in the epub output, otherwise it is omitted.

  • footer (true or false, default True): If this is true, the footer block is inserted in the epub output, otherwise it is omitted.

商务风

一个简单的蓝色主题。 除*无边兰*和*边栏宽度*外，目前没有其他选项。

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

Added in version 1.3: ‘汉白玉’， ‘sphinx_rtd_theme’ 和 ‘商务风’ 主题.

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

第三方主题

There are many third-party themes created for Sphinx. Some of these are for general use, while others are specific to an individual project.

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