构建器¶

这些是内置的 Sphinx 构建器.可以通过扩展添加更多构建器.

构建器的 “name “ 必须被指定为 sphinx-build 的 -M 或 -b 命令行选项,以选择一个构建器.

最常见的构建器有:

html: 构建HTML页面.这是默认的构建器.
dirhtml: 构建HTML页面,但每个文档只用一个目录.如果通过网络服务器提供,这样的网址会更美观（没有 .html ）.
单页 HTML: 构建一个包含所有内容的单个HTML.
htmlhelp, qthelp, devhelp, epub: 使用额外信息构建 HTML 文件,以便以这些格式之一构建文档集合.
苹果帮助: 构建一个 Apple 帮助书.需要 hiutil 和 codesign ,这些不是开源软件,目前仅在 Mac OS X 10.6 及更高版本中可用.
LaTeX: 构建可以使用 pdflatex 编译为 PDF 文档的 LaTeX 源文件.
手册: 为UNIX系统生成groff格式的手册页.
Texinfo: 生成可以使用 makeinfo 处理为 Info 文件的 Texinfo 文件.
文本: 生成纯文本文件.
gettext: 构建gettext风格的消息目录（ .pot 文件）.
文档测试: 在文档中运行所有的 doctest,如果启用了 doctest 扩展.
链接检查: 检查所有外部链接的完整性.
xml: 构建 Docutils 原生 XML 文件.
伪XML: 生成紧凑且美观的”伪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类型列表.图像文件的搜索顺序是按照它们在此处出现的顺序.

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 Help Book.

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

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

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 阅读器能够查看它们.

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.04 LTS 上进行,其 LaTeX 发行版与 2022/02/04 的 TeXLive 2021 相匹配,但 PDF 构建可以在许多较旧的 LaTeX 安装上成功完成.

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

texlive-latex-recommended
texlive-fonts-recommended
texlive-fonts-extra (needed for fontawesome5, see the 7.4.0 change notice below)
tex-gyre (if latex_engine left to default)
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 for Cyrillic (and also then cm-super if using the default fonts),
texlive-lang-greek for Greek (and also then cm-super if using the default fonts),
texlive-xetex if latex_engine is 'xelatex',
texlive-luatex if latex_engine is 'lualatex',
fonts-freefont-otf if latex_engine is either 'xelatex' or '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类型列表.图像文件的搜索顺序是按照它们在此处出现的顺序.

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[源代码]¶

该构建器生成可以通过:program:makeinfo 程序处理成 Info 文件的 Texinfo 文件.您必须通过 texinfo_documents 配置值指定哪些文档应包含在哪些 Texinfo 文件中.

Info格式是GNU Emacs和基于终端的程序:program:info 所使用的在线帮助系统的基础.有关更多细节,请参见:ref:texinfo-faq .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文档.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生成的搜索索引的文件名.

有关输出格式的详细信息,请参见序列化构建器详情 .

Added in version 0.5.

class sphinxcontrib.serializinghtml.PickleHTMLBuilder[源代码]¶

这个构建器生成一个目录,其中包含主要是HTML片段和目录信息的pickle文件,供不使用标准HTML模板的网络应用程序（或自定义后处理工具）使用.

有关输出格式的详细信息,请参见序列化构建器详情 .

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片段和目录信息的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 .

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[源代码]¶

此构建器生成当前 version 的所有 versionadded 、versionchanged 、deprecated 和 versionremoved 指令的 HTML 概览.这对于生成变更日志文件非常有用.

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类型列表.图像文件的搜索顺序是按照它们在此处出现的顺序.

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 以来,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类型列表.图像文件的搜索顺序是按照它们在此处出现的顺序.

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扩展提供更多构建器的是:

序列化构建器详情¶

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

The PickleHTMLBuilder is a builtin subclass that implements the pickle serialization interface.

每个源文件的文件扩展名为 out_suffix ,并且它们按照源文件的目录结构排列.它们会反序列化为一个字典（或类似字典的结构）,包含以下键:

body: HTML “body”（即源文件的HTML渲染）,由HTML翻译器渲染.
title: 文档的标题,作为HTML（可能包含标记）.
toc: 文件的目录,以HTML <ul> 格式呈现.
display_toc: 一个布尔值,如果 toc 包含多个条目,则为 True .
current_page_name: 当前文件的文档名称.
parents, prev and next: 有关TOC树中相关章节的信息.每个关系都是一个字典,包含键 link （关系的HREF）和 title （相关文档的标题,作为HTML）. parents 是关系的列表,而 prev 和 next 是一个单一关系.
sourcename: The name of the source file under _sources.

特殊文件位于根输出目录中.它们是:

SerializingHTMLBuilder.globalcontext_filename

一个包含以下键的pickle字典:

project, copyright, release, version: 与配置文件中提供的值相同.
style: html_style .
last_updated: 最后构建日期.
builder: 用于的构建器名称,在使用 pickles 的情况下,这始终是 'pickle' .
titles: 所有文档标题的字典,以HTML字符串形式表示.

SerializingHTMLBuilder.searchindex_filename

可用于搜索文档的索引.它是一个经过序列化的列表,包含以下条目:

已索引文档名称的列表.
文档标题的列表,作为HTML字符串,顺序与第一个列表相同.
一个字典,将单词根（经过英语词干提取器处理）映射到整数列表,这些整数是第一个列表中的索引.

environment.pickle

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

待处理

文档公共成员.

与其他pickle文件不同,此pickle文件在反序列化时需要 sphinx 包的支持.