建筑商¶
这些是内置的狮身人面像构建器。可以通过以下方式添加更多构建器 extensions 。
建造者的“名字”必须被赋予 -b 命令行选项 sphinx-build 若要选择建造者,请执行以下操作。
- class sphinx.builders.html.StandaloneHTMLBuilder[源代码]¶
这是标准的HTML构建器。它的输出是一个包含HTML文件的目录,其中包括样式表和REST源代码(可选)。有相当多的配置值可以自定义此构建器的输出,请参阅一章 用于HTML输出的选项 了解更多细节。
- name = 'html'¶
构建器的名称,用于-b命令行选项。
- format = 'html'¶
生成器的输出格式,如果没有生成文档输出,则为“”。
- 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'¶
生成器的输出格式,如果没有生成文档输出,则为“”。
- class sphinxcontrib.qthelp.QtHelpBuilder[源代码]¶
此构建器生成与独立的HTML构建器相同的输出,但还生成 Qt help 允许Qt集合生成器编译它们的集合支持文件。
在 2.0 版本发生变更: 从sphinx.Builders包移动到sphinxcontri.qthelp。
- name = 'qthelp'¶
构建器的名称,用于-b命令行选项。
- format = 'html'¶
生成器的输出格式,如果没有生成文档输出,则为“”。
- class sphinxcontrib.applehelp.AppleHelpBuilder[源代码]¶
该构建器基于与独立的HTML构建器相同的输出生成Apple Help Book。
如果源目录包含任何
.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类型列表。图像文件按其在此处显示的顺序进行搜索。
在 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/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类型列表。图像文件按其在此处显示的顺序进行搜索。
在 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'¶
生成器的输出格式,如果没有生成文档输出,则为“”。
请注意,直接的PDF构建器由 rinohtype 。建造者的名字是 rinoh
。请参阅 rinohtype manual 了解更多细节。
- class sphinx.builders.text.TextBuilder[源代码]¶
该构建器为每个REST文件生成一个文本文件--这与REST源代码几乎相同,但为了更好的可读性,去掉了大部分标记。
- name = 'text'¶
构建器的名称,用于-b命令行选项。
- format = 'text'¶
生成器的输出格式,如果没有生成文档输出,则为“”。
在 0.4 版本加入.
- class sphinx.builders.manpage.ManualPageBuilder[源代码]¶
该构建器生成Groff格式的手册页。您必须通过指定哪些文档包含在哪些手册页中
man_pages
配置值。- name = 'man'¶
构建器的名称,用于-b命令行选项。
- format = 'man'¶
生成器的输出格式,如果没有生成文档输出,则为“”。
在 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的模块 (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生成的搜索索引的文件名。
看见 序列化构建器详细信息 有关输出格式的详细信息,请参阅。
在 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 = ''¶
生成器的输出格式,如果没有生成文档输出,则为“”。
在 1.1 版本加入.
- class sphinx.builders.changes.ChangesBuilder[源代码]¶
此构建器生成所有
versionadded
,versionchanged
和deprecated
针对当前的version
。例如,这对于生成ChangeLog文件很有用。- name = 'changes'¶
构建器的名称,用于-b命令行选项。
- format = ''¶
生成器的输出格式,如果没有生成文档输出,则为“”。
- class sphinx.builders.dummy.DummyBuilder[源代码]¶
此构建器不产生任何输出。只对输入进行解析和一致性检查。这对于皮棉用途很有用。
- name = 'dummy'¶
构建器的名称,用于-b命令行选项。
在 1.4 版本加入.
- class sphinx.builders.linkcheck.CheckExternalLinksBuilder[源代码]¶
此构建器扫描所有文档中的外部链接,尝试使用
requests
,并编写了一个概述,其中哪些被破坏并被重定向到标准输出和output.txt
在输出目录中。- name = 'linkcheck'¶
构建器的名称,用于-b命令行选项。
- format = ''¶
生成器的输出格式,如果没有生成文档输出,则为“”。
在 1.5 版本发生变更: 从Sphinx 1.5开始,链接检查构建器使用请求模块。
在 3.4 版本发生变更: 当服务器应用速率限制时,链接检查构建器会重试链接。
- class sphinx.builders.xml.XMLBuilder[源代码]¶
该构建器生成Docutils原生XML文件。可以使用标准的XML工具(如XSLT处理程序)将输出转换为任意的最终形式。
- name = 'xml'¶
构建器的名称,用于-b命令行选项。
- format = 'xml'¶
生成器的输出格式,如果没有生成文档输出,则为“”。
在 1.2 版本加入.
- class sphinx.builders.xml.PseudoXMLBuilder[源代码]¶
此构建器用于调试Sphinx/Docutils“Reader to Transform to Writer”管道。它生成紧凑、打印精美的“伪XML”文件,其中的嵌套由缩进表示(没有结束标记)。所有元素的外部属性都会被输出,任何剩余的“挂起”元素的内部属性也会被给出。
- name = 'pseudoxml'¶
构建器的名称,用于-b命令行选项。
- format = 'pseudoxml'¶
生成器的输出格式,如果没有生成文档输出,则为“”。
在 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
andnext
有关目录树中相关章节的信息。每个关系都是一本带有关键字的词典
link
(关系的参考文献)和title
(相关文档的标题,如Html)。parents
是关系的列表,而prev
和next
是一种单一的关系。sourcename
下的源文件的名称
_sources
。
特殊文件位于根输出目录中。它们是:
SerializingHTMLBuilder.globalcontext_filename
一份带有以下关键字的腌制词典:
project
,copyright
,release
,version
与配置文件中给出的值相同。
style
last_updated
上次生成的日期。
builder
已用构建器的名称,对于泡菜,此名称始终为
'pickle'
。titles
所有文档标题的词典,以HTML字符串的形式。
SerializingHTMLBuilder.searchindex_filename
可用于搜索文档的索引。这是一个包含以下条目的腌制列表:
已编制索引的文档名列表。
文档标题的列表,以与第一个列表相同的顺序显示为HTML字符串。
将词根(由英语词干分析器处理)映射到整数列表的词典,整数列表是第一个列表的索引。
environment.pickle
生成环境。这始终是一个PICLE文件,独立于构建器以及在启动构建器时使用的环境的副本。
待处理
记录公共成员。
与其他Pickle文件不同,此Pickle文件要求
sphinx
包装在非酸洗时可用。