模板法

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

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

不是的。您还有几个其他选项：

金佳/Sphinx模板底漆

Sphinx中的默认模板语言是JJJA。这是Django/Smarty的灵感，很容易理解。金家最重要的概念是 template inheritance ，这意味着您只能覆盖模板中的特定块，对其进行自定义，同时将更改保持在最低限度。

要定制文档的输出，您可以覆盖所有模板(布局模板和子模板)，方法是将与原始文件名相同的文件添加到Sphinx QuickStart为您生成的结构的模板目录中。

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

模板包含 variables ，这些值在评估模板时被替换为值， tags ，它控制模板的逻辑和 blocks 它们用于模板继承。

Sphinx basic Theme为基本模板提供了几个块，这些块将填充数据。它们位于 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

输出格式的doctype。默认情况下，这是XHTML1.0转换类型，因为它最接近Sphinx和Docutils生成的内容，除非您想切换到HTML5或不同但兼容的XHTMLdoctype，否则最好不要更改它。

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

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

以下四个区块是 only 中尚未分配自定义侧栏列表的页面使用 html_sidebars 配置值。不建议使用它们，而是支持单独的侧边栏模板，该模板可以通过 html_sidebars 。

sidebartoc

侧边栏中的目录。

自 1.0 版本弃用.

sidebarrel

侧边栏中的关系链接(上一个、下一个文档)。

自 1.0 版本弃用.

sidebarsourcelink

侧边栏中的“Show source”链接(通常仅当启用此功能时才显示 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在模板中提供了各种JJJA函数作为帮助器。您可以使用它们来生成链接或输出多次使用的元素。

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帮助格式，则为True。在这种情况下，不包括侧边栏。

favicon_url

指向当前文档的HTML收藏图标图像的相对路径，或指向收藏图标的URL，或者 '' 。

Added in version 4.0.

file_suffix

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

has_source

如果复制了REST文档源(如果 html_copy_source 是 True )。

language

的价值 language 。

last_updated

构建日期。

logo_url

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

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

要放在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作为最后一个元素。

Added in version 4.2.

docutils_version_info

用于构建的Docutils版本表示为五个元素的元组。对于Docutils版本0.16.1测试版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

如果目录包含多个条目，则布尔值为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 项目。

prev

喜欢 next ，而不是上一页。

sourcename

当前文档的复制源文件的名称。只有在以下情况下才为非空 html_copy_source 值为 True 。这对于创建自动生成的文件具有空值。

toc

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

toctree

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

collapse

如果为True，则折叠不是当前页的祖先的所有目录条目。 True 默认情况下。

maxdepth

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

titles_only

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

includehidden

如果为True，则目录树还将包含隐藏条目。 False 默认情况下。