HTML 主题开发

在 0.6 版本加入.

备注

本文档提供有关创建您自己的主题的信息。如果您只想使用预先存在的HTML主题，请参阅 HTML主题。

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

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

备注

更多有助于主题开发的信息请参阅 Sphinx API接口。

创建主题

主题采用目录或zipfile（其名称为主题名称）的形式，包含以下内容：

• theme.toml 文件（首选）或 theme.conf 文件。

• HTML模板，如果需要。

• static/ 目录，其中包含将在生成时复制到输出静态目录的任何静态文件。这些可以是图像、样式、脚本文件。

主题配置（theme.toml）

theme.toml 文件为 TOML 文档，其包含两个表格： [theme] 和 [options]。

[theme] 表格定义主题设置：

• inherit （字符串）：用于继承设置、选项、模板和静态文件的基本主题名称。将使用主题“祖先”的所有静态文件。主题将使用继承主题中定义的所有选项。最后，继承的主题将用于查找缺少的模板（例如，如果 "basic" 用作基本主题，则大多数模板将已被定义）。

  如设置为 "none"，则主题不会继承任何其它主题。继承为递归式，形成继承主题链条（如 default -> classic -> basic -> none）。

• stylesheets （字符串列表）：将包含在生成的 HTML 头中的 CSS 文件名列表。设置 html_style 配置值将覆盖此设置。

  包括多个样式表的其他机制包括 CSS 中的 @import 或使用带有适当 <link rel="stylesheet"> 标签的自定义 HTML 模板。

• sidebars （字符串列表）：侧边栏模板列表。可由用户通过 html_sidebars 配置值覆盖之。

• pygments_style （表格）：此为 TOML 表格，定义 Pygments 样式名称以用于语法加亮。表格有两个识别键： default 和 dark。当 CSS 媒体查询 (prefers-color-scheme: dark) 为 True 时，使用在 dark 键内定义的样式。

  [theme.pygments_style.default] 可由用户通过 pygments_style 配置值覆盖之。

[options] 表格定义主题的选项。其结构为每个键值对对应一个变量名和相应的默认值。用户可以在 html_theme_options 中覆盖这些选项，并且可以从所有模板中以 theme_<name> 的形式访问这些选项。

在 7.3 版本加入: theme.toml 支持。

示例 theme.toml 文件：

[theme]
inherit = "basic"
stylesheets = [
    "main-CSS-stylesheet.css",
]
sidebars = [
    "localtoc.html",
    "relations.html",
    "sourcelink.html",
    "searchbox.html",
]
# Style names from https://pygments.org/styles/
pygments_style = { default = "style_name", dark = "dark_style" }

[options]
variable = "default value"

主题配置（theme.conf）

theme.conf 文件为 INI 格式 [1] (可由标准的 Python configparser 模块读取），具有以下结构：

[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename
sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html

[options]
variable = default value

• inherit 设置提供“基本主题”或“无”的名称。基本主题将用于查找缺少的模板（如果大多数主题使用“basic”作为基本主题，则大多数主题不必提供大多数模板），它的选项将被继承，并且它的所有静态文件也将被使用。如果您还想继承样式表，可以通过CSS' @import 将其包含在自己的样式表中。

• stylesheet 设置提供以逗号分隔的 CSS 文件名列表，这些文件将在 HTML 头中引用。您还可以使用 CSS' @import 技术从其他文件中包含，或使用自定义 HTML 模板根据需要添加 <link rel="stylesheet"> 标签。设置 html_style 配置值将覆盖此设置。

• pygments_style 设置提供用于突出显示的pygments样式的名称。用户可以在 pygments_style 配置值中重写此设置。

• pygments_dark_style 设置给予 Pygments 样式名称以在 CSS 媒体查询 (prefers-color-scheme: dark) 为 True 时用作语法加亮。使用 add_css_file() 将其注射到网页。

• sidebars 设置提供了用逗号分隔的侧边栏模板列表，用于构造提要栏。用户可以在 html_sidebars 配置值中覆盖此值。

• options 部分包含变量名和默认值对。用户可以在以下位置重写这些选项 html_theme_options 并且可以从所有模板中以 theme_<name> 的形式访问这些选项。

在 1.7 版本加入: 边栏设置

在 5.1 版本发生变更: 样式表设置接受多个 CSS 文件名

转换 theme.conf 为 theme.toml

可通过随 Sphinx 分布的助手程序转换 INI 样式的主题配置文件（theme.conf）为 TOML。此为一次性使用，可能在 Sphinx 的以后版本中移除，不另行通知。

$ python -m sphinx.theming conf_to_toml [THEME DIRECTORY PATH]

所需参数为包含 theme.conf 文件的目录路径。助手程序会写 theme.toml 文件到同一目录，不会修改原始 theme.conf 文件。

在 7.3 版本加入.

将主题作为Python包分发

您可用 Python 包作为分布您主题的方式。这可使用户能够更轻松地设置主题。

要分布您的主题为 Python 包，请在您的 pyproject.toml 文件内定义名为 sphinx.html_themes 的入口点并写 setup() 函数以使用 add_html_theme() API 注册您的主题：

# pyproject.toml

[project.entry-points."sphinx.html_themes"]
name_of_theme = "your_theme_package"

# your_theme_package.py
from pathlib import Path

def setup(app):
    app.add_html_theme('name_of_theme', Path(__file__).resolve().parent)

如果您的主题包包含两个或多个主题，请调用“add_html_theme（）`”两次或更多。

在 1.2 版本加入: “sphinx_themes”入口点功能。

自 1.6 版本弃用: sphinx_themes entry_points 已被弃用。

在 1.6 版本加入: sphinx.html_themes 进入点特征。

使用 CSS 进行样式设计

stylesheets 设置可用于添加自定义 CSS 文件到主题。

小心

HTML 元素及其类的结构目前不是定义良好的公共 API。请通过检查构建的 HTML 页面来推断它们。虽然我们不能保证完全稳定，但它们往往相当稳定。

按类别设置搜索结果条目的样式

在 8.0 版本加入.

备注

以下命名的 CSS 类由 Sphinx 的独立搜索代码生成。如果您使用第三方搜索提供程序（如 ReadTheDocs）来提供搜索结果，则可用的主题选项可能会有所不同。

搜索结果项具有指示搜索词所在上下文的类。您可以使用 CSS 选择器：

• ul.search li.kind-index：用于索引中的结果，例如术语表

• ul.search li.kind-object：用于源代码中的结果，如 Python 函数定义

• ul.search li.kind-title：用于在章节标题中找到的结果

• ul.search li.kind-text：用于在文档文本中的任何其他位置找到的结果

作为其他主题继承的基础，basic 主题故意是最小化的，并且不使用这些定义 CSS 规则。鼓励派生主题根据需要使用这些选择器。例如，以下样式表向搜索结果列表添加了上下文图标：

ul.search {
    padding-left: 30px;
}
ul.search li {
    padding: 5px 0 5px 10px;
    list-style-type: "\25A1";  /* Unicode: White Square */
}
ul.search li.kind-index {
    list-style-type: "\1F4D1";  /* Unicode: Bookmark Tabs */
}
ul.search li.kind-object {
    list-style-type: "\1F4E6";  /* Unicode: Package */
}
ul.search li.kind-title {
    list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
}
ul.search li.kind-text {
    list-style-type: "\1F4C4";  /* Unicode: Page Facing Up */
}

模板

如果您想编写自己的模板， guide to templating 很有帮助。重要的是要记住Sphinx搜索模板的顺序：

• 首先，在用户的“templates_path”目录中。

• 然后，在选定的主题中。

• 然后，在它的基主题中，它的基主题，等等。

在具有相同名称的基本主题中扩展模板时，请使用主题名称作为显式目录： {% extends "basic/layout.html" %}。从用户 templates_path 模板，您仍然可以使用“感叹号”语法，如 Jinja/Sphinx模板 模板文档中所述。

静态模板

因为主题选项是为了让用户更容易地配置一个主题，而不必编写自定义样式表，所以必须能够模板化静态文件和HTML文件。因此，Sphinx支持所谓的“静态模板”，如下所示：

如果主题的 static/ 目录中的文件名（或用户的静态路径）以 .jinja 或 _t 结尾，则将由模板引擎处理。后缀将从最终文件名中删除。

例如，具有 static/theme_styles.css.jinja 文件的主题可以使用模板将选项放入样式表中。当使用该主题构建文档项目时，输出目录将包含一个 _static/theme_styles.css 文件，其中所有模板标签均已被处理。

在 7.4 版本发生变更:

静态模板的首选后缀现在是 .jinja，符合 Jinja 项目的 recommended file extension。

静态模板的 _t 文件后缀现在被视为“传统”，并且支持最终可能会被移除。

如果检测到具有 _t 后缀或 .jinja 后缀的静态模板，则将由模板引擎处理，并从最终文件名中删除后缀。

在 HTML 模板中使用自定义页面元数据

放置在页面标题*之前*的 field lists 中的任何键/值对将在构建页面时通过 meta 属性提供给 Jinja 模板。例如，如果页面在其第一个标题之前具有以下文本：

:mykey: My value

My first title
--------------

它可以在 Jinja 模板中这样访问：

{%- if meta is mapping %}
    {{ meta.get("mykey") }}
{%- endif %}

请注意检查 meta 是否为字典（Jinja 术语中的“映射”），以确保以这种方式使用它是有效的。

定义自定义模板函数

有时在 Python 中定义自己的函数然后在模板中使用它是很有用的。例如，如果您想插入一个模板值，其逻辑取决于项目中用户的配置，或者如果您想包含非平凡的检查并为模板中的错误配置提供友好的错误消息。

要定义您自己的模板函数，您需要在模块内定义两个函数：

• 页面上下文事件处理程序**（或**注册）函数。这是通过事件回调连接到 Sphinx 应用程序的。

• 模板函数，您将在 Jinja 模板中使用它。

首先，定义注册函数，该函数接受 html-page-context 的参数。

在注册函数内，定义您想在 Jinja 中使用的模板函数。模板函数应返回字符串或 Python 对象（列表、字典），其中包含 Jinja 在模板处理过程中使用的字符串

备注

模板函数将可以访问传递给注册函数的所有变量。

在注册函数的末尾，将模板函数添加到 Sphinx 应用程序的上下文中，方法是 context['template_func'] = template_func。

最后，在扩展的 setup() 函数中，将注册函数添加为 html-page-context 的回调。

# The registration function
 def setup_my_func(app, pagename, templatename, context, doctree):
     # The template function
     def my_func(mystring):
         return "Your string is %s" % mystring
     # Add it to the page's context
     context['my_func'] = my_func

 # Your extension's setup function
 def setup(app):
     app.connect("html-page-context", setup_my_func)

现在，您将可以在 jinja 中访问此函数，如下所示：

<div>
{{ my_func("some string") }}
</div>

将您自己的静态文件添加到构建资产中

默认情况下，Sphinx 会复制模板目录的 static/ 目录中的静态文件。但是，如果您的包需要出于某些原因将静态文件放置在 static/ 目录之外，则需要通过事件钩子在构建时手动将它们复制到 HTML 输出的 _static/ 目录中。以下是实现此目的的代码示例：

import shutil

def copy_custom_files(app, exc):
    if app.builder.format == 'html' and not exc:
        static_dir = app.outdir / '_static'
        shutil.copyfile('path/to/myextension/_static/myjsfile.js', static_dir)

def setup(app):
    app.connect('build-finished', copy_custom_files)

根据用户配置注入JavaScript

如果您的扩展使用 JavaScript，则允许用户使用其 Sphinx 配置来控制其行为可能很有用。但是，如果您的 JavaScript 以静态库的形式出现（不会使用 Jinja 构建），则可能很难做到这一点。

有两种方法可以根据用户配置将变量注入 JavaScript 空间。

首先，您可以在扩展中包含的任何静态文件的末尾添加 _t。这将导致 Sphinx 使用模板引擎处理这些文件，允许您嵌入变量和控制行为。

例如，以下 JavaScript 结构：

mymodule/
├── _static
│   └── myjsfile.js_t
└── mymodule.py

将导致在 HTML 的构建输出中放置以下静态文件：

_build/
└── html
    └── _static
        └── myjsfile.js

参见 静态模板 以获取更多信息。

其次，您可以使用 Sphinx.add_js_file() 方法，而不指向文件。通常，此方法用于将新的 JavaScript 文件插入到您的站点中。但是，如果您*不*传递文件路径，而是将字符串传递给“body”参数，则该文本将作为 JavaScript 插入到您站点的头中。这允许您从 Python 将变量插入到项目的 JavaScript 中。

例如，以下代码将读取用户配置的值，然后将该值作为 JavaScript 变量插入，您的扩展的 JavaScript 代码可以使用该变量：

# This function reads in a variable and inserts it into JavaScript
def add_js_variable(app):
    # This is a configuration that you've specified for users in `conf.py`
    js_variable = app.config['my_javascript_variable']
    js_text = "var my_variable = '%s';" % js_variable
    app.add_js_file(None, body=js_text)
# We connect this function to the step after the builder is initialized
def setup(app):
    # Tell Sphinx about this configuration variable
    app.add_config_value('my_javascript_variable', 0, 'html')
    # Run the function after the builder is initialized
    app.connect('builder-inited', add_js_variable)

因此，在您的主题中，您可以使用依赖于该变量存在的代码。用户可以通过在其 conf.py 文件中定义该变量来控制变量的值。

[1]

它不是一个可执行的Python文件，而不是：file:conf.py，因为如果共享主题，则会带来不必要的安全风险。

Previous

配置构建器

Next

模板