构建器

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

构建器的“名称”必须在sphinx-build的-M或-b命令行选项中给出，以选择构建器。

最常见的构建器是

html

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

dirhtml

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

singlehtml

构建一个包含所有内容的单一 HTML 文件。

htmlhelp, qthelp, devhelp, epub

构建 HTML 文件，并附带额外信息，用于以这些格式之一构建文档集合。

applehelp

构建 Apple 帮助手册。需要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'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = ['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'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

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

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

0.6 版本新增。

class sphinx.builders.singlehtml.SingleFileHTMLBuilder

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

name = 'singlehtml'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

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

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

版本 1.0 新增。

class sphinxcontrib.htmlhelp.HTMLHelpBuilder

此构建器生成与独立 HTML 构建器相同的输出，但也会生成 HTML 帮助支持文件，允许 Microsoft HTML Help Workshop 将它们编译成 CHM 文件。

name = 'htmlhelp'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = ['image/png', 'image/gif', 'image/jpeg']

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

class sphinxcontrib.qthelp.QtHelpBuilder

此构建器生成与独立 HTML 构建器相同的输出，但也会生成Qt 帮助集合支持文件，允许 Qt 集合生成器编译它们。

版本 2.0 中的更改： 从 sphinx.builders 包移动到 sphinxcontrib.qthelp。

name = 'qthelp'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = ['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来禁用索引步骤，在这种情况下，在捆绑包中的所有.lproj文件夹上运行hiutil之前，输出将无效。

name = 'applehelp'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = ['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'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = ['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'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = ['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 (for fontawesome5, see 7.4.0 change notice below)

• tex-gyre (如果latex_engine保留为默认值)

• texlive-latex-extra

• latexmk

版本 4.0.0 中的更改： TeX Gyre 字体现在是'pdflatex'引擎（默认）的必需品。

版本 7.4.0 中的更改： LaTeX 包xcolor现在是必需的（它 anyhow 是 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 版起，在 GNU/Linux 和 macOS 上，make latexpdf 使用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'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'latex'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

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

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

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

class sphinx.builders.text.TextBuilder

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

name = 'text'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'text'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = []

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

版本 0.4 新增。

class sphinx.builders.manpage.ManualPageBuilder

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

name = 'man'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'man'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = []

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

版本 1.0 新增。

class sphinx.builders.texinfo.TexinfoBuilder

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

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

name = 'texinfo'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'texinfo'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = ['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

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

out_suffix

所有常规文件的后缀。

globalcontext_filename

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

searchindex_filename

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

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

版本 0.5 中新增。

class sphinxcontrib.serializinghtml.PickleHTMLBuilder

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

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

name = 'pickle'

构建器的名称。这是用于在命令行上选择构建器的值。

旧名称web仍然有效。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

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

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

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

class sphinxcontrib.serializinghtml.JSONHTMLBuilder

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

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

name = 'json'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'html'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = ['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'

构建器的名称。这是用于在命令行上选择构建器的值。

format = ''

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = []

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

版本 1.1 新增。

class sphinx.builders.changes.ChangesBuilder

此构建器生成当前版本的所有versionadded、versionchanged、deprecated和versionremoved指令的 HTML 概览。例如，这对于生成更改日志文件很有用。

name = 'changes'

构建器的名称。这是用于在命令行上选择构建器的值。

format = ''

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = []

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

class sphinx.builders.dummy.DummyBuilder

此构建器不生成任何输出。输入仅被解析并检查一致性。这对于代码检查很有用。

name = 'dummy'

构建器的名称。这是用于在命令行上选择构建器的值。

supported_image_types = []

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

版本 1.4 中新增。

class sphinx.builders.linkcheck.CheckExternalLinksBuilder

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

name = 'linkcheck'

构建器的名称。这是用于在命令行上选择构建器的值。

format = ''

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = []

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

版本 1.5 中的更改： 自 Sphinx 1.5 起，linkcheck 构建器使用 requests 模块。

版本 3.4 中的更改： 当服务器应用速率限制时，linkcheck 构建器会重试链接。

class sphinx.builders.xml.XMLBuilder

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

name = 'xml'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'xml'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = []

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

版本 1.2 中新增。

class sphinx.builders.xml.PseudoXMLBuilder

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

name = 'pseudoxml'

构建器的名称。这是用于在命令行上选择构建器的值。

format = 'pseudoxml'

构建器的输出格式，如果未生成文档输出，则为“”。这通常是文件扩展名，例如“html”，但接受任何字符串值。构建器的格式字符串可用于各种组件，例如SphinxPostTransform或扩展，以确定它们与构建器的兼容性。

supported_image_types = []

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

版本 1.2 中新增。

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

• doctest

• coverage

序列化构建器详细信息

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

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

每个源文件的文件具有out_suffix的扩展名，并像源文件一样排列在目录中。它们反序列化为一个字典（或类似字典的结构），具有以下键：

body

HTML“正文”（即源文件的 HTML 渲染），由 HTML 转换器渲染。

标题

文档标题，以 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

一个包含这些键的 pickle 字典

project、copyright、release、version

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

style

html_样式.

last_updated

上次构建日期。

builder

所用构建器的名称，对于 pickle 文件，始终为'pickle'。

titles

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

SerializingHTMLBuilder.searchindex_filename

一个可用于搜索文档的索引。它是一个包含以下条目的 pickle 列表

• 已索引文档名称的列表。

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

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

environment.pickle

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

与其他 pickle 文件不同，此 pickle 文件在反序列化时需要sphinx包可用。

上一页

配置

下一页

域