模板¶

Sphinx uses the Jinja templating engine for its HTML templates. Jinja is a text-based engine, inspired by Django templates, so anyone having used Django will already be familiar with it. It also has excellent documentation for those who need to make themselves familiar with it.

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

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

你可以写一个：类：`~sphinx.application.TemplateBridge`调用所选模板引擎的子类，并相应地设置：confval:`template_bridge`配置值。
您可以：ref:`write a custom builder 1`派生自：class:`~sphinx.builders.html.StandaloneHTMLBuilder`并调用您选择的模板引擎。
You can use the PickleHTMLBuilder that produces pickle files with the page contents, and postprocess them using a custom tool, or use them in your Web application.

Jinja/Sphinx模板¶

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

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

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

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

Sphinx的*basic*主题为基本模板提供了几个它将填充数据的块。它们位于Sphinx安装目录的：file:`themes/basic`子目录中，由所有内置的Sphinx主题使用。在：confval:`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主题所基于的模板。您可以覆盖或使用以下元素：

模块¶

以下块存在于``布局.html``模板：

doctype

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

linktags

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

extrahead

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

relbar1, relbar2

This block contains the relation bar, the list of related links (the parent documents on the left, and the links to index, modules etc. on the right). relbar1 appears before the document, relbar2 after the document. By default, both blocks are filled; to show the relbar only before the document, you would override relbar2 like this:

{% block relbar2 %}{% endblock %}

rootrellink, relbaritems

Inside the relbar there are three sections: The rootrellink, the links from the documentation and the custom relbaritems. The rootrellink is a block that by default contains a list item pointing to the root document by default, the relbaritems is an empty block. If you override them to add extra links into the bar make sure that they are list items and end with the reldelim1.

文档

文档本身的内容。它包含块“body”，其中单个内容由子模板放置，如``页面.html``.

备注

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

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

边栏1, 边栏2

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

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

（侧边栏的“侧边栏2”位置是``狮身人面像.css``例如样式表。）

边栏图标

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

脚注

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

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

边栏: 侧边栏中的目录。

自 1.0 版本弃用.
“边栏”: 侧边栏中的关系链接（上一个、下一个文档）。

自 1.0 版本弃用.
“边栏源链接”: 侧边栏中的“Show source”链接（通常仅在启用此链接的情况下显示：confval: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_文件（）``。

辅助函数¶

Sphinx在模板中提供各种Jinja函数作为助手。您可以使用它们来生成链接或输出多个使用过的元素。

pathto(document)¶: 将Sphinx文档的路径作为URL返回。使用此选项可引用生成的文档。

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

hasdoc(document)¶: 检查名称为*document*的文档是否存在。

sidebar()¶: 返回呈现的边栏。

relbar()¶: 返回呈现的关系栏。

warning(message)¶: 发出警告消息。

全局变量¶

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

builder¶: 生成器的名称（例如`html``或``htmlhelp```）。

copyright¶: 值：confval:copyright。

docstitle¶: 文档的标题（值：confval:html_title），除非使用“single file”生成器，当它被设置为“None`”。

embedded¶: 如果生成的HTML是要嵌入某些处理导航的查看应用程序（而不是web浏览器，例如HTML帮助或Qt帮助格式）中，则为True。在这种情况下，不包括侧边栏。

favicon_url¶: The relative path to the HTML favicon image from the current document, or URL to the favicon, or ''.

Added in version 4.0.

file_suffix¶: 生成器的值：attr:` ~.Serializingtmlbuilder.out_后缀`属性，即输出文件将获得的文件扩展名。对于标准的HTML生成器，通常是“.HTML”。

has_source¶: 如果复制了reST文档源，则为True（如果：confval:html_copy_source`为’`True``）。

language¶: 值：confval:language。

last_updated¶: 生成日期。

logo_url¶: The relative path to the HTML logo image from the current document, or URL to the logo, or ''.

Added in version 4.0.

master_doc¶: 与 root_doc 相同。

在 4.0 版本发生变更: 改名为``root_doc``。

root_doc¶: The value of root_doc, for usage with pathto().

在 4.0 版本发生变更: 曾用名 master_doc。

pagename¶: 当前文件的“页面名”，即如果文件是从reST源生成的，则为文档名，或者是与输出目录相对应的等效层次结构名称（[directory/]filename_without_extension``）。

project¶: 值：confval:project。

release¶: 值：confval:release。

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

shorttitle¶: 值：confval:html_short_title。

show_source¶: 如果：confval:html_show_sourcelink`为`True，则为True。

sphinx_version¶: The version of Sphinx used to build represented as a string for example “3.5.1”.

sphinx_version_tuple¶: The version of Sphinx used to build represented as a tuple of five elements. For Sphinx version 3.5.1 beta 3 this would be (3, 5, 1, 'beta', 3). The fourth element can be one of: alpha, beta, rc, final. final always has 0 as the last element.

Added in version 4.2.

docutils_version_info¶: The version of Docutils used to build represented as a tuple of five elements. For Docutils version 0.16.1 beta 2 this would be (0, 16, 1, 'beta', 2). The fourth element can be one of: alpha, beta, candidate, final. final always has 0 as the last element.

Added in version 5.0.2.

styles¶: A list of the names of the main stylesheets as given by the theme or html_style.

Added in version 5.1.

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

use_opensearch¶: 值：confval:html_use_opensearch。

version¶: 值：confval:version。

除了这些值之外，还有所有可用的**主题选项**（前缀为“theme”``），以及用户在：confval:`html_context`中给出的值。

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

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

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

meta¶: 文档元数据（字典），请参阅：ref:metadata。

metatags¶: 包含页面的HTML:dudir:`meta`标记的字符串。

next¶

The next document for the navigation. This variable is either false or has two attributes link and title. The title contains HTML markup. For example, to generate a link to the next page, you can use this snippet:

{% if next %}
<a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %}

page_source_suffix¶: 渲染的文件的后缀。由于我们支持：confval:source_suffix，因此这将允许您正确链接到原始源文件。

parents¶: 用于导航的父文档列表，其结构类似于：data:`next`项。

prev¶: 例如：data:next，但是是对于上一页的。

sourcename¶: 当前文档的复制源文件的名称。只有当：confval:`html_copy_source`值为“True”时，此值才是非空的。对于创建自动生成的文件，此值为空。

toc¶: 当前页面的本地目录，呈现为HTML项目符号列表。

toctree¶

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

collapse: 如果为true，则折叠所有不是当前页的祖先的TOC条目。``默认情况下为True。
最大深度: 树的最大深度。将其设置为“-1”以允许无限深。默认为在toctree指令中选择的最大深度。
仅标题: 如果为true，则只在树中放置顶级文档标题。``默认情况下为False。
“包括”: 如果为true，ToC树也将包含隐藏项。``默认情况下为False。

Sphinx

On this page

Site navigation

模板¶