主题化¶

Sphinx 使用 Jinja 模板引擎来制作 HTML 模板。Jinja 是一个基于文本的引擎，灵感来自 Django 模板，所以任何使用过 Django 的人都会熟悉它。对于那些需要熟悉它的人，它也有很好的文档。

我需要使用 Sphinx 的模板来制作 HTML 吗？¶

不，你有其他几个选择：

你可以写一个 TemplateBridge 子类，调用你选择的模板引擎，并相应设置 template_bridge 配置值。
你可以写一个自定义的构建器，它源自 StandaloneHTMLBuilder 并调用你选择的模板引擎。
你可以使用 PickleHTMLBuilder，它产生带有页面内容的 pickle 文件，并使用自定义工具对其进行后处理，或在你的 Web 应用程序中使用它们。

Jinja/Sphinx 模板化入门¶

Sphinx 的默认模板语言是 Jinja。它受 Django/Smarty 启发，易于理解。Jinja 中最重要的概念是 模板继承，这意味着你可以在模板中只覆盖特定的块，定制它的同时也将变化控制在最小范围。

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

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

模板包含 variables （这些变量在模板被评估时被替换成值），tags （控制模板的逻辑）以及 blocks （用于模板的继承）。

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() }}，以便在插件模板中呈现该块的原始内容–除非你不希望该内容显示出来。

令内置模板生效¶

内建的 basic 主题提供了所有内建的 Sphinx 主题所基于的模板。它有以下元素，你可以覆盖或使用：

块¶

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

doctype

输出格式的 doctype。默认是 XHTML 1.0 Transitional，因为它最接近 Sphinx 和 Docutils 生成的格式，除非你想切换到 HTML 5 或不同但兼容的 XHTML doctype，否则最好不要改变它。

linktags

这个块在模板的头部添加了几个 <link> 标签。

extrahead

这个区块默认是空的，可以用来在生成的 HTML 文件的 <head> 标签中添加额外的内容。这是添加对 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" 属性的 HTML 元素中。例如

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

sidebar1, sidebar2

一个可能的侧边栏位置。sidebar1 出现在文档之前，默认为空，sidebar2 在文档之后，包含默认的侧边栏。如果你想更换侧边栏的位置，可以覆盖这个，并调用 sidebar 助手

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

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

sidebarlogo

侧边栏内的 logo 位置。如果你想把一些内容放在侧边栏的顶部，可以覆盖这个。

footer

用于页脚 DIV 的块。如果你想在它之前或之后有一个自定义的页脚或标记，请覆盖这个。

以下四个块只用于那些没有在 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 = ' &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 的文件。

sidebar()¶: 返回已渲染的侧边栏。

relbar()¶: 返回已渲染的关系栏。

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

全局变量¶

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

builder¶: 构建器的名称（例如，html 或 htmlhelp）。

copyright¶: copyright 的值。

docstitle¶: 文档的标题（html_title 的值），除了当使用 “single-file” 构建器时，它被设置为 None。

embedded¶: 如果内置的 HTML 是为了嵌入到一些处理导航的查看程序中，而不是 Web 浏览器，例如 HTML 帮助或 Qt 帮助格式，则为真。在这种情况下，侧边栏就不包括在内。

favicon¶: 静态路径中的 HTML favicon 的路径，或指向 favicon 的 URL，或 ''。

4.0 版后已移除: 建议使用 favicon_url 代替。

favicon_url¶: 当前文档中的 HTML favicon 图片的相对路径，或指向 favicon 的URL，或 ''。

4.0 新版功能.

file_suffix¶: 构建器的 out_suffix 属性的值，即输出文件将得到的文件名扩展。对于一个标准的 HTML 生成器，这通常是 .html。

has_source¶: 如果 reST 文档源被复制，则为真（如果 html_copy_source 是 True ）。

language¶: language 的值。

last_updated¶: 构建日期。

logo¶: 静态路径中的 HTML 标志图片的路径，或标志的 URL，或 ''。

4.0 版后已移除: 建议使用 logo_url 代替。

logo_url¶: 当前文档中 HTML 标志图片的相对路径，或标志的 URL，或 ''。

4.0 新版功能.

master_doc¶: 同 root_doc。

在 4.0 版更改: 重命名为 root_doc。

root_doc¶: root_doc 的值，与 pathto() 一起使用。

在 4.0 版更改: 从 master_doc 重新命名。

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

project¶: project 的值。

release¶: release 的值。

rellinks¶: 在relbar的左边，在 “next” 和 “previous” 旁边的链接列表。这通常包含指向总索引和其他索引的链接，例如 Python 模块索引。如果你自己添加东西，它必须是一个元

shorttitle¶: html_short_title 的值。

show_source¶: 如果 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 作为最后一个元素。

4.2 新版功能.

style¶: 主样式表的名称，由主题或 html_style 给出。

title¶: 当前文档的标题，在 <title> 标记中使用。

use_opensearch¶: html_use_opensearch 的值。

version¶: 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 bullet 列表。

toctree¶

一个可调用程序，产生包含当前页面的全局 TOC 树，以 HTML bullet 列表的形式呈现。可选的关键字参数：

collapse: 如果为真，所有不是当前页的祖先的 TOC 条目都会被折叠起来。默认为 True。
maxdepth: 树的最大深度。将其设置为 -1 以允许无限深度。默认为 toctree 指令中选择的最大深度。
titles_only: 如果是真的，在树上只放顶层的文档标题。默认为 False。
includehidden: 如果为真，ToC 树也将包含隐藏条目。默认为 False。

目录

上一个主题

下一个主题

本页