建筑商

这些是内置的狮身人面像构建器。可以通过以下方式添加更多构建器 extensions

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

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

这是标准的HTML构建器。它的输出是一个包含HTML文件的目录,其中包括样式表和REST源代码(可选)。有相当多的配置值可以自定义此构建器的输出,请参阅一章 用于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类型列表。图像文件按其在此处显示的顺序进行搜索。

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

在 1.0 版本加入.

class sphinxcontrib.htmlhelp.HTMLHelpBuilder[源代码]

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

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包移动到sphinxcontri.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_toolsTrue ,在这种情况下,输出将在 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类型列表。图像文件按其在此处显示的顺序进行搜索。

在 1.3 版本加入.

在 2.0 版本发生变更: 从sphinx.Builders包移至sphinxcontri.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包移至sphinxcontri.devHelp。

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

此生成器生成与独立的HTML生成器相同的输出,但还生成 epub 适用于电子书读者的文件。看见 EPUB信息 关于它的详细信息。有关epub格式的定义,请查看 http://idpf.org/epubhttps://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类型列表。图像文件按其在此处显示的顺序进行搜索。

在 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" 在包含大量图形的情况下,通过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类型列表。图像文件按其在此处显示的顺序进行搜索。

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

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

该构建器为每个REST文件生成一个文本文件--这与REST源代码几乎相同,但为了更好的可读性,去掉了大部分标记。

name = 'text'

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

format = 'text'

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

supported_image_types: list[str] = []

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

在 0.4 版本加入.

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

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

name = 'man'

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

format = 'man'

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

supported_image_types: list[str] = []

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

在 1.0 版本加入.

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

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

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

name = 'texinfo'

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

format = 'texinfo'

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

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

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

在 1.1 版本加入.

class sphinxcontrib.serializinghtml.SerializingHTMLBuilder[源代码]

此构建器使用实现Python序列化API的模块 (picklesimplejsonphpserialize 等)来转储生成的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模块中的同名函数一致的函数。实现此接口的已知模块有 simplejsonphpserializeplistlib ,以及其他。

out_suffix

所有常规文件的后缀。

globalcontext_filename

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

searchindex_filename

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

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

在 0.5 版本加入.

class sphinxcontrib.serializinghtml.PickleHTMLBuilder[源代码]

这个构建器生成一个目录,其中包含主要包含HTML片段和TOC信息的Pickle文件,以供不使用标准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

在 0.5 版本加入.

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

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

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

name = 'gettext'

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

format = ''

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

supported_image_types: list[str] = []

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

在 1.1 版本加入.

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

此构建器生成所有 versionaddedversionchangeddeprecated 针对当前的 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类型列表。图像文件按其在此处显示的顺序进行搜索。

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

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

在 1.2 版本加入.

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

序列化构建器详细信息

所有序列化构建器都为每个源文件输出一个文件和几个特殊文件。它们还复制目录中的REST源文件 _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 是关系的列表,而 prevnext 是一种单一的关系。

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 包装在非酸洗时可用。