生成器¶

这些是内置的Sphinx生成器。可以通过 :doc:`扩展 </usage/extensions/index>`添加更多生成器。

The builder’s “name” must be given to the -M or -b command-line options of sphinx-build to select a builder.

The most common builders are:

html: 生成 HTML 页面。这是默认的生成器。
dirhtml: 构建 HTML 页面，每个文档生成一个单独的文件夹。通过网页服务器可以显示出更好看的 URL（可以不显示.html）。
singlehtml: 使用整个内容生成单个 HTML 。
htmlhelp, qthelp, devhelp, epub: 生成 HTML文件，其中包含以这些格式之一构建文档集合的附加信息。
applehelp: 生成一本苹果帮助手册。需要 hiutil’和 codesign，它们不是开源的，目前仅适用于Mac OS X 10.6及更高版本。
latex: 使用 :program:`pdflatex`生成可以编译为PDF文档的LaTeX源。
man: 为 UNIX 系统生成 groff 格式的手册（man pages）。
texinfo: 使用 :program:`makeinfo`生成可以被处理为 Info 文件的 Texinfo 文件。
text: 生成纯文本文件。
gettext: 生成 gettext 样式的文本集（“.pot”格式）。
doctest: 如果启动了 doctest 扩展程序，可运行文档中的所有文档测试。
linkcheck: 检查所有外部链接的完整性。
xml: 生成 Docutils 原生 XML 文件。
pseudoxml: 生成简洁美观的“pseudo-XML”格式文件，显示中间文档树的内部结构。

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

这是标准的HTML生成器。它的输出是一个包含HTML文件的目录，包括样式表和可选的reST源。有很多配置值可以自定义此生成器的输出，有关详细信息，请参阅章节：ref:`html options’。

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文件的目录，其中每个文件都被调用``索引.html``并放在一个名为其页面名的子目录中。例如，文档标记/休息.rst``不会产生输出文件``标记/休息.html``，但``标记/休息/索引.html``. 在页面之间生成链接时``索引.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[源代码]¶

This is an HTML builder that combines the whole project in one output file. (Obviously this only works with smaller projects.) The file is named like the root document. No indices will be generated.

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.生成器包移到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` 文件夹，则与所选语言对应的文件夹的内容将与生成的输出合并。这些文件夹将被所有其他文档类型忽略。

为了生成有效的帮助手册，此生成器需要命令行工具：program:hiutil，该工具仅在 Mac OS X 10.6 及更高版本上可用。可以通过将 confval:applehelp_disable_external_tools 设置为 “True” 来禁用索引步骤，在这种情况下，输出将无效，直到：program: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.生成器包移到sphinxcontrib.applehelp。

class sphinxcontrib.devhelp.DevhelpBuilder[源代码]¶

此生成器生成与独立 HTML 生成器相同的输出，但也生成 “GNOME Devhelp”<https://wiki.gnome.org/Apps/Devhelp>`__允许 GNOME Devhelp 阅读器查看它们的支持文件

name = 'devhelp'¶: 编译器的名称，用于-b命令行选项。

format = 'html'¶: 生成器的输出格式，如果未生成文档输出，则为“”。

supported_image_types: list[str] = ['image/png', 'image/gif', 'image/jpeg']¶: 生成器支持的图像格式的MIME类型列表。图像文件按它们在此处出现的顺序进行搜索。

在 2.0 版本发生变更: 从sphinx.生成器包移到sphinxcontrib.devhelp。

class sphinx.builders.epub3.Epub3Builder[源代码]¶

This builder produces the same output as the standalone HTML builder, but also generates an epub file for ebook readers. See Epub信息 for details about it. For definition of the epub format, have a look at https://idpf.org/epub or https://en.wikipedia.org/wiki/EPUB. The builder creates EPUB 3 files.

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 版本发生变更: Since Sphinx 1.5, the epub3 builder is used as the default epub builder.

class sphinx.builders.latex.LaTeXBuilder[源代码]¶

This builder produces LaTeX source files in the output directory. The actual PDF builds happen inside this output directory and need to be triggered in a second step. This can be done via make all-pdf there. To combine the two steps into only one, use sphinx-build -M (i.e. -M latexpdf not -b latexpdf) or make latexpdf at the project root.

See latex_documents and the chapter LaTeX输出的选项 for available options.

PDF builds need a sufficiently complete LaTeX installation. The testing is currently (since 5.3.0) done on Ubuntu 22.04LTS, whose LaTeX distribution matches upstream TeXLive 2021 as of 2022/02/04, but PDF builds can be successfully done on much older LaTeX installations.

At any rate, on Ubuntu for example, following packages must all be present:

texlive-latex-recommended
texlive-fonts-recommended
tex-gyre (if latex_engine left to default)
texlive-latex-extra
latexmk

在 4.0.0 版本发生变更: TeX Gyre fonts now required for 'pdflatex' engine (default).

Additional packages are needed in some circumstances:

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 如果 latex_engine 是 'xelatex'，
texlive-luatex 如果 latex_engine 是 'lualatex'，
fonts-freefont-otf if latex_engine is either 'xelatex' or 'lualatex'.

备注

Since 1.6, make latexpdf uses on GNU/Linux and macOS latexmk, as it makes sure the needed number of runs is automatically executed. On Windows the PDF builds execute a fix number of LaTeX runs (three, then makeindex, then two more).

可以通过 “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'¶: 编译器的名称，用于-b命令行选项。

format = 'latex'¶: 生成器的输出格式，如果未生成文档输出，则为“”。

supported_image_types: list[str] = ['application/pdf', 'image/png', 'image/jpeg']¶: 生成器支持的图像格式的MIME类型列表。图像文件按它们在此处出现的顺序进行搜索。

请注意，“rinohtype” 正在提供一个直接的PDF构建器。建筑商的名字叫“里诺”。有关详细信息，请参阅 “rinohtype 手册”。

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 格式生成手册页。您必须通过：confval:man_pages 配置值指定哪些文档要包含在哪些手册页中。

name = 'man'¶: 编译器的名称，用于-b命令行选项。

format = 'man'¶: 生成器的输出格式，如果未生成文档输出，则为“”。

supported_image_types: list[str] = []¶: 生成器支持的图像格式的MIME类型列表。图像文件按它们在此处出现的顺序进行搜索。

Added in version 1.0.

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

此生成器生成 Texinfo 文件，这些文件可以由：program:makeinfo 程序处理为 Info 文件。您必须通过：confval:Texinfo_documents 配置值指定哪些Texinfo文件要包含在哪些文档。

Info 格式是 gnuemacs 使用的在线帮助系统和基于终端的程序的基础：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[源代码]¶

This builder uses a module that implements the Python serialization API (pickle, simplejson, phpserialize, and others) to dump the generated HTML documentation. The pickle builder is a subclass of it.

序列化为 “PHP serialization” 格式的此生成器的具体子类可能如下所示：

import phpserialize

class PHPSerializedBuilder(SerializingHTMLBuilder):
    name = 'phpserialized'
    implementation = phpserialize
    out_suffix = '.file.phpdump'
    globalcontext_filename = 'globalcontext.phpdump'
    searchindex_filename = 'searchindex.phpdump'

implementation¶: A module that implements dump(), load(), dumps() and loads() functions that conform to the functions with the same names from the pickle module. Known modules implementing this interface are simplejson, phpserialize, plistlib, and others.

out_suffix¶: 所有常规文件的后缀。

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

searchindex_filename¶: Sphinx 生成的搜索索引的文件名。

有关输出格式的详细信息，请参见：ref:`serialization details’。

Added in version 0.5.

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

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

有关输出格式的详细信息，请参见：ref:`serialization details’。

name = 'pickle'¶

编译器的名称，用于-b命令行选项。

旧名 “web” 仍然有效。

format = 'html'¶: 生成器的输出格式，如果未生成文档输出，则为“”。

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: 生成器支持的图像格式的MIME类型列表。图像文件按它们在此处出现的顺序进行搜索。

文件后缀为 “.fpickle”。全局上下文为“globalcontext.pickle”，搜索索引是“.searchpickle”.

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

这个生成器生成一个包含 JSON 文件的目录，其中大部分包含 HTML 片段和 TOC 信息，以供不使用标准 HTML 模板的 web 应用程序（或自定义后处理工具）使用。

有关输出格式的详细信息，请参见：ref:`serialization details’。

name = 'json'¶: 编译器的名称，用于-b命令行选项。

format = 'html'¶: 生成器的输出格式，如果未生成文档输出，则为“”。

supported_image_types: list[str] = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg']¶: 生成器支持的图像格式的MIME类型列表。图像文件按它们在此处出现的顺序进行搜索。

文件后缀为 “.fpickle”。全局上下文为“globalcontext.pickle”，搜索索引是“.searchpickle”.

Added in version 0.5.

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

此生成器生成 gettext 样式的消息目录。每个顶级文件或子目录都会增长一个单独的“.pot” 目录模板。

有关进一步参考，请参阅以下文档：ref:`intl’。

name = 'gettext'¶: 编译器的名称，用于-b命令行选项。

format = ''¶: 生成器的输出格式，如果未生成文档输出，则为“”。

supported_image_types: list[str] = []¶: 生成器支持的图像格式的MIME类型列表。图像文件按它们在此处出现的顺序进行搜索。

Added in version 1.1.

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

This builder produces an HTML overview of all versionadded, versionchanged, deprecated and versionremoved directives for the current version. This is useful to generate a changelog file, for example.

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

此生成器扫描所有文档以查找外部链接，尝试使用“请求”打开它们，并编写一个概述，其中哪些链接已断开并重定向到标准输出和：file:输出 .txt 在输出目录中。

name = 'linkcheck'¶: 编译器的名称，用于-b命令行选项。

format = ''¶: 生成器的输出格式，如果未生成文档输出，则为“”。

supported_image_types: list[str] = []¶: 生成器支持的图像格式的MIME类型列表。图像文件按它们在此处出现的顺序进行搜索。

在 1.5 版本发生变更: Since Sphinx 1.5, the linkcheck builder uses the requests module.

在 3.4 版本发生变更: The linkcheck builder retries links when servers apply rate limits.

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 扩展包括：

序列化生成器详细信息¶

所有序列化生成器为每个源文件输出一个文件和一些特殊文件。它们还将其余源文件复制到输出目录下的 “u sources” 目录中。

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

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

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”下的源文件的名称。

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

：属性：.Serializingtmlbuilder.globalcontext_文件名

用这些键腌制的 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 时可用。

Sphinx

On this page

Site navigation

生成器¶

序列化生成器详细信息¶