模板

Sphinx使用 Jinja 模板引擎作为其HTML模板. Jinja是一个基于文本的引擎, 受到Django模板的启发, 因此任何使用过Django的人都会熟悉它. 它还为那些需要熟悉它的人提供了出色的文档.

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

不, 您还有其他几种选择:

  • 你可以编写一个 TemplateBridge 子类来调用你选择的模板引擎, 并相应地设置 template_bridge 配置值.

  • 您可以 编写一个自定义构建器, 它派生自 StandaloneHTMLBuilder 并调用您选择的模板引擎.

  • 您可以使用 PickleHTMLBuilder 生成带有页面内容的 pickle 文件, 并使用自定义工具对其进行后处理, 或者在Web应用程序中使用它们.

Jinja/Sphinx 模板入门

Sphinx中的默认模板语言是Jinja. 这是 Django/Smarty 的灵感和易于理解. Jinja中最重要的概念是 template inheritance , 这意味着您只能覆盖模板中的特定块, 自定义它, 同时将更改保持在最低限度.

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

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()}} 以在扩展模板中呈现块的原始内容 - 除非您不希望显示该内容.

使用内置模板

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

Blocks

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

doctype

输出格式的doctype. 默认情况下, 这是XHTML 1.0 Transitional, 因为它最接近Sphinx和Docutils生成的内容, 除非您想要切换到HTML 5或不同但兼容的XHTML doctype, 否则最好不要更改它.

linktags

这个块在模板的head部分添加了几个 <link> 标签.

extrahead

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

relbar1 / relbar2

该块包含*关系栏*, 相关链接列表(左侧的父文档, 右侧的索引链接, 模块等). relbar1 出现在文档之前, relbar2 出现在文档之后. 默认情况下, 两个块都已填充;要在文档之前显示relbar, 你可以像这样重写 relbar2

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

在relbar里面有三个部分: rootrellink, 文档中的链接和自定义 relbaritems. rootrellink 是一个默认包含指向主文档的列表项的块, relbaritems 是一个空块. 如果覆盖它们以在条形图中添加额外的链接, 请确保它们是列表项并以 reldelim1 结束.

文档

文件本身的内容. 它包含块 “body” , 其中单个内容由 page.html 等子模板放置.

sidebar1 / sidebar2

侧边栏的可能位置. sidebar1 出现在文档之前, 默认为空, 在文档后面是`sidebar2`并包含默认侧边栏. 如果你想交换边栏位置覆盖它并调用 sidebar 帮助器:

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

(例如, sphinxdoc.css 样式表需要侧边栏的 sidebar2 位置. )

sidebarlogo

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

页脚

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

以下四个块 仅 用于未在 html_sidebars 配置值中分配自定义侧边栏列表的页面. 它们的使用已被弃用, 有利于单独的侧边栏模板, 可以通过以下方式包含 html_sidebars .

sidebartoc

侧栏内的目录.

1.0 版后已移除.

sidebarrel

边栏内的关系链接(上一个, 下一个文档).

1.0 版后已移除.

sidebarsourcelink

侧边栏中的“显示源”链接(通常仅在以下情况下显示 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)

将路径返回到*文件*, 该文件是相对于生成的输出的根的文件名. 用它来引用静态文件.

hasdoc(document)

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

返回渲染的侧边栏.

relbar()

返回渲染的关系栏.

warning(message)

发出警告信息.

全局变量

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

builder

构建器的名称(例如``html``或``htmlhelp``).

价值 copyright .

docstitle

文档的标题(值 html_title), 除非使用“单文件”构建器, 否则设置为“无”.

embedded

如果构建的HTML旨在嵌入到处理导航的某个查看应用程序中, 而不是Web浏览器(例如HTML帮助或Qt帮助格式), 则为True. 在这种情况下, 侧边栏不包括在内.

favicon

静态路径中 HTML favicon 的路径, 或者 ''.

file_suffix

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

has_source

如果复制了reST文档源, 则为True(如果 html_copy_source`为``True`).

language

language 的值 .

last_updated

构建日期.

静态路径中HTML徽标图像的路径, 或者``’``.

master_doc

master_doc 的值, 用于 pathto().

pagename

当前文件的“页面名称”, 即文件名(如果文件是从reST源生成的), 或者是相对于输出目录的等效层次名称([directory/] filename_without_extension).

project

值 project.

release

值 release.

放置在relbar左侧, “next” 和 “prev” 旁边的链接列表. 这通常包含指向常规索引和其他索引的链接, 例如Python模块索引. 如果你自己添加一些东西, 它必须是一个元组 (页面名称, 链接标题, 访问键, 链接文本).

shorttitle

值 html_short_title.

show_source

如果 html_show_sourcelink 是 True , 则为真.

sphinx_version

用于构建的Sphinx版本.

style

主要样式表的名称, 由主题或 html_style 给出.

title

当前文档的标题, 在 <title> 标签中使用.

use_opensearch

值 html_use_opensearch.

version

值 html_use_opensearch.

除了这些值之外, 还有所有 主题选项 (以 theme_ 为前缀), 以及用户在 html_context 中给出的值.

在从源文件创建的文档中(与自动生成的文件(如模块索引或已经是HTML格式的文档)相反), 这些变量也可用:

body

在应用主题之前, 包含HTML构建器生成的HTML表单内容的字符串.

display_toc

如果toc包含多个条目, 则为布尔值为True.

meta

文档元数据(字典), 请参阅 File-wide metadata.

metatags

包含页面HTML meta 标签的字符串.

next

导航的下一个文档. 这个变量要么是假的, 要么有两个属性 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, 则这只是非空的. 这对于创建自动生成的文件没有空白价值.

title

页面标题.

toc

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

toctree

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

  • collapse (默认为 True):如果为true, 则表示当前页面不是祖先的所有TOC条目都将折叠

  • maxdepth (默认为toctree指令中选择的最大深度):树的最大深度;将它设置为 -1 以允许无限深度

  • titles_only``(默认为 ``False):如果为true, 则只在树中放入文档标题

  • includehidden``(默认为 ``False`): 如果为true, TOC树也将包含隐藏的条目.