构建器

这些是内置的Sphinx构建器。可以通过 extensions 添加更多构建器。

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

最常用的构建器有：

html

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

dirhtml

构建 HTML 页面，每个文档生成一个单独的文件夹。通过网页服务器可以显示出更美观的 URL地址（可不显示 .html）。

singlehtml

使用整个内容生成单个 HTML 。

htmlhelp, qthelp, devhelp, epub

生成 HTML文件，其中包含以这些格式之一构建文档集合的附加信息。

applehelp

生成苹果帮助手册。需要 hiutil 和 codesign，它们不是开源的，目前仅适用于Mac OS X 10.6及更高版本。

latex

使用 pdflatex 生成可以编译为PDF文档的LaTeX源。

man

为 UNIX 系统生成 groff 格式的手册（man pages）。

texinfo

使用 makeinfo 生成可以被处理为 Info 文件的 Texinfo 文件。

text

生成纯文本文件。

gettext

生成 gettext 样式的文本集（.pot 格式）。

doctest

如果启动了 doctest 扩展程序，可运行文档中的所有文档测试。

linkcheck

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

xml

生成 Docutils 原生 XML 文件。

pseudoxml

生成简洁美观的“pseudo-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帮助研讨会将其编译为CHM文件。

name = 'htmlhelp'

构建器的名字。这是在命令行上选择构建器时使用的值。

format = 'html'

构建器的输出格式，如果不生成文档输出则为空字符串。通常是文件扩展名，比如"html"，但接受任何字符串值。可以被各种组件（如 SphinxPostTransform 或扩展）用来确定它们与构建器的兼容性。

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

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

class sphinxcontrib.qthelp.QtHelpBuilder[源代码]

此构建器生成与独立 HTML 构建器相同的输出，但也会生成 Qt help 集合支持文件，这些文件允许 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” 来禁用索引步骤，在这种情况下，输出将无效，直到 hiutil 已在捆绑包中的所有 .lproj 文件夹上运行。

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 （需要 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或更高（1月17日），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构建器。构建器的名字叫“里诺”。有关详细信息，请参阅 rinohtype manual。

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 格式是 gnuemacs 使用的在线帮助系统和基于终端的程序的基础 Info。详见 Texinfo信息。Texinfo 格式是 GNU 项目使用的官方文档系统。有关 Texinfo 的更多信息，请访问 https://www.gnu.org/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 serialization 格式的此构建器的具体子类可能如下所示：

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

包含“全局上下文”的文件的文件名。这是一个包含一些常规配置值的 dict，例如项目的名称。

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，搜索索引是 .searchpickle.

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 概述，用于当前 version。这对于生成更改日志文件非常有用，例如。

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“Reader to Transform to Writer” 管道。它生成紧凑的漂亮打印的“伪 XML”文件，其中嵌套由缩进表示（没有结束标记）。输出所有元素的外部属性，并给出任何剩余的“挂起”元素的内部属性。

name = 'pseudoxml'

构建器的名字。这是在命令行上选择构建器时使用的值。

format = 'pseudoxml'

构建器的输出格式，如果不生成文档输出则为空字符串。通常是文件扩展名，比如"html"，但接受任何字符串值。可以被各种组件（如 SphinxPostTransform 或扩展）用来确定它们与构建器的兼容性。

supported_image_types = []

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

在 1.2 版本加入.

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

序列化构建器详细信息

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

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

每个源文件的扩展名为 out_suffix，和在目录中的排列方式与源文件相同。它们使用以下键将非序列化为字典（或类似字典的结构）：

body

HTML“body”（即源文件的 HTML 呈现），由 HTML 转换器呈现。

title

文档的标题，如 HTML（可能包含标记）。

toc

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

display_toc

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

current_page_name

当前文件的文档名。

parents, prev and next

有关目录树中相关章节的信息。每个关系都是一个字典，其键为 link （表示关系的HREF）和 title （相关文档的标题，以 HTML形式）。parents 是一个关系列表，而 prev 和 next 是独立关系。

sourcename

“%u sources”下的源文件的名称。

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

SerializingHTMLBuilder.globalcontext_filename

一个带有以下键的 pickled dict：

project, copyright, release, version

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

style

html_style.

last_updated

最近一次构建的日期。

builder

使用的构建器的名称，如果是 pickle，则始终为 'pickle'。

titles

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

SerializingHTMLBuilder.searchindex_filename

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

  • 索引文档名的列表。

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

  • 将词根（由英语词干分析器处理）映射到整数列表的 dict，整数是第一个列表的索引。

environment.pickle

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

与其他 pickle 文件不同，这个 pickle 文件要求 sphinx 包在取消 pickle 时可用。