构建器

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

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

最常见的构建器是：

html

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

dirhtml

构建HTML页面，但每个文档有一个目录。 制作更漂亮的URL（否 .html ）如果从网络服务器提供服务。

singlehtml

用整个内容构建单个HTML。

htmlhelp , qthelp , devhelp , epub

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

applehelp

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

latex

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

man

以Groff格式为UNIX系统构建手册页面。

texinfo

构建可以使用将其处理为Info文件的Texinfo文件 makeinfo .

text

构建纯文本文件。

gettext

构建gettext风格的消息目录 (.pot 文件）。

doctest

如果 doctest 扩展已启用。

linkcheck

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

xml

构建Docutils原生的HTML文件。

pseudoxml

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

---

class sphinx.builders.html.StandaloneHTMLBuilder

这是标准的HTML构建器。 它的输出是一个包含HTML文件的目录，包含样式表和可选的reStructuredtext源。有相当多的配置值可以自定义此构建器的输出，请参阅章节 用于HTML输出的选项 有关详细信息

name: str = 'html'

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

format: str = 'html'

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

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: str = 'dirhtml'

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

format: str = 'html'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 0.6.

class sphinx.builders.singlehtml.SingleFileHTMLBuilder

这是一个将整个项目合并到一个输出文件中的HTML构建器。(显然，这只适用于较小的项目。)该文件的命名类似于根文档。不会生成任何索引。

name: str = 'singlehtml'

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

format: str = 'html'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 1.0.

class sphinxcontrib.htmlhelp.HTMLHelpBuilder

此生成器生成与独立的HTML生成器相同的输出，但还生成允许Microsoft HTML帮助工作室将其编译为CHM文件的HTML帮助支持文件。

name: str = 'htmlhelp'

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

format: str = 'html'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

class sphinxcontrib.qthelp.QtHelpBuilder

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

在 2.0 版本发生变更: 从sphinx.Builders包移动到sphinxcontri.qthelp。

name: str = 'qthelp'

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

format: str = 'html'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

class sphinxcontrib.applehelp.AppleHelpBuilder

该构建器基于与独立的HTML构建器相同的输出生成Apple Help Book。

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

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

name: str = 'applehelp'

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

format: str = 'html'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 1.3.

在 2.0 版本发生变更: 从sphinx.Builders包移至sphinxcontri.appleHelp。

class sphinxcontrib.devhelp.DevhelpBuilder

此构建器生成与独立的HTML构建器相同的输出，但还生成 GNOME Devhelp 支持文件，允许GNOME DevHelp阅读器查看它们。

name: str = 'devhelp'

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

format: str = 'html'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

在 2.0 版本发生变更: 从sphinx.Builders包移至sphinxcontri.devHelp。

class sphinx.builders.epub3.Epub3Builder

此生成器生成与独立的HTML生成器相同的输出，但也生成 epub 适合电子书读者的文件。 看到 EPUB信息 有关epub格式的定义，请参阅 https://idpf.org/epub 或 https://en.wikipedia.org/wiki/EPUB .构建器创建 EPUB 3 文件.

name: str = 'epub'

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

format: str = 'html'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 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 ，然后再来两个)。

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

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: str = 'latex'

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

format: str = 'latex'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

请注意，直接的PDF构建器由 rinohtype 。建造者的名字是 rinoh 。请参阅 rinohtype manual 了解更多细节。

class sphinx.builders.text.TextBuilder

此构建器为每个reStructuredText文件生成一个文本文件。这几乎与reStructuredText源代码相同，但为了更好的可读性，删除了许多标记。

name: str = 'text'

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

format: str = 'text'

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

supported_image_types: list[str] = []

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 0.4.

class sphinx.builders.manpage.ManualPageBuilder

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

name: str = 'man'

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

format: str = 'man'

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

supported_image_types: list[str] = []

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 1.0.

class sphinx.builders.texinfo.TexinfoBuilder

此构建器生成可由 makeinfo 程序。属性指定要包含在哪些文本信息文件中的文档。 texinfo_documents 配置值。

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

name: str = 'texinfo'

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

format: str = 'texinfo'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 1.1.

class sphinxcontrib.serializinghtml.SerializingHTMLBuilder

此构建器使用实现Python序列化API的模块 (pickle , simplejson , phpserialize ，和其他）来转储生成的HTML文档。 泡菜构建器是它的一个子集。

此生成器的一个具体子类序列化到 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

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

searchindex_filename

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

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

Added in version 0.5.

class sphinxcontrib.serializinghtml.PickleHTMLBuilder

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

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

name: str = 'pickle'

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

老名字 web 现在仍然有效。

format: str = 'html'

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

supported_image_types: list[str] = ['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: str = 'json'

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

format: str = 'html'

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

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

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

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

Added in version 0.5.

class sphinx.builders.gettext.MessageCatalogBuilder

该构建器生成getText样式的消息目录。每个顶级文件或子目录都会增长一个 .pot 元件库样板。

请参阅上的文档 国际化 以供进一步参考。

name: str = 'gettext'

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

format: str = ''

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

supported_image_types: list[str] = []

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 1.1.

class sphinx.builders.changes.ChangesBuilder

该生成器生成所有内容的HTML概述 versionadded , versionchanged , deprecated 和 versionremoved 当前指令 version . 例如，这对于生成更改日志文件很有用。

name: str = 'changes'

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

format: str = ''

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

supported_image_types: list[str] = []

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

class sphinx.builders.dummy.DummyBuilder

此构建器不产生任何输出。只对输入进行解析和一致性检查。这对于皮棉用途很有用。

name: str = 'dummy'

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

supported_image_types: list[str] = []

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 1.4.

class sphinx.builders.linkcheck.CheckExternalLinksBuilder

此构建器扫描所有文档中的外部链接，尝试使用 requests ，并编写了一个概述，其中哪些被破坏并被重定向到标准输出和 output.txt 在输出目录中。

name: str = 'linkcheck'

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

format: str = ''

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

supported_image_types: list[str] = []

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

在 1.5 版本发生变更: 从Sphinx 1.5开始，链接检查构建器使用请求模块。

在 3.4 版本发生变更: 当服务器应用速率限制时，链接检查构建器会重试链接。

class sphinx.builders.xml.XMLBuilder

该构建器生成Docutils原生XML文件。可以使用标准的XML工具(如XSLT处理程序)将输出转换为任意的最终形式。

name: str = 'xml'

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

format: str = 'xml'

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

supported_image_types: list[str] = []

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 1.2.

class sphinx.builders.xml.PseudoXMLBuilder

此构建器用于调试Sphinx/Docutils“Reader to Transform to Writer”管道。它生成紧凑、打印精美的“伪XML”文件，其中的嵌套由缩进表示(没有结束标记)。所有元素的外部属性都会被输出，任何剩余的“挂起”元素的内部属性也会被给出。

name: str = 'pseudoxml'

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

format: str = 'pseudoxml'

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

supported_image_types: list[str] = []

生成器支持的图像格式的MIME类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 1.2.

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

• doctest

• coverage

序列化构建器详细信息

所有序列化生成器每个源文件输出一个文件和一些特殊文件。 他们还将reStructuredtext源文件复制到 _sources 输出目录下的目录。

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

每个源文件的文件扩展名为 out_suffix ，并与源文件一样排列在目录中。它们使用以下键反序列化为字典(或类似字典的结构)：

body

由HTMLTranslator呈现的HTMLBody(即源文件的HTML化)。

title

文档的标题，如HTML(可以包含标记)。

toc

以HTML格式呈现的文件的目录 <ul> 。

display_toc

一个布尔值，即 True 如果 toc 包含多个条目。

current_page_name

当前文件的文档名称。

parents, prev and next

有关目录树中相关章节的信息。每个关系都是一本带有关键字的词典 link (关系的参考文献)和 title (相关文档的标题，如Html)。 parents 是关系的列表，而 prev 和 next 是一种单一的关系。

sourcename

下的源文件的名称 _sources 。

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

SerializingHTMLBuilder.globalcontext_filename

一份带有以下关键字的腌制词典：

project, copyright, release, version

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

style

html_style 。

last_updated

上次生成的日期。

builder

已用构建器的名称，对于泡菜，此名称始终为 'pickle' 。

titles

所有文档标题的词典，以HTML字符串的形式。

SerializingHTMLBuilder.searchindex_filename

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

• 已编制索引的文档名列表。

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

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

environment.pickle

生成环境。这始终是一个PICLE文件，独立于构建器以及在启动构建器时使用的环境的副本。

待处理

记录公共成员。

与其他Pickle文件不同，此Pickle文件要求 sphinx 包装在非酸洗时可用。

Previous

配置

Next

域