模板化

Sphinx使用 Jinja 模板引擎来处理其HTML模板.Jinja是一个基于文本的引擎,灵感来自Django模板,因此任何使用过Django的人都对其感到熟悉.对于那些需要熟悉它的人,Jinja也有很好的文档.

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

没有.您还有其他几种选择:

Jinja/Sphinx 模板入门

Sphinx中的默认模板语言是Jinja.它受到Django/Smarty的启发,易于理解.Jinja中最重要的概念是 模板继承 ,这意味着你可以仅覆盖模板中的特定块,从而在进行自定义的同时将更改保持在最低限度.

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

Sphinx将首先在 :confval: templates_path`指定的文件夹中查找模板,如果在那里找不到所需的模板,它将回退到所选主题的模板.

模板包含**变量**,在模板被评估时这些变量会被替换为值,**标签**,用于控制模板的逻辑,以及**块**,用于模板继承.

Sphinx的*基本*主题提供了基本模板,并包含一些将填充数据的块.这些块位于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() }} 以渲染块的原始内容,除非您不希望该内容显示出来.

与内置模板一起工作

内置的 basic 主题提供了所有内置 Sphinx 主题所基于的模板.它具有以下元素,您可以覆盖或使用:

块

以下区块存在于 layout.html 模板中:

doctype

输出格式的文档类型.默认情况下,这是 XHTML 1.0 Transitional,因为它与 Sphinx 和 Docutils 生成的内容最为接近,除非你想切换到 HTML 5 或其他兼容的 XHTML 文档类型,否则最好不要更改它.

linktags

该代码块向模板的头部添加了一些 <link> 标签.

extrahead

此块默认是空的,可用于向生成的 HTML 文件的 <head> 标签中添加额外内容.这是添加 JavaScript 或额外 CSS 文件引用的合适位置.

relbar1, relbar2

此块包含 关系栏,包含相关链接的列表（左侧是父文档,右侧是索引、模块等的链接）. relbar1 出现在文档之前,而 relbar2 出现在文档之后. 默认情况下,两个块都是填充的;要仅在文档之前显示关系栏,您可以像这样覆盖 relbar2

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

在关系条内有三个部分: 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

侧边栏内的徽标位置.如果您想在侧边栏顶部放置一些内容,请覆盖此设置.

footer

用于页脚 div 的块.如果您想要自定义页脚或在其之前或之后添加标记,请覆盖此块.

以下四个块*仅*用于未在 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提供了各种Jinja函数作为模板中的助手.您可以使用它们来生成链接或输出多次使用的元素.

pathto(document)

返回Sphinx文档的路径作为URL.使用此方法引用已生成的文档.

pathto(file, 1)

返回一个 file 的路径,该文件名相对生成输出的根目录.使用此方法引用静态文件.

hasdoc(document)

检查是否存在名为 document 的文档.

返回呈现的侧边栏.

relbar()

返回渲染的关系条.

warning(message)

发出警告信息.

全局变量

这些全局变量在每个模板中均可用,并且安全可用.还有更多变量,但其中大多数是实现细节,未来可能会发生变化.

builder

构建器的名称（例如 html 或 htmlhelp ）.

The value of copyright.

docstitle

文档的标题（html_title 的值）,除非使用 “单文件” 构建器,此时设置为 None .

embedded

如果生成的 HTML 是为了嵌入到一些处理导航的查看应用程序中,而不是网页浏览器,例如用于 HTML 帮助或 Qt 帮助格式,则返回 True.在这种情况下,不包括侧边栏.

favicon_url

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

Added in version 4.0.

file_suffix

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

has_source

如果 html_copy_source 为 True ,则表示复制了 reStructuredText 文档源.

language

The value of 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

当前文件的”页面名称”,即如果该文件是从 reStructuredText 源生成的,则为文档名称;如果不是,则为相对于输出目录的等效层次名称 ( [directory/]filename_without_extension ).

project

该值为 project .

release

The value of release.

在relbar的左侧放置的链接列表,位于”下一页”和”上一页”旁边. 这通常包含指向一般索引和其他索引的链接,例如Python模块索引. 如果您自己添加内容,则必须是一个元组 (pagename, link title, accesskey, link text) .

shorttitle

html_short_title 的值.

show_source

如果 html_show_sourcelink 为 True ,则返回 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

The value of html_use_opensearch.

version

The value of version.

除了这些值,还有所有可用的 **主题选项**（以 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

一个可调用的函数,返回包含当前页面的全局TOC树,并以HTML列表的形式渲染.可选的关键字参数:

collapse

如果为真,则当前页面的所有非祖先TOC条目都会被折叠.默认值为 True .

maxdepth

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

titles_only

如果为真,则只在树中放置顶级文档标题.默认为 False .

includehidden

如果为真,目录树将包含隐藏条目. 默认情况下为 False .