模板

什么是模板？

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

模板使用继承机制，允许子模板文件（例如主题中的）根据需要重写尽可能多（或尽可能少）的“父级”。同样，内容作者可以使用他们自己的本地模板来根据需要重写尽可能多（或尽可能少）的主题模板。

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

Sphinx模板

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

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

不。您还有几个其他选择：

金雅/狮身克斯模板底漆

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

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

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

模板包含 variables ，当评估模板时，这些值将被值替换， tags ，控制模板的逻辑， blocks 用于模板继承。

人面像的 basic 主题为基本模板提供了几个块，它将用数据填充。 这些位于 themes/basic Sphinx安装目录的收件箱，并由所有内置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 theme提供了所有内置Sphinx主题所基于的模板。它具有以下元素，您可以覆盖或用途：

块

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

doctype

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

linktags

这个块添加了几个 <link> 标记到模板的头部部分。

extrahead

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

relbar1 , relbar2

此块包含 relation bar 、相关链接列表（左侧是父文档，右侧是索引、模块等的链接）。 relbar1 出现在文件之前， relbar2 文件之后。 默认情况下，这两个块都是填充的;要想只在文档之前显示relbar， relbar2 像这样：：

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

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

document

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

备注

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

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

侧边栏的可能位置。 sidebar1 出现在文档之前并且默认为空， sidebar2 并包含默认的侧边栏。 如果要交换侧边栏位置，请重写此语句并调用 sidebar 帮手：：

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

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

sidebarlogo

侧边栏内的徽标位置。 如果您想将某些内容放置在侧边栏顶部，请选中此选项。

footer

页脚分区的块。 如果您想要在其之前或之后使用自定义页脚或标记，请重写此。

以下四个区块是 only 中未分配自定义侧边栏列表的页面 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)

将路径返回到 file 这是相对于生成的输出根的文件名。 使用此来引用静态文件。

hasdoc(document)

检查是否有一个文件的名称 document 存在.

返回渲染的侧边栏。

relbar()

返回渲染的关系栏。

warning(message)

发出警告消息。

全局变量

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

builder

建筑师的名字（例如： html 或 htmlhelp ).

的价值 copyright .

docstitle

文档的标题（价值 html_title ），除非使用“单文件”生成器时，设置为 None .

embedded

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

favicon_url

当前文档到HTML favicon图像的相对路径，或到favicon的URL，或 '' .

Added in version 4.0.

file_suffix

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

has_source

如果复制reStructuredtext文档源，则为真（如果 html_copy_source 是 True ).

language

的价值 language .

last_updated

构建日期。

logo_url

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

Added in version 4.0.

master_doc
root_doc

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

Added in version 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

时为True html_show_sourcelink 是 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作为最后一个元素。

Added in version 4.2.

docutils_version_info

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

Added in version 5.0.2.

styles

主题或给出的主要样式表名称列表 html_style .

Added in version 5.1.

title

当前文档的标题，如中所用 <title> 标签

use_opensearch

的价值 html_use_opensearch .

version

的价值 version .

除了这些价值观之外，还有所有 theme options 可用（开头为 theme_ ），以及用户在中给出的值 html_context .

在从源文件创建的文档中（与模块索引等自动生成的文件或已经采用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 item.

prev

像 next ，但在前一页。

sourcename

当前文档复制的源文件的名称。 只有当 html_copy_source 值 True .这对于创建自动生成的文件具有空值。

toc

当前页面的本地内容表，呈现为HTML项目符号列表。

toctree

一个可调用的对象，产生包含当前页面的全局SOC树，呈现为HTML项目符号列表。 可选关键字参数：

collapse

如果为真，则所有不是当前页面祖先的目录项都会折叠。 True 在默认情况下

maxdepth

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

titles_only

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

includehidden

如果为真，ToC树也将包含隐藏条目。 False 在默认情况下