模板

什么是模板？

模板是一种通过将静态模板与可变数据相结合来生成HTML页面的方法。模板文件包含所需HTML输出的静态部分，并包含描述如何插入可变内容的特殊语法。例如，这可用于在每个页面的页脚中插入当前日期，或使用HTML脚手架将文档的主要内容包围起来，以实现布局和格式目的。这样做只需要了解HTML和模板语法。了解Python可能会有所帮助，但不是必需的。

模板使用一种继承机制，允许子模板文件（例如，在主题中）覆盖其“父级”的任意多（或少）。同样，内容作者可以使用自己的本地模板来覆盖主题模板的任意多（或少）。

其结果是，Sphinx核心无需更改即可提供基本的HTML生成，而不依赖于最终输出的结构和外观，同时为主题和内容作者提供了极大的灵活性。

Sphinx模板

Sphinx使用 Jinja 模板引擎来处理其HTML模板。Jinja是一个基于文本的引擎，受Django模板的启发，因此任何使用过Django的人都会对它很熟悉。对于那些需要熟悉它的人来说，它也有出色的文档。

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

不，您还有好几个其他选择：

Jinja/Sphinx模板

Sphinx中的默认模板语言是Jinja。它是Django/Smarty的灵感来源，易于理解。Jinja中最重要的概念是：dfn:template inheritance，这意味着您只能覆盖模板中的特定块，对其进行自定义，同时将更改保持在最小限度。

要自定义文档的输出，您可以覆盖所有模板（包括布局模板和子模板），方法是将与原始文件名同名的文件添加到Sphinx quickstart为您生成的结构的模板目录中。

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

一个模板包含 变量 ，在对模板求值时用值替换 标记 ，控制模板逻辑， 块 用于模板继承。

Sphinx的 basic 主题为基本模板提供了几个它将填充数据的块。它们位于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()}} 在扩展模板中呈现该块的原始内容，除非您不希望该内容显示出来。

使用内置模板

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

模块

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

doctype

输出格式的文档类型。默认情况下，这是xhtml1.0的过渡版本，因为这是最接近Sphinx和Docutils生成的内容的，所以最好不要更改它，除非您想切换到html5或不同但兼容的XHTML doctype。

linktags

此块向模板的head部分添加两个“1”标记。

extrahead

默认情况下，此块为空，可用于将额外内容添加到生成的HTML文件的“`”标记中。这是添加对JavaScript或额外CSS文件的引用的正确位置。

relbar1, relbar2

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

{% block relbar2 %}{% endblock %}
rootrellink, relbaritems

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

document

文档本身的内容。它包含块"body"，其中单个内容由子模板放置，如 page.html。

备注

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

<div role="main">
  {% block document %}{% endblock %}
</div>
边栏1, 边栏2

边栏的可能位置。sidebar1 出现在文档前面，默认情况下为空。在文档之后显示为 sidebar2 并包含默认的提要栏。如果要交换侧边栏位置，请重写此选项并调用 sidebar 助手：

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

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

边栏图标

侧边栏中的徽标位置。如果要在侧栏顶部放置一些内容，请重写此选项。

脚注

页脚div的块。如果希望在页脚或标记之前或之后有自定义页脚或标记，请重写此页脚或标记。

以下四个块 仅 用于未在 html_sidebars config值中分配自定义边栏列表的页面。为了支持单独的侧栏模板，不推荐使用它们，可以通过 html_sidebars 包含这些模板。

边栏

侧边栏中的目录。

自 1.0 版本弃用.

边栏

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

自 1.0 版本弃用.

“边栏源链接”

侧边栏中的“Show source”链接（通常仅在启用此链接的情况下显示 html_show_sourcelink）。

自 1.0 版本弃用.

边栏搜索

侧栏中的搜索框。如果要在边栏底部放置一些内容，请重写此选项。

自 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)

返回指向*file*的路径，该文件是相对于生成输出的根的文件名。使用它来引用静态文件。

hasdoc(document)

检查名称为*document*的文档是否存在。

返回呈现的边栏。

relbar()

返回呈现的关系栏。

warning(message)

发出警告消息。

全局变量

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

builder

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

The value of 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

The value of language.

last_updated

构建日期。

logo_url

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

在 4.0 版本加入.

master_doc
root_doc

master_doc or root_doc (别名)的值，用于 pathto()。

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

pagename

当前文件的“页面名称”，即如果文件是从reStructuredText源生成的文档名称，或相对于输出目录的等效分层名称 （[directory/]filename_without_extension）。

project

The value of project.

release

The value of release.

要放在relbar左侧"next"和"prev"旁边的链接列表。这通常包含指向通用索引和其他索引（如Python模块索引）的链接。如果您自己添加内容，它必须是元组 (pagename, link title, accesskey, link text)。

shorttitle

The value of 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

“1”标记中使用的当前文档的标题。

use_opensearch

The value of html_use_opensearch.

version

The value of version.

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

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

body

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

display_toc

如果toc包含多个条目，则为真的布尔值。

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。

最大深度

树的最大深度。将其设置为“-1”以允许无限深。默认为在toctree指令中选择的最大深度。

仅标题

如果为true，则只在树中放置顶级文档标题。默认情况下为False。

“包括”

如果为true，ToC树也将包含隐藏项。默认情况下为False。