构建器

以下是 Sphinx 内置的构建器。更多构建器可以通过 扩展 添加。

要选择一个构建器，构建器的“名称”必须传递给 sphinx-build 命令行选项的 -M 或 -b。

最常用的构建器是

html

构建 HTML 页面。这是默认的构建器。

dirhtml

构建 HTML 页面，但每个文档使用一个单独的目录。如果从 Web 服务器提供服务，这将使 URL 更漂亮（没有 .html）。

singlehtml

构建包含全部内容的单个 HTML 文件。

htmlhelp, qthelp, devhelp, epub

构建包含附加信息以在这些格式中构建文档集的 HTML 文件。

applehelp

构建 Apple Help Book。需要 hiutil 和 codesign，它们不是开源的，目前仅在 Mac OS X 10.6 及更高版本上可用。

latex

构建 LaTeX 源代码，可以使用 pdflatex 编译为 PDF 文档。

man

为 UNIX 系统构建 groff 格式的手册页。

texinfo

构建 Texinfo 文件，可以使用 makeinfo 处理为 Info 文件。

text

构建纯文本文件。

gettext

构建 gettext 样式的消息目录 (.pot 文件)。

doctest

如果启用了 doctest 扩展，则运行文档中的所有 doctest。

linkcheck

检查所有外部链接的完整性。

xml

构建 Docutils 原生的 XML 文件。

pseudoxml

构建紧凑的漂亮打印的“伪 XML”文件，显示中间文档树的内部结构。

---

class sphinx.builders.html.StandaloneHTMLBuilder

这是标准的 HTML 构建器。它的输出是一个包含 HTML 文件的目录，包括样式表以及可选的 reStructuredText 源代码。有许多配置值可以定制此构建器的输出，有关详细信息，请参见 HTML 输出选项 章节。

name = 'html'

构建器的名称，用于 -b 命令行选项。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

class sphinx.builders.dirhtml.DirectoryHTMLBuilder

这是标准 HTML 构建器的子类。它的输出是一个包含 HTML 文件的目录，其中每个文件名为 index.html 并放置在与其页面名称相同的子目录中。例如，文档 markup/rest.rst 不会导致生成输出文件 markup/rest.html，而是 markup/rest/index.html。在生成页面间的链接时，index.html 会被省略，因此 URL 会像 markup/rest/ 这样。

name = 'dirhtml'

构建器的名称，用于 -b 命令行选项。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

版本 0.6 中添加。

class sphinx.builders.singlehtml.SingleFileHTMLBuilder

这是一个 HTML 构建器，它将整个项目合并到一个输出文件中。（显然，这仅适用于较小的项目。）该文件以根文档命名。不会生成索引。

name = 'singlehtml'

构建器的名称，用于 -b 命令行选项。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

版本 1.0 中添加。

class sphinxcontrib.htmlhelp.HTMLHelpBuilder

此构建器生成与独立 HTML 构建器相同的输出，但也生成 HTML 帮助支持文件，这些文件允许 Microsoft HTML 帮助工作台将它们编译为 CHM 文件。

name = 'htmlhelp'

构建器的名称，用于 -b 命令行选项。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

class sphinxcontrib.qthelp.QtHelpBuilder

此构建器会生成与独立 HTML 构建器相同的输出，但还会生成 Qt 帮助 集合支持文件，以供 Qt 集合生成器编译这些文件。

自版本 2.0 起更改: 从 sphinx.builders 包移动到 sphinxcontrib.qthelp。

name = 'qthelp'

构建器的名称，用于 -b 命令行选项。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

class sphinxcontrib.applehelp.AppleHelpBuilder

此构建器会生成基于与独立 HTML 构建器相同输出的 Apple 帮助手册。

如果源目录包含任何 .lproj 文件夹，则与所选语言相对应的文件夹的内容将与其生成的输出合并。这些文件夹将被所有其他文档类型忽略。

为了生成有效的帮助手册，此构建器需要命令行工具 hiutil，该工具仅在 Mac OS X 10.6 及更高版本上可用。可以通过将 applehelp_disable_external_tools 设置为 True 来禁用索引步骤，在这种情况下，输出在 hiutil 在捆绑包内的所有 .lproj 文件夹上运行之前将无效。

name = 'applehelp'

构建器的名称，用于 -b 命令行选项。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg', 'image/tiff', 'image/jp2', 'image/svg+xml']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

自版本 1.3 起添加。

自版本 2.0 起更改: 从 sphinx.builders 包移动到 sphinxcontrib.applehelp。

class sphinxcontrib.devhelp.DevhelpBuilder

此构建器会生成与独立 HTML 构建器相同的输出，但还会生成 GNOME Devhelp 支持文件，以供 GNOME Devhelp 阅读器查看这些文件。

name = 'devhelp'

构建器的名称，用于 -b 命令行选项。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

自版本 2.0 起更改: 从 sphinx.builders 包移动到 sphinxcontrib.devhelp。

class sphinx.builders.epub3.Epub3Builder

此构建器会生成与独立 HTML 构建器相同的输出，但还会生成用于电子书阅读器的 epub 文件。有关详细信息，请参阅 Epub 信息。有关 epub 格式的定义，请查看 https://idpf.org/epub 或 https://en.wikipedia.org/wiki/EPUB。此构建器会创建 EPUB 3 文件。

name = 'epub'

构建器的名称，用于 -b 命令行选项。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

自版本 1.4 起添加。

自版本 1.5 起更改: 自 Sphinx 1.5 起，epub3 构建器用作默认的 epub 构建器。

class sphinx.builders.latex.LaTeXBuilder

此构建器会在输出目录中生成 LaTeX 源文件。实际的 PDF 构建发生在该输出目录内，需要在第二步中触发。这可以通过在该目录中使用 make all-pdf 来完成。要将这两个步骤合并为一个，请使用 sphinx-build -M（即 -M latexpdf 而不是 -b latexpdf）或在项目根目录中使用 make latexpdf。

有关可用选项，请参阅 latex_documents 和章节 LaTeX 输出选项。

PDF 构建需要一个足够完整的 LaTeX 安装。当前（自 5.3.0 起）测试是在 Ubuntu 22.04LTS 上完成的，其 LaTeX 发行版与截至 2022/02/04 的上游 TeXLive 2021 相匹配，但 PDF 构建可以在更旧的 LaTeX 安装上成功完成。

无论如何，例如在 Ubuntu 上，以下软件包必须全部存在

• texlive-latex-recommended

• texlive-fonts-recommended

• texlive-fonts-extra（需要 fontawesome5，请参阅下面的 7.4.0 更改通知）

• tex-gyre（如果 latex_engine 保持默认值）

• texlive-latex-extra

• latexmk

自版本 4.0.0 起更改: TeX Gyre 字体现在是 'pdflatex' 引擎（默认值）所必需的。

自版本 7.4.0 起更改: LaTeX 包 xcolor 现在是必需的（它本身就是 Ubuntu texlive-latex-recommended 的一部分）。LaTeX 包 fontawesome5 是推荐的。有关更多信息，请参阅 ‘sphinxsetup’ iconpackage 键。

在某些情况下需要其他软件包

• texlive-lang-cyrillic 用于西里尔字母（如果使用默认字体，则还需要 cm-super），

• texlive-lang-greek 用于希腊语（如果使用默认字体，则还需要 cm-super），

• texlive-xetex 如果 latex_engine 为 'xelatex'，

• texlive-luatex 如果 latex_engine 为 'lualatex'，

• fonts-freefont-otf 如果 latex_engine 为 'xelatex' 或 'lualatex'。

注意

从 1.6 版开始，make latexpdf 在 GNU/Linux 和 macOS 上使用 latexmk，因为它可以确保自动执行所需的运行次数。在 Windows 上，PDF 构建会执行固定数量的 LaTeX 运行（三次，然后是 makeindex，最后再运行两次）。

可以通过 LATEXMKOPTS Makefile 变量将选项传递给 latexmk。例如

make latexpdf LATEXMKOPTS="-silent"

将控制台输出减少到最小。

此外，如果 latexmk 的版本为 4.52b 或更高版本（2017 年 1 月），LATEXMKOPTS="-xelatex" 可以通过 XeLateX 加速 PDF 构建，尤其是在包含大量图形的情况下。

要直接将选项传递给 (pdf|xe|lua)latex 二进制文件，请使用变量 LATEXOPTS，例如

make latexpdf LATEXOPTS="--halt-on-error"

name = 'latex'

构建器的名称，用于 -b 命令行选项。

format = 'latex'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['application/pdf', 'image/png', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

请注意，rinohtype 提供了一个直接的 PDF 构建器。构建器的名称是 rinoh。有关详细信息，请参阅 rinohtype 手册。

class sphinx.builders.text.TextBuilder

此构建器为每个 reStructuredText 文件生成一个文本文件。这与 reStructuredText 源代码几乎相同，但去掉了大部分标记，以提高可读性。

name = 'text'

构建器的名称，用于 -b 命令行选项。

format = 'text'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = []

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

在版本 0.4 中添加。

class sphinx.builders.manpage.ManualPageBuilder

此构建器以 groff 格式生成手册页。您需要通过 man_pages 配置值指定哪些文档要包含在哪些手册页中。

name = 'man'

构建器的名称，用于 -b 命令行选项。

format = 'man'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = []

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

版本 1.0 中添加。

class sphinx.builders.texinfo.TexinfoBuilder

此构建器生成 Texinfo 文件，这些文件可以通过 makeinfo 程序处理成 Info 文件。您需要通过 texinfo_documents 配置值指定哪些文档要包含在哪些 Texinfo 文件中。

Info 格式是 GNU Emacs 和基于终端的程序 info 使用的在线帮助系统的基础。有关详细信息，请参阅 Texinfo info。Texinfo 格式是 GNU 项目使用的官方文档系统。有关 Texinfo 的更多信息，请访问 https://www.gnu.org/software/texinfo/。

name = 'texinfo'

构建器的名称，用于 -b 命令行选项。

format = 'texinfo'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/png', 'image/jpeg', 'image/gif']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

在版本 1.1 中添加。

class sphinxcontrib.serializinghtml.SerializingHTMLBuilder

此构建器使用一个实现 Python 序列化 API (pickle、simplejson、phpserialize 等) 的模块来转储生成的 HTML 文档。pickle 构建器是它的一个子类。

此构建器的具体子类序列化为 PHP 序列化 格式可能如下所示

import phpserialize

class PHPSerializedBuilder(SerializingHTMLBuilder):
    name = 'phpserialized'
    implementation = phpserialize
    out_suffix = '.file.phpdump'
    globalcontext_filename = 'globalcontext.phpdump'
    searchindex_filename = 'searchindex.phpdump'

implementation

一个实现 dump()、load()、dumps() 和 loads() 函数的模块，这些函数符合 pickle 模块中同名函数的规范。已知实现此接口的模块有 simplejson、phpserialize、plistlib 等。

out_suffix

所有常规文件的扩展名。

globalcontext_filename

包含“全局上下文”文件的名称。这是一个字典，其中包含一些通用配置值，例如项目的名称。

searchindex_filename

Sphinx 生成的搜索索引文件的名称。

有关输出格式的详细信息，请参阅 序列化构建器详细信息。

在版本 0.5 中添加。

class sphinxcontrib.serializinghtml.PickleHTMLBuilder

此构建器生成一个包含 pickle 文件的目录，这些文件主要包含 HTML 片段和 TOC 信息，用于使用不使用标准 HTML 模板的 Web 应用程序（或自定义后处理工具）。

有关输出格式的详细信息，请参阅 序列化构建器详细信息。

name = 'pickle'

构建器的名称，用于 -b 命令行选项。

旧名称 web 仍然有效。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

文件后缀为 .fpickle。全局上下文称为 globalcontext.pickle，搜索索引为 searchindex.pickle。

class sphinxcontrib.serializinghtml.JSONHTMLBuilder

此构建器生成一个目录，其中包含包含大部分 HTML 片段和 TOC 信息的 JSON 文件，供不使用标准 HTML 模板的 Web 应用程序（或自定义后处理工具）使用。

有关输出格式的详细信息，请参阅 序列化构建器详细信息。

name = 'json'

构建器的名称，用于 -b 命令行选项。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

文件后缀为 .fjson。全局上下文称为 globalcontext.json，搜索索引为 searchindex.json。

在版本 0.5 中添加。

class sphinx.builders.gettext.MessageCatalogBuilder

此构建器生成 gettext 风格的消息目录。每个顶级文件或子目录都会生成一个单独的 .pot 目录模板。

有关更多参考，请参阅关于 国际化 的文档。

name = 'gettext'

构建器的名称，用于 -b 命令行选项。

format = ''

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = []

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

在版本 1.1 中添加。

class sphinx.builders.changes.ChangesBuilder

此构建器生成所有 versionadded、versionchanged、deprecated 和 versionremoved 指令的 HTML 概述，用于当前的 version。这对于生成更改日志文件（例如）非常有用。

name = 'changes'

构建器的名称，用于 -b 命令行选项。

format = ''

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = []

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

class sphinx.builders.dummy.DummyBuilder

此构建器不生成任何输出。输入只会被解析并检查一致性。这对于 linting 目的很有用。

name = 'dummy'

构建器的名称，用于 -b 命令行选项。

supported_image_types: list[str] = []

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

自版本 1.4 起添加。

class sphinx.builders.linkcheck.CheckExternalLinksBuilder

此构建器扫描所有文档以查找外部链接，尝试使用 requests 打开它们，并写入哪些链接已损坏以及重定向到标准输出和输出目录中的 output.txt 的概述。

name = 'linkcheck'

构建器的名称，用于 -b 命令行选项。

format = ''

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = []

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

更改于版本 1.5: 自 Sphinx 1.5 以来，linkcheck 构建器使用 requests 模块。

更改于版本 3.4: linkcheck 构建器在服务器应用速率限制时重试链接。

class sphinx.builders.xml.XMLBuilder

此构建器生成 Docutils 本地 XML 文件。输出可以使用标准 XML 工具（例如 XSLT 处理器）转换为任意最终形式。

name = 'xml'

构建器的名称，用于 -b 命令行选项。

format = 'xml'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = []

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

在版本 1.2 中添加。

class sphinx.builders.xml.PseudoXMLBuilder

此构建器用于调试 Sphinx/Docutils 的“Reader to Transform to Writer”管道。它生成紧凑的漂亮打印的“伪 XML”文件，其中嵌套由缩进表示（没有结束标签）。所有元素的外部属性都会输出，任何剩余的“待处理”元素的内部属性也会给出。

name = 'pseudoxml'

构建器的名称，用于 -b 命令行选项。

format = 'pseudoxml'

构建器的输出格式，如果未生成文档输出，则为 ‘’。

supported_image_types: list[str] = []

构建器支持的图像格式 MIME 类型列表。图像文件将按它们在此处出现的顺序进行搜索。

在版本 1.2 中添加。

提供更多构建器的内置 Sphinx 扩展

• doctest

• coverage

序列化构建器详细信息

所有序列化构建器每个源文件输出一个文件，以及一些特殊文件。它们还会将 reStructuredText 源文件复制到输出目录下的 _sources 目录中。

The PickleHTMLBuilder 是一个内置子类，它实现了 pickle 序列化接口。

每个源文件的文件具有 out_suffix 的扩展名，并按照与源文件相同的目录排列。它们反序列化为具有以下键的字典（或类似字典的结构）：

body

由 HTML 翻译器呈现的 HTML “body”（即源文件的 HTML 呈现）。

title

文档标题，作为 HTML（可能包含标记）。

toc

文件的目录，作为 HTML <ul> 呈现。

display_toc

如果 toc 包含多个条目，则为 True 的布尔值。

current_page_name

当前文件的文档名称。

parents、prev 和 next

有关 TOC 树中相关章节的信息。每个关系都是一个字典，具有键 link（关系的 HREF）和 title（相关文档的标题，作为 HTML）。parents 是关系列表，而 prev 和 next 是单个关系。

sourcename

在 _sources 下的源文件名。

特殊文件位于根输出目录中。它们是：

SerializingHTMLBuilder.globalcontext_filename

一个带有以下键的腌制字典：

project、copyright、release、version

与配置文件中给出的相同值。

style

html_style.

last_updated

上次构建的日期。

builder

使用的构建器名称，在 pickle 的情况下，它始终为 'pickle'。

titles

所有文档标题的字典，作为 HTML 字符串。

SerializingHTMLBuilder.searchindex_filename

可用于搜索文档的索引。它是一个腌制列表，其中包含以下条目：

• 已索引的 docnames 列表。

• 文档标题列表，作为 HTML 字符串，与第一个列表的顺序相同。

• 一个将单词词根（由英语词干提取器处理）映射到整数列表的字典，这些整数是第一个列表中的索引。

environment.pickle

构建环境。这始终是一个 pickle 文件，与构建器无关，并且是构建器启动时使用的环境的副本。

与其他 pickle 文件不同，此 pickle 文件要求在解腌时 sphinx 包可用。

Previous

Configuration

Next

Domains