模板法¶
Sphinx使用 Jinja 模板引擎，用于其HTML模板。Jinsa是一个基于文本的引擎，灵感来自Django模板，所以任何使用过Django的人都已经熟悉它了。它还为那些需要熟悉它的人提供了极好的文档。
我需要使用Sphinx的模板来生成HTML吗？¶
不，您还有其他几种选择：
你可以写一个
TemplateBridge调用模板引擎的子类，并设置template_bridge相应的配置值。你可以 write a custom builder 源于
StandaloneHTMLBuilder并调用您选择的模板引擎。你可以使用
PickleHTMLBuilder它生成带有页面内容的pickle文件，并使用自定义工具对其进行后处理，或者在Web应用程序中使用它们。
Jinja/Sphinx模板基础¶
Sphinx中的默认模板语言是Jinja。这是Django/Smarty的启发和容易理解。Jinja最重要的概念是 template inheritance 这意味着您只能覆盖模板中的特定块，并对其进行自定义，同时将更改保持在最小值。
要自定义文档的输出，可以通过将与原始文件名相同的文件添加到为您生成的sphinx Quickstart结构的模板目录中来覆盖所有模板（包括布局模板和子模板）。
Sphinx将在以下文件夹中查找模板： templates_path 首先，如果它找不到它要查找的模板，那么它将返回到所选主题的模板。
模板包含 变量 ，在评估模板时将其替换为值， tags 控制模板的逻辑和 阻碍 用于模板继承。
Sphinx 基本的 主题为基础模板提供了几个将由数据填充的块。它们位于 themes/basic sphinx安装目录的子目录，由所有内置的sphinx主题使用。中具有相同名称的模板 templates_path 覆盖所选主题提供的模板。
例如，要向包含相关链接的模板区域添加新链接，您只需添加一个名为 layout.html 内容如下：
{% extends "!layout.html" %}
{% block rootrellink %}
<li><a href="https://project.invalid/">Project Homepage</a> »</li>
{{ super() }}
{% endblock %}
通过在重写模板的名称前面加上感叹号，sphinx将从基础HTML主题加载布局模板。
重要
如果覆盖块，请调用 {{{{ super() }}}} 在扩展模板中呈现块的原始内容的地方——除非您不希望该内容出现。
使用内置模板¶
建筑工人 基本的 主题提供所有内置的sphinx主题所基于的模板。它具有以下元素，您可以覆盖或使用：
阻碍¶
以下块存在于 layout.html 模板：
doctype输出格式的doctype。默认情况下，这是XHTML 1.0过渡，因为这是最接近sphinx和docutils生成的，最好不要更改它，除非您想切换到HTML 5或其他但兼容的XHTML doctype。
linktags此块添加了
<link>标记到模板的头部分。extrahead默认情况下，此块为空，可用于向
<head>生成的HTML文件的标记。这是添加对javascript或其他CSS文件引用的正确位置。relbar1,relbar2此块包含 关系栏 ，相关链接列表（左侧的父文档，右侧的索引、模块等链接）。
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 %}
(The
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¶
相关栏左侧项目的分隔符。默认为
' »'相关栏中的每个项目都以该变量的值结尾。
- reldelim2¶
相关栏右侧项目的分隔符。默认为
' |'. 除相关栏中最后一个项目外，每个项目都以该变量的值结尾。
重写工作如下：
{% extends "!layout.html" %}
{% set reldelim1 = ' >' %}
- 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)¶
检查具有名称的文档 文件 存在。
- sidebar()¶
返回呈现的侧边栏。
- relbar()¶
返回呈现的关系栏。
- warning(message)¶
发出警告消息。
全局变量¶
这些全局变量在每个模板中都可用，并且可以安全使用。还有更多，但大多数都是实现细节，将来可能会有所改变。
- builder¶
建造商的名称（例如
html或htmlhelp）
- docstitle¶
文件的标题（价值
html_title，除非使用“单个文件”生成器，否则将其设置为None.
- embedded¶
如果构建的HTML要嵌入到一些处理导航的查看应用程序中，而不是Web浏览器中，例如用于HTML帮助或Qt帮助格式，则为true。在这种情况下，不包括侧边栏。
- favicon_url¶
指向当前文档的HTML收藏图标图像的相对路径，或指向收藏图标的URL，或者
''。在 4.0 版本加入.
- file_suffix¶
建筑商的价值
out_suffix属性，即输出文件将得到的文件扩展名。对于标准的HTML生成器，这通常是.html.
- has_source¶
如果复制其余文档源（如果
html_copy_source是True）
- last_updated¶
生成日期。
- logo_url¶
从当前文档到HTML徽标图像的相对路径，或徽标的URL，或者
''。在 4.0 版本加入.
- pagename¶
当前文件的“页面名称”，即如果文件是从REST源生成的，则为文档名称，或者与输出目录相关的等效层次名称。 (
[directory/]filename_without_extension）
- rellinks¶
一个链接列表，放在relbar的左侧，“next”和“prev”旁边。这通常包含到常规索引和其他索引（如python模块索引）的链接。如果你自己添加一些东西，它必须是一个元组
(pagename, link title, accesskey, link text).
- shorttitle¶
价值
html_short_title.
- show_source¶
如果真
html_show_sourcelink是True.
- sphinx_version¶
用于构建的Sphinx版本表示为字符串，例如“3.5.1”。
- sphinx_version_tuple¶
用于构建的Sphinx版本表示为五个元素的元组。对于Sphinx版本3.5.1测试版3，这将是
(3, 5, 1, 'beta', 3)。第四个元素可以是以下元素之一：alpha，beta，rc，final。final始终将0作为最后一个元素。在 4.2 版本加入.
- docutils_version_info¶
用于构建的Docutils版本表示为五个元素的元组。对于Docutils版本0.16.1测试版2，这将是
(0, 16, 1, 'beta', 2)。第四个元素可以是以下元素之一：alpha，beta，candidate，final。final始终将0作为最后一个元素。在 5.0.2 版本加入.
- styles¶
主题或给出的主样式表的名称列表
html_style。在 5.1 版本加入.
- style¶
主样式表的名称，如主题或
html_style.在 5.1 版本发生变更: 主题或
html_style现在可以指定多个样式表，style如果指定了多个样式表，Key将返回最后一个样式表。自 5.1 版本弃用: 使用
styles键，因为不再有单个主样式表。这个style在Sphinx 7.0中将删除密钥。
- title¶
当前文档的标题，如在
<title>标签。
- use_opensearch¶
价值
html_use_opensearch.
除了这些值，还有 主题选项 可用（前缀为 theme_ ）以及用户在 html_context .
在从源文件创建的文档中（与模块索引等自动生成的文件或HTML格式的文档不同），这些变量也可用：
- body¶
在应用主题之前，包含HTML生成器生成的HTML格式页面内容的字符串。
- display_toc¶
如果TOC包含多个条目，则为真的布尔值。
- next¶
导航的下一个文档。此变量为false或有两个属性 link 和 title . 标题包含HTML标记。例如，要生成指向下一页的链接，可以使用以下代码段：
{% if next %} <a href="{{ next.link|e }}">{{ next.title }}</a> {% endif %}
- page_source_suffix¶
呈现的文件的后缀。因为我们支持
source_suffix，这将允许您正确链接到原始源文件。
- sourcename¶
当前文档的复制源文件的名称。只有当
html_copy_source价值是True. 这在创建自动生成的文件时具有空值。
- toc¶
当前页的本地目录，呈现为HTML项目符号列表。
- toctree¶
生成包含当前页的全局TOC树的可调用文件，呈现为HTML项目符号列表。可选关键字参数：
collapse如果为true，则折叠所有不是当前页祖先的TOC条目。
True默认情况下。maxdepth树的最大深度。设置为
-1允许无限的深度。默认为在toctree指令中选择的最大深度。titles_only如果为true，则只在树中放置顶级文档标题。
False默认情况下。includehidden如果为true，则目录树还将包含隐藏项。
False默认情况下。