Builders

这些是内建的Sphinx建筑工人。更多的建筑商可以通过 extensions .

建造者的“名字”必须被赋予 -M 或 -b 命令行选项 sphinx-build 若要选择建造者，请执行以下操作。

最常见的建筑商有：

html

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

dirhtml

构建HTML页面，但每个文档只有一个目录。使URL更漂亮(否 .html )如果是从网络服务器提供的。

singlehtml

构建包含整个内容的单个HTML。

htmlhelp ， qthelp ， devhelp ， epub

使用附加信息生成HTML文件，以便以这些格式之一生成文档集合。

applehelp

创建一本苹果帮助书。要求 hiutil 和 codesign ，它们不是开源的，目前只在Mac OS X 10.6和更高版本上可用。

latex

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

man

为Unix系统构建Groff格式的手册页。

texinfo

使用构建可处理为Info文件的纹理信息文件 makeinfo 。

text

构建纯文本文件。

gettext

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

doctest

运行文档中的所有文档测试，如果 doctest 扩展已启用。

linkcheck

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

xml

构建Docutils-原生XML文件。

pseudoxml

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

class sphinx.builders.html.StandaloneHTMLBuilder[源代码]

这是标准的HTML生成器。它的输出是一个包含HTML文件的目录，包括样式表和可选的其余源文件。有相当多的配置值可自定义此生成器的输出，请参见本章 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 放在一个名为page name的子目录中。例如，文档 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类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 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类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 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 help 允许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类型列表。图像文件按其在此处显示的顺序进行搜索。

Added in version 1.3.

在 2.0 版本发生变更: 从sphinx.builders包移到sphinxcontrib.applehelp。

class sphinxcontrib.devhelp.DevhelpBuilder[源代码]

此生成器生成与独立HTML生成器相同的输出，但也生成 GNOME Devhelp 支持允许gnome devhelp reader查看它们的文件。

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类型列表。图像文件按其在此处显示的顺序进行搜索。

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

  • tex-gyre (如果 latex_engine 左至默认)

  • texlive-latex-extra

  • latexmk

在 4.0.0 版本发生变更: 现在需要Tex Gyre字体 'pdflatex' 引擎(默认)。

在某些情况下需要额外的程序包：

  • 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" 通过Xeletex加速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类型列表。图像文件按其在此处显示的顺序进行搜索。

请注意，直接PDF生成器由 rinohtype . 建筑商的名字是 rinoh . 参考 rinohtype manual 有关详细信息。

class sphinx.builders.text.TextBuilder[源代码]

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

name = 'text'

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

format = 'text'

生成器的输出格式，如果没有生成文档输出，则为“”。

supported_image_types: list[str] = []

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

Added in version 0.4.

class sphinx.builders.manpage.ManualPageBuilder[源代码]

此生成器以groff格式生成手动页面。您必须通过 man_pages 配置值。

name = 'man'

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

format = 'man'

生成器的输出格式，如果没有生成文档输出，则为“”。

supported_image_types: list[str] = []

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

Added in version 1.0.

class sphinx.builders.texinfo.TexinfoBuilder[源代码]

此生成器生成Texinfo文件，可由 makeinfo 程序。您必须指定哪些文档将包含在通过 texinfo_documents 配置值。

信息格式是GNU Emacs使用的在线帮助系统和基于终端的程序的基础。 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类型列表。图像文件按其在此处显示的顺序进行搜索。

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

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

searchindex_filename

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

见 序列化生成器详细信息 有关输出格式的详细信息。

Added in version 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[源代码]

这个生成器生成一个包含JSON文件的目录，其中大部分包含HTML片段和TOC信息，用于不使用标准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 .

Added in version 0.5.

class sphinx.builders.gettext.MessageCatalogBuilder[源代码]

此生成器生成GetText样式的消息目录。每个顶级文件或子目录增长一个 .pot 目录模板。

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

name = 'gettext'

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

format = ''

生成器的输出格式，如果没有生成文档输出，则为“”。

supported_image_types: list[str] = []

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

Added in version 1.1.

class sphinx.builders.changes.ChangesBuilder[源代码]

此构建器生成所有 versionadded ， versionchanged ， deprecated 和 versionremoved 针对当前的 version 。例如，这对于生成ChangeLog文件很有用。

name = 'changes'

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

format = ''

生成器的输出格式，如果没有生成文档输出，则为“”。

supported_image_types: list[str] = []

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

class sphinx.builders.dummy.DummyBuilder[源代码]

此生成器不生成输出。只分析和检查输入的一致性。这对于起毛很有用。

name = 'dummy'

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

supported_image_types: list[str] = []

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

Added in version 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开始，链接检查构建器使用请求模块。

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

class sphinx.builders.xml.XMLBuilder[源代码]

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

name = 'xml'

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

format = 'xml'

生成器的输出格式，如果没有生成文档输出，则为“”。

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 = 'pseudoxml'

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

format = 'pseudoxml'

生成器的输出格式，如果没有生成文档输出，则为“”。

supported_image_types: list[str] = []

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

Added in version 1.2.

提供更多建筑商的内置Sphinx扩展包括：

序列化生成器详细信息

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

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

每个源文件的扩展名为 out_suffix 和在目录中排列，就像源文件一样。它们使用以下键取消对字典（或类似字典的结构）的序列化：

body

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

title

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

toc

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

display_toc

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

current_page_name

当前文件的文档名。

parents, prev and 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' .

titles

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

SerializingHTMLBuilder.searchindex_filename

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

  • 索引文档名列表。

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

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

environment.pickle

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

待处理

记录普通成员。

与其他pickle文件不同，此pickle文件需要 sphinx 拆下包装即可使用。