模板

什么是模板？

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

模板使用继承机制，允许子模板文件（例如，在主题中）根据需要覆盖其“父”模板的部分（或全部）。同样，内容作者可以使用他们自己的本地模板根据需要覆盖主题模板的部分（或全部）。

结果是 Sphinx 核心，无需更改，提供了基本的 HTML 生成，独立于最终输出的结构和外观，同时为主题和内容作者提供了很大的灵活性。

Sphinx 模板

Sphinx 使用 Jinja 模板引擎来处理其 HTML 模板。Jinja 是一个基于文本的引擎，灵感来自 Django 模板，因此任何使用过 Django 的人都会熟悉它。它还为那些需要熟悉它的人提供了出色的文档。

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

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

Jinja/Sphinx 模板入门

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

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

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

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

相关栏左侧项目的分隔符。默认为 ' &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)

以 URL 形式返回 Sphinx 文档的路径。使用它来引用已构建的文档。

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

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

4.0 版新增： root_doc 模板变量。

pagename

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

project

project 的值。

release

release 的值。

要放在 relbar 左侧，“next”和“prev”旁边的链接列表。这通常包含指向通用索引和其他索引（如 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 中给出的值。

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

body

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

display_toc

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

meta

文档元数据（字典），请参见 文件范围元数据。

metatags

一个字符串，包含页面的 HTML 元 标签。

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。