模板¶

Sphinx 使用 Jinja 模板引擎作为其 HTML 模板。Jinja 是一个基于文本的引擎，灵感来自 Django 模板，因此任何使用过 Django 的人都已经熟悉它。对于那些需要熟悉它的人，它也拥有优秀的文档。

我需要使用 Sphinx 的模板来生成 HTML 吗？¶

不需要。您有其他几个选项

您可以编写一个 TemplateBridge 子类，它调用您选择的模板引擎，并相应地设置 template_bridge 配置值。
您可以编写自定义构建器，该构建器派生自 StandaloneHTMLBuilder 并调用您选择的模板引擎。
您可以使用 PickleHTMLBuilder，它生成包含页面内容的 pickle 文件，并使用自定义工具对它们进行后处理，或者在您的 Web 应用程序中使用它们。

Jinja/Sphinx 模板入门¶

Sphinx 中的默认模板语言是 Jinja。它受到 Django/Smarty 的启发，并且易于理解。Jinja 中最重要的概念是模板继承，这意味着您可以仅覆盖模板中的特定块，在自定义它的同时，也将更改保持在最低限度。

要自定义文档的输出，您可以通过将与原始文件名相同的文件名添加到 Sphinx 快速入门为您生成的结构的模板目录中，来覆盖所有模板（包括布局模板和子模板）。

Sphinx 将首先在 templates_path 的文件夹中查找模板，如果在那里找不到它正在查找的模板，它将回退到所选主题的模板。

一个模板包含变量，这些变量在模板求值时被值替换，标签，它们控制模板的逻辑，以及块，它们用于模板继承。

Sphinx 的基本主题提供了带有几个块的基本模板，它将用数据填充这些块。这些块位于 Sphinx 安装目录的 themes/basic 子目录中，并被所有内置 Sphinx 主题使用。 templates_path 中具有相同名称的模板会覆盖所选主题提供的模板。

例如，要向包含相关链接的模板区域添加新链接，您只需添加一个名为 layout.html 的新模板，其内容如下

{% extends "!layout.html" %}
{% block rootrellink %}
    <li><a href="https://project.invalid/">Project Homepage</a> &raquo;</li>
    {{ super() }}
{% endblock %}

通过在被覆盖模板的名称前加上感叹号，Sphinx 将从底层 HTML 主题加载布局模板。

重要

如果您覆盖了一个块，请在某处调用 {{ super() }} 以在扩展模板中渲染该块的原始内容 – 除非您不希望该内容显示出来。

使用内置模板¶

内置的 basic 主题提供了所有内置 Sphinx 主题都基于的模板。它具有以下您可以覆盖或使用的元素

块¶

以下块存在于 layout.html 模板中

doctype

输出格式的文档类型。默认情况下，这是 XHTML 1.0 Transitional，因为它最接近 Sphinx 和 Docutils 生成的内容，除非您想切换到 HTML 5 或不同的但兼容的 XHTML 文档类型，否则最好不要更改它。

linktags

此块向模板的 head 部分添加几个 <link> 标签。

extrahead

此块默认情况下为空，可用于向生成的 HTML 文件的 <head> 标签添加额外内容。这是添加对 JavaScript 或额外的 CSS 文件的引用的正确位置。

relbar1, relbar2

此块包含关系栏，即相关链接的列表（左侧的父文档，以及右侧的索引、模块等链接）。relbar1 出现在文档之前，relbar2 出现在文档之后。默认情况下，两个块都已填充；要仅在文档之前显示关系栏，您可以像这样覆盖 relbar2

{% block relbar2 %}{% endblock %}

rootrellink, relbaritems

在关系栏内部，有三个部分：rootrellink，来自文档的链接和自定义 relbaritems。rootrellink 是一个块，默认情况下包含指向根文档的列表项，relbaritems 是一个空块。如果您覆盖它们以向栏中添加额外的链接，请确保它们是列表项，并以 reldelim1 结尾。

document

文档本身的内容。它包含 “body” 块，子模板（如 page.html）将各个内容放入其中。

注意

为了使内置的 JavaScript 搜索在结果页面上显示页面预览，文档或正文内容应包装在包含 role="main" 属性的 HTML 元素中。例如

<div role="main">
  {% block document %}{% endblock %}
</div>

sidebar1, sidebar2

侧边栏的可能位置。sidebar1 出现在文档之前，默认情况下为空，sidebar2 出现在文档之后，包含默认侧边栏。如果您想交换侧边栏位置，请覆盖此项并调用 sidebar 助手

{% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %}

（例如，sphinxdoc.css 样式表需要侧边栏的 sidebar2 位置。）

sidebarlogo

侧边栏内的徽标位置。如果您想在侧边栏顶部放置一些内容，请覆盖此项。

footer

页脚 div 的块。如果您想要自定义页脚或在其之前或之后的标记，请覆盖此项。

以下四个块仅用于在 html_sidebars 配置值中未分配自定义侧边栏列表的页面。不建议使用它们，而建议使用单独的侧边栏模板，这些模板可以通过 html_sidebars 包含。

sidebartoc: 侧边栏内的目录。

版本 1.0 中已弃用。
sidebarrel: 侧边栏内的关系链接（上一个，下一个文档）。

版本 1.0 中已弃用。
sidebarsourcelink: 侧边栏内的 “显示源代码” 链接（通常仅在通过 html_show_sourcelink 启用时显示）。

版本 1.0 中已弃用。
sidebarsearch: 侧边栏内的搜索框。如果您想在侧边栏底部放置一些内容，请覆盖此项。

版本 1.0 中已弃用。

配置变量¶

在模板内部，您可以使用 {% set %} 标签设置布局模板使用的一些变量

reldelim1¶: 相关栏左侧项目的分隔符。默认为 ' »'。相关栏中的每个项目都以该变量的值结尾。

reldelim2¶: 相关栏右侧项目的分隔符。默认为 ' |'。相关栏中除最后一个项目外的每个项目都以该变量的值结尾。

覆盖的工作方式如下

{% extends "!layout.html" %}
{% set reldelim1 = ' &gt;' %}

script_files¶

在此处添加其他脚本文件，如下所示

{% set script_files = script_files + ["_static/myscript.js"] %}

版本 1.8.0 中已弃用: 请改用 .Sphinx.add_js_file()。

辅助函数¶

Sphinx 在模板中提供各种 Jinja 函数作为助手。您可以使用它们来生成链接或输出多次使用的元素。

pathto(document)¶: 返回 Sphinx 文档的路径作为 URL。使用它来引用构建的文档。

pathto(file, 1): 返回文件的路径，该文件是相对于生成的输出根目录的文件名。使用它来引用静态文件。

hasdoc(document)¶: 检查名称为document 的文档是否存在。

sidebar()¶: 返回渲染的侧边栏。

relbar()¶: 返回渲染的关系栏。

warning(message)¶: 发出警告消息。

全局变量¶

这些全局变量在每个模板中都可用，并且可以安全使用。还有更多，但其中大多数是实现细节，将来可能会更改。

builder¶: 构建器的名称（例如 html 或 htmlhelp）。

copyright¶: copyright 的值。

docstitle¶: 文档的标题（html_title 的值），但使用 “single-file” 构建器时除外，此时它设置为 None。

embedded¶: 如果构建的 HTML 旨在嵌入到某些处理导航的查看应用程序中，而不是 Web 浏览器中，例如 HTML 帮助或 Qt 帮助格式，则为 True。在这种情况下，不包括侧边栏。

favicon_url¶: 从当前文档到 HTML favicon 图像的相对路径，或 favicon 的 URL，或 ''。

在 4.0 版本中添加。

file_suffix¶: 构建器的 out_suffix 属性的值，即输出文件将获得的扩展名。对于标准 HTML 构建器，这通常是 .html。

has_source¶: 如果复制了 reStructuredText 文档源（如果 html_copy_source 为 True），则为 True。

language¶: language 的值。

last_updated¶: 构建日期。

logo_url¶: 从当前文档到 HTML 徽标图像的相对路径，或徽标的 URL，或 ''。

在 4.0 版本中添加。

master_doc¶
root_doc¶: master_doc 或 root_doc （别名）的值，用于 pathto()。

在 4.0 版本中添加: root_doc 模板变量。

pagename¶: 当前文件的 “页面名称”，即如果文件是从 reStructuredText 源生成的文档名称，或相对于输出目录的等效分层名称 ([目录/]不带扩展名的文件名)。

project¶: project 的值。

release¶: release 的值。

rellinks¶: 要放置在关系栏左侧，“下一个” 和 “上一个” 旁边的链接列表。这通常包含指向常规索引和其他索引的链接，例如 Python 模块索引。如果您自己添加内容，则必须是一个元组 (pagename, 链接标题, 快捷键, 链接文本)。

shorttitle¶: html_short_title 的值。

show_source¶: 如果 html_show_sourcelink 为 True，则为 True。

sphinx_version¶: 用于构建的 Sphinx 版本，表示为字符串，例如 “3.5.1”。

sphinx_version_tuple¶: 用于构建的 Sphinx 版本，表示为包含五个元素的元组。对于 Sphinx 版本 3.5.1 beta 3，这将是 (3, 5, 1, 'beta', 3)。第四个元素可以是以下之一：alpha、beta、rc、final。final 的最后一个元素始终为 0。

在 4.2 版本中添加。

docutils_version_info¶: 用于构建的 Docutils 版本，表示为包含五个元素的元组。对于 Docutils 版本 0.16.1 beta 2，这将是 (0, 16, 1, 'beta', 2)。第四个元素可以是以下之一：alpha、beta、candidate、final。final 的最后一个元素始终为 0。

在 5.0.2 版本中添加。

styles¶: 主要样式表的名称列表，由主题或 html_style 给出。

在 5.1 版本中添加。

title¶: 当前文档的标题，在 <title> 标签中使用。

use_opensearch¶: html_use_opensearch 的值。

version¶: version 的值。

除了这些值之外，还有所有可用的主题选项（以 theme_ 为前缀），以及用户在 html_context 中给出的值。

在从源文件创建的文档中（与自动生成的文件（如模块索引或已经是 HTML 格式的文档）相反），这些变量也可用

body¶: 一个字符串，包含 HTML 构建器生成的 HTML 格式的页面内容，在应用主题之前。

display_toc¶: 一个布尔值，如果目录包含多个条目，则为 True。

meta¶: 文档元数据（字典），请参阅文件级元数据。

metatags¶: 一个字符串，包含页面的 HTML meta 标签。

next¶

导航的下一个文档。此变量为 false 或具有两个属性 link 和 title。标题包含 HTML 标记。例如，要生成指向下一页的链接，您可以使用此代码片段

{% if next %}
<a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %}

page_source_suffix¶: 渲染的文件的后缀。由于我们支持 source_suffix 列表，这将允许您正确链接到原始源文件。

parents¶: 用于导航的父文档列表，结构类似于 next 项。

prev¶: 类似于 next，但用于上一页。

sourcename¶: 当前文档的复制源文件的名称。仅当 html_copy_source 值为 True 时，此值才为非空。在创建自动生成的文件时，此值为空。

toc¶: 当前页面的本地目录，渲染为 HTML 项目符号列表。

toctree¶

一个可调用对象，生成包含当前页面的全局 TOC 树，渲染为 HTML 项目符号列表。可选关键字参数

collapse: 如果为 true，则折叠所有不是当前页面祖先的 TOC 条目。True 默认值。
maxdepth: 树的最大深度。将其设置为 -1 以允许无限深度。默认为 toctree 指令中选择的最大深度。
titles_only: 如果为 true，则仅将顶级文档标题放在树中。False 默认值。
includehidden: 如果为 true，则 ToC 树也将包含隐藏条目。False 默认值。