模板

Sphinx 使用 Jinja 模板引擎来创建其 HTML 模板。Jinja 是一个基于文本的引擎，灵感来自 Django 模板，因此任何使用过 Django 的人都已经熟悉它。对于那些需要熟悉它的用户，它也提供了非常好的文档。

我是否需要使用 Sphinx 的模板来生成 HTML？

不需要。您还有其他几种选择

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() }} 来渲染块的原始内容 - 除非您不希望该内容显示。

使用内置模板

内置的基本主题提供所有内置 Sphinx 主题所基于的模板。它包含以下您可以覆盖或使用的元素：

块

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

doctype

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

linktags

此块在模板的头部部分添加几个 <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 %}

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

sidebarlogo

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

footer

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

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

sidebartoc

侧边栏内的目录。

版本 1.0 中已弃用。

sidebarrel

侧边栏内的关系链接（上一篇、下一篇文档）。

版本 1.0 中已弃用。

sidebarsourcelink

侧边栏内的“显示源代码”链接（通常仅在通过 html_show_sourcelink 启用时显示）。

版本 1.0 中已弃用。

sidebarsearch

侧边栏内的搜索框。如果您想在侧边栏底部放置一些内容，请覆盖此内容。

版本 1.0 中已弃用。

配置变量

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

reldelim1

相关栏左侧项目的分隔符。默认值为 ' &raquo;'。相关栏中的每个项目都以该变量的值结尾。

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的文档。

返回渲染后的侧边栏。

relbar()

返回渲染后的关系栏。

warning(message)

发出警告消息。

全局变量

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

builder

生成器的名称（例如 html 或 htmlhelp）。

的值 copyright.

docstitle

文档标题（的值 html_title），除非使用“单个文件”生成器，此时它被设置为 None。

embedded

如果生成的 HTML 旨在嵌入到一些处理导航的查看应用程序（而不是 Web 浏览器）中，例如 HTML 帮助或 Qt 帮助格式，则为 True。在这种情况下，将不包含侧边栏。

favicon_url

从当前文档到 HTML 收藏夹图像的相对路径，或收藏夹图像的 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 相同。

在版本 4.0 中更改: 更名为 root_doc。

root_doc

的值 root_doc，用于与 pathto() 一起使用。

在版本 4.0 中更改: 从 master_doc 更名。

pagename

当前文件的“页面名称”，即如果文件从 reStructuredText 源生成，则为文档名称，或者相对于输出目录的等效层次结构名称 ([directory/]filename_without_extension)。

project

的值 project.

release

的值 release.

要在 relbar 的左侧放置的链接列表，位于“下一个”和“上一个”旁边。这通常包含指向一般索引和其他索引的链接，例如 Python 模块索引。如果您自己添加了一些内容，它必须是一个元组 (pagename, link title, accesskey, link text)。

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 中提供的 value。

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

body

包含页面内容的字符串，以 HTML 格式，由 HTML 构建器生成，在应用主题之前。

display_toc

一个布尔值，如果 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。