配置¶

这个 configuration directory 必须包含名为的文件 conf.py . 这个文件（包含python代码）称为“构建配置文件”，包含（几乎）自定义sphinx输入和输出行为所需的所有配置。

可选文件 docutils.conf 可以添加到配置目录以进行调整 Docutils 配置，如果不是由Sphinx重写或设置。

配置文件在构建时以Python代码的形式执行(使用 importlib.import_module() 并将当前目录设置为其包含的目录)，因此可以执行任意复杂的代码。然后，Sphinx从文件的名称空间中读取简单名称作为其配置。

需要注意的要点：

如果没有其他文档记录，则值必须是字符串，其默认值是空字符串。
术语“完全限定名”是指命名模块内可导入的python对象的字符串；例如，fqn "sphinx.builders.Builder" 意味着 Builder 类中 sphinx.builders 模块。
记住文档名称使用 / 作为路径分隔符，不包含文件扩展名。
自从 conf.py 作为一个python文件读取，通常的规则适用于编码和Unicode支持。
配置命名空间的内容被pickled（以便sphinx可以在配置更改时找到），因此它可能不包含不可识别的值——使用 del 如果合适的话。模块会自动删除，因此您不需要 del 使用后进口。
有一个特殊的对象名为 tags 在配置文件中可用。它可用于查询和更改标记（请参见包括基于标记的内容）使用 tags.has('tag') 查询， tags.add('tag') 和 tags.remove('tag') 改变。仅通过设置标签 -t 命令行选项或通过 tags.add('tag') 可以使用查询 tags.has('tag') . 请注意，当前的builder标记在 conf.py ，创建时之后生成器已初始化。

项目信息¶

project¶: 记录的项目名称。

author¶: 文档的作者姓名。默认值为 'unknown' .

copyright¶: 样式中的版权声明 '2008, Author Name' .

在 7.1 版本发生变更: 该值现在可以是上述形式的版权声明序列，这些声明将分别显示在各自的行中。

project_copyright¶: 的别名 copyright 。

Added in version 3.5.

version¶: 主要项目版本，用作 |version| . 例如，对于Python文档，这可能是 2.6 .

release¶

完整的项目版本，用作 |release| 例如，在HTML模板中。例如，对于Python文档，这可能是 2.6.0rc1 .

如果你不需要在 version 和 release ，只需将它们都设置为相同的值。

一般配置¶

extensions¶

作为模块名称的字符串列表 extensions . 这些可以是Sphinx的扩展名 sphinx.ext.* ）或者定制的。

请注意，您可以扩展 sys.path 在conf文件中，如果扩展名位于另一个目录中，请确保使用绝对路径。如果扩展路径相对于 configuration directory 使用 os.path.abspath() 像这样：：

import sys, os

sys.path.append(os.path.abspath('sphinxext'))

extensions = ['extname']

这样，您就可以加载一个名为 extname 从子目录 sphinxext .

配置文件本身可以是扩展名；为此，您只需提供 setup() 在其中起作用。

source_suffix¶

源文件的文件扩展名。sphinx将带有此后缀的文件视为源文件。该值可以是将文件扩展名映射到文件类型的字典。例如：：

source_suffix = {
    '.rst': 'restructuredtext',
    '.txt': 'restructuredtext',
    '.md': 'markdown',
}

默认情况下，Sphinx仅支持 'restructuredtext' 文件类型。可以使用源分析器扩展名添加新的文件类型。请阅读扩展名的文档以了解扩展名支持的文件类型。

该值也可以是文件扩展名列表：然后sphinx会认为它们都映射到 'restructuredtext' 文件类型。

{{'.rst': 'restructuredtext'}} .

备注

文件扩展名必须以点开头（例如 .rst ）

在 1.3 版本发生变更: 现在可以是扩展名列表。

在 1.8 版本发生变更: 支持文件类型映射

source_encoding¶: 所有REST源文件的编码。建议的编码和默认值是 'utf-8-sig' .

Added in version 0.5: 以前，Sphinx只接受UTF-8编码源。

source_parsers¶

如果给定的话，一个针对不同源的解析器类字典就足够了。键是后缀，值可以是类，也可以是字符串，给出解析器类的完全限定名。解析器类可以是 docutils.parsers.Parser 或 sphinx.parsers.Parser . 后缀不在字典中的文件将使用默认的RestructedText分析器进行分析。

例如：：

source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}

备注

参照 Markdown 有关使用Sphinx标记的更多信息。

Added in version 1.3.

自 1.8 版本弃用: 现在Sphinx提供了一个API Sphinx.add_source_parser() 注册源解析器。请改用它。

master_doc¶: 相同于 root_doc 。

在 4.0 版本发生变更: 已重命名 master_doc 至 root_doc 。

root_doc¶: 根文档的文档名，即包含根的文档 toctree 指令。缺省值为 'index' 。

在 2.0 版本发生变更: 默认值更改为 'index' 从 'contents' .

在 4.0 版本发生变更: 已重命名 root_doc 从… master_doc 。

exclude_patterns¶

GLOB样式模式的列表 [1] 在查找源文件时应将其排除。它们与相对于源目录的源文件名匹配，在所有平台上都使用斜杠作为目录分隔符。

示例模式：

'library/xml.rst' --忽略 library/xml.rst 文件
'library/xml' --忽视 library/xml 目录
'library/xml*' -- ignores all files and directories starting with library/xml
'**/.svn' --忽略一切 .svn 目录

exclude_patterns 在中查找静态文件时也会参考 html_static_path 和 html_extra_path .

Added in version 1.0.

include_patterns¶

GLOB样式模式的列表 [1] 用于查找源文件的。它们与相对于源目录的源文件名匹配，在所有平台上都使用斜杠作为目录分隔符。缺省值为 ** 这意味着所有文件都是从源目录递归包含的。 exclude_patterns 优先于 include_patterns 。

示例模式：

'**' --源目录和子目录中的所有文件，递归
'library/xml' --只有 library/xml 目录
'library/xml*' -- all files and directories starting with library/xml
'**/doc' --全部 doc 目录(如果文档与源文件位于同一位置，这可能很有用)

Added in version 5.1.

templates_path¶: 包含额外模板（或覆盖内置/主题特定模板的模板）的路径列表。相对路径被视为相对于配置目录的路径。

在 1.3 版本发生变更: 由于这些文件不是要生成的，因此它们会自动添加到 exclude_patterns .

template_bridge¶: 具有可调用（或简单类）的完全限定名的字符串，该字符串返回 TemplateBridge . 然后，该实例用于呈现HTML文档，可能还用于输出其他生成器（当前为更改生成器）。（请注意，如果要使用HTML主题，则必须使模板桥具有主题意识。）

rst_epilog¶

一个重新构造的文本字符串，它将包含在读取的每个源文件的末尾。这是一个添加替换的可能位置，每个文件中都应该有替换（另一个 rst_prolog ）一个例子：

rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""

Added in version 0.6.

rst_prolog¶

一个重新构造的文本字符串，它将包含在每个读取的源文件的开头。这是一个添加替换的可能位置，每个文件中都应该有替换（另一个 rst_epilog ）一个例子：

rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""

Added in version 1.0.

primary_domain¶: 默认设置的名称 domain 。也可以 None 要禁用默认域，请执行以下操作。缺省值为 'py' 。其他域中的那些对象(无论域名是显式给定的，还是由 default-domain 指令)将在命名时显式地将域名放在前面(例如，当默认域为C时，将命名为“Python Function”，而不仅仅是“Function”)。

Added in version 1.0.

default_role¶

要用作默认角色的rest角色（内置或sphinx扩展）的名称，即，对于标记为 `like this '.这个可以设置为 'py:obj' 使 `filter 对python函数“filter”的交叉引用。默认值为 ``None` ，这不会重新分配默认角色。

默认角色始终可以使用标准REST在各个文档中设置 default-role 指令。

Added in version 0.4.

keep_warnings¶

如果为真，则在生成的文档中将警告保留为“系统消息”段落。无论此设置如何，当 sphinx-build 运行。

默认值为 False ，0.5之前的行为总是保留它们。

Added in version 0.5.

show_warning_types¶: 如果 True 每个警告的类型被添加为警告消息的后缀，例如， WARNING: [...] [index] 或 WARNING: [...] [toc.circular] 。缺省值为 False 。

Added in version 7.3.0.

suppress_warnings¶

禁止任意警告消息的警告类型列表。

Sphinx核心支持以下警告类型：

app.add_node
app.add_directive
app.add_role
app.add_generic_role
app.add_source_parser
autosectionlabel.*
download.not_readable
epub.unknown_project_files
epub.duplicated_toc_entry
i18n.inconsistent_references
index
image.not_readable
ref.term
ref.ref
ref.numref
ref.keyword
ref.option
ref.citation
ref.footnote
ref.doc
ref.python
misc.highlighting_failure
toc.circular
toc.excluded
toc.not_readable
toc.secnum

然后，扩展还可以定义它们自己的警告类型。

您可以从这些类型中进行选择。您也可以只指定第一个组件，以排除附加到它的所有警告。

Added in version 1.4.

在 1.5 版本发生变更: 补充 misc.highlighting_failure

在 1.5.1 版本发生变更: 补充 epub.unknown_project_files

在 1.6 版本发生变更: 补充 ref.footnote

在 2.1 版本发生变更: 补充 autosectionlabel.*

在 3.3.0 版本发生变更: 补充 epub.duplicated_toc_entry

在 4.3 版本发生变更: 增列 toc.excluded 和 toc.not_readable

Added in version 4.5:

增列 i18n.inconsistent_references

Added in version 7.1: 增列 index 警告类型。

needs_sphinx¶: 如果设置为 major.minor 版本字符串 '1.1' Sphinx会把它和它的版本进行比较，如果它太旧就拒绝建造。默认为无要求。

Added in version 1.0.

在 1.4 版本发生变更: 还接受微版本字符串

needs_extensions¶

此值可以是一个字典，指定扩展的版本要求 extensions ，例如 needs_extensions = {{'sphinxcontrib.something': '1.5'}} . 版本字符串的格式应为 major.minor . 不必为所有扩展指定要求，只需为要检查的扩展指定要求。

这要求扩展名将其版本指定为sphinx（请参见 Sphinx扩展API 如何做到这一点）。

Added in version 1.3.

manpages_url¶

要交叉引用的URL manpage 角色。如果将其定义为 https://manpages.debian.org/{path} vt.的. :manpage: MAN(%1)``角色将链接到<https://manpages.debian.org/man(1)>.可用的模式包括：

page -手册页 (man ）
section -手册部分 (1 ）
path -指定的原始手册页和节 (man(1) ）

它还支持指定为 man.1 .

备注

这目前只影响HTML编写器，但将来可能会扩展。

Added in version 1.7.

nitpicky¶: 如果是真的，Sphinx会警告 all 找不到目标的引用。默认是 False . 您可以使用 -n 命令行开关。

Added in version 1.0.

nitpick_ignore¶: 一组或一列 (type, target) 在“挑剔模式”下生成警告时应忽略的元组(默认为空)。请注意 type 应包括域名(如果存在)。示例条目如下 ('py:func', 'int') 或 ('envvar', 'LD_LIBRARY_PATH') 。

Added in version 1.1.

在 6.2 版本发生变更: 将允许的容器类型更改为集、列表或元组

nitpick_ignore_regex¶

的扩展版本 nitpick_ignore ，它转而解释 type 和 target 字符串作为正则表达式。请注意，正则表达式必须匹配整个字符串(就好像 ^ 和 $ 插入了标记)。

例如, (r'py:.*', r'foo.*bar\.B.*') 将忽略所有以 'foo' 并拥有 'bar.B' 在它们中，例如 ('py:const', 'foo_package.bar.BAZ_VALUE') 或 ('py:class', 'food.bar.Barman') 。

Added in version 4.1.

在 6.2 版本发生变更: 将允许的容器类型更改为集、列表或元组

numfig¶: 如果为真，则图形、表格和代码块如果有标题，则会自动编号。这个 numref 角色已启用。到目前为止，只有HTML和LaTex构建者遵守。默认是 False .

备注

无论是否启用此选项，LaTex Builder始终指定数字。

Added in version 1.3.

numfig_format¶

字典映射 'figure' ， 'table' ， 'code-block' 和 'section' 用于数字格式的字符串。作为一个特殊的角色， %s 将替换为图号。

默认情况下，使用 'Fig. %s' 为 'figure' ， 'Table %s' 为 'table' ， 'Listing %s' 为 'code-block' 和 'Section %s' 为 'section' 。

Added in version 1.3.

numfig_secnum_depth¶

如果设置为 0 ，数字、表格和代码块从开始连续编号 1 .
如果 1 (default) numbers will be x.1, x.2, ... with x the section number (top level sectioning; no x. 如果没有节）。只有当通过 :numbered: 选择权 toctree 指令。
2 意味着数字将是 x.y.1 ， x.y.2 ，…如果位于小节中（但仍然 x.1 ， x.2 ，…如果直接位于一个截面下方， 1 ， 2 ，…如果不在任何顶层部分。）
等。。。

Added in version 1.3.

在 1.7 版本发生变更: Latex 制造商遵守此设置（如果 numfig 设置为 True ）

smartquotes¶

如果是真的， `Docutils Smart Quotes transform`__ 最初基于 `SmartyPants`_ _（限于英语）目前应用于多种语言，将用于将引号和破折号转换为正确的印刷体。违约： True .

Added in version 1.6.6: 它取代了已弃用的 html_use_smartypants . 它默认应用于除 man 和 text （见 smartquotes_excludes ）

A `docutils.conf`__ 位于配置目录（或全局 ~/.docutils 无条件服从停用通过相应的 `Docutils option`_ ②但是如果激活然后，他们 smartquotes 确实盛行。

smartquotes_action¶: 此字符串自定义智能引号转换。请参阅该文件 smartquotes.py 在 `Docutils repository`__ 了解更多细节。默认设置 'qDe' 培养师范生 q u引用字符 " ， ' ，嗯-和恩- D 灰烬 --- ， -- ，以及 e llipses ... 。

Added in version 1.6.6.

smartquotes_excludes¶

这是一个 dict 默认值为：

{'languages': ['ja'], 'builders': ['man', 'text']}

每个条目都提供了一个足够的条件来忽略 smartquotes 设置和停用智能引号转换。接受的密钥如上所述 'builders' 或 'languages' . 这些值是列表。

备注

目前，如果调用 make 对于多个目标，第一个目标名称是针对 'builders' 它决定一切。另外，A make text 下列的 make html 需要以表格形式发布 make text O="-E" 强制重新解析源文件，因为缓存文件已经被转换。另一方面，直接使用 sphinx-build 当它在每个生成器位置缓存（在其默认用法中）解析的源文件时。

提示

例如，有效地停用（或自定义）给定生成器的智能报价的另一种方法 latex ，用于 make 这种方式：

make latex O="-D smartquotes_action="

这可以遵循一些 make html 没有问题，与前面说明的情况形成对比。

Added in version 1.6.6.

user_agent¶: Sphinx的用户代理。它用于HTTP访问上的头（例如linkcheck、intersphinx等等）。默认为 "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z" .

Added in version 2.3.

tls_verify¶: 如果为真，Sphinx将验证服务器认证。默认是 True .

Added in version 1.5.

tls_cacerts¶: CA证书文件的路径或包含证书的目录的路径。这还允许字典将主机名映射到证书文件的路径。证书用于验证服务器证书。

Added in version 1.5.

小技巧

Sphinx用途 requests 作为内部HTTP库。因此，sphinx指的是所指目录上的认证文件 REQUESTS_CA_BUNDLE 环境变量if tls_cacerts 未设置。

today¶

today_fmt¶

这些值决定如何格式化当前日期，用作 |today| .

如果你设置 today 对于非空值，将使用它。
否则，当前时间的格式将使用 time.strftime() 以及中给出的格式 today_fmt .

默认值现在为 today 和一个 today_fmt 的 '%b %d, %Y' (或者，如果使用启用了转换 language 所选区域设置的等效格式)。

highlight_language¶

用来突出显示源代码的默认语言。缺省值为 'default' 。它类似于 'python3' ；它主要是一个超集 'python' 但它会退回到 'none' 如果失败则不会发出任何警告。 'python3' 如果失败，其他语言将发出警告。

该值应为有效的Pygments词法分析器名称，请参见显示代码示例了解更多详细信息。

Added in version 0.5.

在 1.4 版本发生变更: 默认设置为现在 'default' 。如果您更喜欢仅高亮显示Python2，则可以将其设置回 'python' 。

highlight_options¶

将语言名称映射到Pygments的词法分析器模块选项的字典。这些选项是特定于lexer的；有关每个选项的理解，请参阅 Pygments documentation 。

例子：：

highlight_options = {
  'default': {'stripall': True},
  'php': {'startinline': True},
}

还允许使用单个选项词典。则将其识别为由指定的词法分析器的选项 highlight_language ：：

# configuration for the ``highlight_language``
highlight_options = {'stripall': True}

Added in version 1.3.

在 3.5 版本发生变更: 允许配置多种语言的突出显示选项

pygments_style¶: 用于突出显示源代码的Pygments的样式名。如果未设置，主题的默认样式或 'sphinx' 为HTML输出选择。

在 0.3 版本发生变更: 如果该值是自定义Pygments样式类的完全限定名，则将其用作自定义样式。

maximum_signature_line_length¶

如果签名的字符长度超过设置的数字，则签名中的每个参数将显示在单独的逻辑行上。

什么时候 None (默认)，没有最大长度，整个签名将显示在单个逻辑行上。

“逻辑行”类似于硬行中断-构建者或主题可以选择“软换行”单个逻辑行，并且此设置不会影响该行为。

域可以提供选项来抑制单个对象指令上的任何硬包装，例如在C、C++和Python域(例如 py:function:single-line-parameter-list )。

Added in version 7.1.

add_function_parentheses¶: 决定括号是否附加到函数和方法角色文本（例如 :func:`input ）表示该名称是可调用的。默认是 ``True` .

add_module_names¶: 一个布尔值，用于确定模块名称是否为 object 名称（对于定义了某种“模块”的对象类型），例如 py:function 指令。默认是 True .

toc_object_entries¶: 创建域对象(例如，函数、类、属性等)的目录条目。缺省值为 True 。

toc_object_entries_show_parents¶

一个字符串，它确定域对象(例如函数、类、属性等)显示在它们的目录条目中。

使用 domain to allow the domain to determine the appropriate number of parents to show. For example, the Python domain would show Class.method() and function(), leaving out the module. 父母的级别。这是默认设置。

使用 hide 若要仅显示元素的名称，而不显示任何父元素(即 method() )。

使用 all 要显示对象的完全限定名称(即 module.Class.method() )，显示所有父项。

Added in version 5.2.

show_authors¶: 一个决定是否 codeauthor 和 sectionauthor 指令在生成的文件中生成任何输出。

modindex_common_prefix¶: 为排序python模块索引而忽略的前缀列表（例如，如果设置为 ['foo.'] 然后 foo.bar 显示在 B 不是 F ）如果您记录一个由单个包组成的项目，这将非常方便。当前仅适用于HTML生成器。默认是 [] .

Added in version 0.6.

trim_footnote_reference_space¶: 修剪脚注引用之前的空格，这是REST解析器识别脚注所必需的，但在输出中不要显得太漂亮。

Added in version 0.6.

trim_doctest_flags¶: 如果为真，则doctest标志（注释看起来像 # doctest: FLAG, ... ）在线条末端和 <BLANKLINE> 删除显示交互式Python会话（即doctests）的所有代码块的标记。默认是 True . 查看扩展名 doctest 更多的可能性包括教义。

Added in version 1.0.

在 1.1 版本发生变更: 现在也删除 <BLANKLINE> .

strip_signature_backslash¶: 默认值为 False 。如果启用了反斜杠剥离，则eve会出现 \\ 在域中，指令将更改为 \ ，eve n在字符串文字内。这是3.0版之前的行为，并将此变量设置为 True 会恢复这种行为。

Added in version 3.0.

option_emphasise_placeholders¶: 缺省值为 False 。启用时，强调占位符 option 指令。要显示原义大括号，请使用反斜杠转义 (\{ )。例如, option_emphasise_placeholders=True 和 .. option:: -foption={TYPE} 将呈现为 TYPE 被强调了。

Added in version 5.1.

国际化的选择¶

这些选择影响Sphinx 母语支持 . 请参阅上的文档国际化有关详细信息。

language¶

文档编写时所用语言的代码。Sphinx自动生成的任何文本都将使用该语言。此外，Sphinx会尝试用从以下地址获得的翻译集替换文档中的单个段落 locale_dirs 。Sphinx将搜索特定语言的数字，命名为 figure_language_filename (例如，德文版 myfigure.png 将会是 myfigure.de.png 默认设置)，并用它们替换原始图形。在LaTeX构建器中，将选择合适的语言作为 Babel 包裹。缺省值为 'en' 。

Added in version 0.5.

在 1.4 版本发生变更: 支持图替换

在 5.0 版本发生变更.

Sphinx目前支持的语言有：

ar --阿拉伯语
bg --保加利亚人
bn ——Bengali
ca ——加泰罗尼亚人
cak --卡奇克尔
cs --捷克
cy --威尔士语
da --丹麦人
de 德语
el --希腊语
en --英语(默认)
eo --世界语
es 西班牙语
et 爱沙尼亚人
eu 巴斯克
fa 伊朗
fi ——芬兰
fr --法语
he 希伯来语
hi --印地语
hi_IN --印地语（印度）
hr --克罗地亚语
hu 匈牙利语
id 印度尼西亚人
it 意大利语的
ja --日本
ko --韩语
lt 立陶宛人
lv 拉脱维亚语
mk ——马其顿人
nb_NO --挪威博克马尔
ne 尼泊尔人
nl 荷兰
pl ——波兰
pt ——葡萄牙语
pt_BR --巴西葡萄牙语
pt_PT --欧洲葡萄牙语
ro 罗马尼亚人
ru --俄语
si ——僧伽罗
sk --斯洛伐克
sl ——斯洛文尼亚人的
sq --阿尔巴尼亚语
sr --塞尔维亚语
sr@latin --塞尔维亚语（拉丁语）
sr_RS --塞尔维亚语（西里尔文）
sv --瑞典语
ta --泰米尔语
te --泰卢固语
tr ——土耳其语
uk_UA 乌克兰人
ur --乌尔都语
vi 越南语
zh_CN --简体中文
zh_TW --繁体中文

locale_dirs¶

Added in version 0.5.

要在其中搜索其他邮件目录的目录（请参阅 language ，相对于源目录。此路径上的目录按标准进行搜索 gettext 模块。

从的文本域中提取内部消息 sphinx ；因此，如果添加目录 ./locale 对于此设置，消息目录（编译自 .po 格式使用 msgfmt ）必须在 ./locale/{language}/LC_MESSAGES/sphinx.mo . 单个文档的文本域取决于 gettext_compact .

默认值为 ['locales'] .

备注

这个 -v option for sphinx-build command 对于检查locale_dirs配置是否按预期工作很有用。如果找不到消息目录目录，它将发出调试消息。

在 1.5 版本发生变更: 使用 locales 目录作为默认值

gettext_allow_fuzzy_translations¶: 如果为真，则使用消息目录中的“模糊”消息进行翻译。缺省值为 False 。

Added in version 4.3.

gettext_compact¶

Added in version 1.1.

如果为true，则文档的文本域是其docname（如果它是顶级项目文件），否则是其基本目录。

如果设置为字符串，则所有文档的文本域都是此字符串，使所有文档使用单个文本域。

默认情况下，文档 markup/code.rst 结束于 markup 文本域。将此选项设置为 False 它是 markup/code .

在 3.3 版本发生变更: 现在接受字符串值。

gettext_uuid¶

如果为真，Sphinx将在消息目录中为版本跟踪生成UUID信息。它用于：

为.pot文件中的每个msgid添加uid行。
计算新msgids和以前保存的旧msgids之间的相似性。这个计算需要很长时间。

如果要加速计算，可以使用 python-levenshtein 使用C编写的第三方软件包 pip install python-levenshtein .

默认值为 False .

Added in version 1.3.

gettext_location¶

如果为真，Sphinx将为消息目录中的消息生成位置信息。

默认值为 True .

Added in version 1.3.

gettext_auto_build¶

如果为真，Sphinx将为每个翻译目录文件生成mo文件。

默认值为 True .

Added in version 1.3.

gettext_additional_targets¶

指定名称以另外启用对i18n应用的GetText提取和转换。可以指定以下名称：

指数:: 索引项
文字块:: 文字块 (:: 注释和 code-block 指令）
测试块:: 测试块
未经加工的:: 原始内容
形象:: 图像/图形URI

例如： gettext_additional_targets = ['literal-block', 'image'] .

默认值为 [] .

Added in version 1.3.

在 4.0 版本发生变更: 默认情况下，会翻译图像的Alt文本。

figure_language_filename¶

语言特定数字的文件名格式。默认值为 {{root}}.{{language}}{{ext}} . 它将扩展到 dirname/filename.en.png 从 .. image:: dirname/filename.png . 可用的格式标记有：

{root} - the filename, including any path component, without the file extension, e.g. dirname/filename
{path} - the directory path component of the filename, with a trailing slash if non-empty, e.g. dirname/
{{docpath}} -当前文档的目录路径组件，如果不是空的，则后面有一个斜杠。
{basename} - the filename without the directory path or file extension components, e.g. filename
{ext} - the file extension, e.g. .png
{language} - the translation language, e.g. en

例如，将此设置为 {{path}}{{language}}/{{basename}}{{ext}} 将扩展到 dirname/en/filename.png 相反。

Added in version 1.4.

在 1.5 版本发生变更: 补充 {{path}} 和 {{basename}} 令牌。

在 3.2 版本发生变更: 补充 {{docpath}} 令牌。

translation_progress_classes¶

控制添加哪些类(如果有)以指示转换进度。此设置可能只由文档的翻译者使用，以便快速指示已翻译和未翻译的内容。

True ：添加 translated 和 untranslated 类添加到具有可翻译内容的所有节点。
translated ：仅添加 translated 班级。
untranslated ：仅添加 untranslated 班级。
False ：不添加任何类来指示翻译进度。

默认为 False .

Added in version 7.1.

数学选项¶

这些选项影响数学符号。

math_number_all¶: 将此选项设置为 True 如果要对显示的所有数学进行编号。默认值为 False .

math_eqref_format¶

用于设置公式引用标签格式的字符串。这个 {{number}} 占位符代表方程式编号。

例子： 'Eq.{{number}}' 例如，呈现为， Eq.10 .

math_numfig¶: 如果 True ，当 numfig 启用。这个 numfig_secnum_depth 设置得到尊重。这个 eq 不是 numref ，角色必须用于引用公式编号。默认是 True .

Added in version 1.7.

HTML输出选项¶

这些选项会影响HTML以及HTML帮助输出，以及使用sphinx的htmlwriter类的其他构建器。

html_theme¶: HTML输出应该使用的“主题”。见 section about theming . 默认值为 'alabaster' .

Added in version 0.6.

html_theme_options¶: 影响所选主题外观的选项字典。这些是特定主题的。有关内置主题理解的选项，请参见 this section .

Added in version 0.6.

html_theme_path¶: 包含自定义主题的路径列表，可以是子目录，也可以是zip文件。相对路径被视为相对于配置目录的路径。

Added in version 0.6.

html_style¶: 用于HTML页的样式表。该名称的文件必须存在于Sphinx的 static/ 路径，或在中给定的自定义路径之一中 html_static_path . 默认值是由所选主题提供的样式表。如果只想添加或覆盖与主题样式表相比的一些内容，请使用CSS @import 导入主题的样式表。

html_title¶: 使用Sphinx自己的模板生成的HTML文档的“标题”。这是附加到 <title> 单个页面的标记，并在导航栏中用作“最顶层”元素。它默认为 '{<project>} v{<revision>} documentation' .

html_short_title¶: HTML文档的简短“标题”。它用于标题和HTML帮助文档中的链接。如果未给定，则默认为 html_title .

Added in version 0.4.

html_baseurl¶: 指向HTML文档根的基URL。它用来指示文档的位置，使用 The Canonical Link Relation 。默认值： '' 。

Added in version 1.8.

html_codeblock_linenos_style¶

代码块的行号样式。

'table' --使用显示行号 <table> 标牌
'inline' --使用显示行号 <span> 标记(默认)

Added in version 3.2.

在 4.0 版本发生变更: 默认为 'inline' 。

自 4.0 版本弃用.

html_context¶: 要传递到模板引擎上下文中的所有页的值字典。也可以使用 -A 命令行选项 sphinx-build .

Added in version 0.5.

html_logo¶: 如果给定，这必须是图像文件的名称(相对于 configuration directory )这是文档的徽标，或指向徽标的图像文件的URL。它被放置在侧边栏的顶部；因此其宽度不应超过200像素。默认： None 。

Added in version 0.4.1: 图像文件将复制到 _static 输出HTML的目录，但仅当文件不存在时。

在 4.0 版本发生变更: 还接受徽标文件的URL。

html_favicon¶: 如果给定，这必须是图像文件的名称(相对于 configuration directory )这是文档的收藏图标，或指向该收藏图标的图像文件的URL。现代浏览器将其用作选项卡、窗口和书签的图标。它应该是Windows样式的图标文件 (.ico )，大小为16x16或32x32像素。默认： None 。

Added in version 0.4: 图像文件将复制到 _static 输出HTML的目录，但仅当文件不存在时。

在 4.0 版本发生变更: 还接受收藏夹图标的URL。

html_css_files¶

一个css文件列表。该条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典。这个 filename 必须相对于 html_static_path ，或具有如下方案的完整URI https://example.org/style.css 。这个 attributes 用于以下属性 <link> 标签。它默认为空列表。

例子：：

html_css_files = ['custom.css',
                  'https://example.com/css/custom.css',
                  ('print.css', {'media': 'print'})]

作为一种特殊属性， priority 可以设置为整数，以便在较早或较慢的步骤中加载CSS文件。有关更多信息，请参阅 Sphinx.add_css_file() 。

Added in version 1.8.

在 3.5 版本发生变更: 支持优先级属性

html_js_files¶

一份JavaScript的列表 filename 。该条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典。这个 filename 必须相对于 html_static_path ，或具有如下方案的完整URI https://example.org/script.js 。这个 attributes 用于以下属性 <script> 标签。它默认为空列表。

例子：：

html_js_files = ['script.js',
                 'https://example.com/scripts/custom.js',
                 ('custom.js', {'async': 'async'})]

作为一种特殊属性， priority 可以设置为整数，以便在较早或较慢的步骤中加载JavaScript文件。有关更多信息，请参阅 Sphinx.add_js_file() 。

Added in version 1.8.

在 3.5 版本发生变更: 支持优先级属性

html_static_path¶

包含自定义静态文件（如样式表或脚本文件）的路径列表。相对路径被视为相对于配置目录的路径。它们被复制到输出的 _static 目录后的主题的静态文件，所以文件名为 default.css 将覆盖主题的 default.css .

由于这些文件不是要构建的，因此它们会自动从源文件中排除。

备注

出于安全原因，点文件位于 html_static_path 不会被复制。如果要有意复制，请将每个文件路径添加到此设置：

html_static_path = ['_static', '_static/.htaccess']

另一种方法是，您也可以使用 html_extra_path . 它允许复制目录下的点文件。

在 0.4 版本发生变更: 中的路径 html_static_path 现在可以包含子目录。

在 1.0 版本发生变更: 参赛作品 html_static_path 现在可以是单个文件。

在 1.8 版本发生变更: 下面的文件 html_static_path 从源文件中排除。

html_extra_path¶

包含与文档不直接相关的额外文件的路径列表，例如 robots.txt 或 .htaccess . 相对路径被视为相对于配置目录的路径。它们被复制到输出目录。它们将覆盖任何同名的现有文件。

由于这些文件不是要构建的，因此它们会自动从源文件中排除。

Added in version 1.2.

在 1.4 版本发生变更: 额外目录中的点文件将被复制到输出目录。它指的是 exclude_patterns 在复制额外的文件和目录时，忽略路径是否与模式匹配。

html_last_updated_fmt¶: 如果不是NONE，则在每个页面底部插入“上次更新日期：”时间戳，并使用给定的 strftime() 格式化。空字符串等效于 '%b %d, %Y' (或与区域设置相关的等价物)。

html_use_smartypants¶: 如果为真，则引号和破折号将转换为正确的印刷体实体。违约： True .

自 1.6 版本弃用: 要禁用智能引号，请使用 smartquotes .

html_permalinks¶: 为每个标题和描述环境添加链接锚点。默认： True 。

Added in version 3.5.

html_permalinks_icon¶: 每个标题和描述环境的链接锚点的文本。允许使用HTML实体和Unicode。默认：段落符号； ¶

Added in version 3.5.

html_sidebars¶

自定义边栏模板必须是将文档名映射到模板名的字典。

键可以包含全局样式模式 [1], 在这种情况下，所有匹配的文档都将获得指定的侧栏。（当多个全局样式模式与任何文档匹配时，将发出警告。）

值可以是列表或单个字符串。

如果值是列表，则指定要包含的侧边栏模板的完整列表。如果要包括所有或部分默认的侧边栏，那么它们也必须放在这个列表中。

默认侧栏（对于与任何模式都不匹配的文档）由主题本身定义。默认情况下，内置主题使用这些模板： ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] .
如果值是单个字符串，则指定要在 'sourcelink.html' 和 'searchbox.html' 条目。这是为了与1.0之前的Sphinx版本兼容。

自 1.7 版本弃用: 的单个字符串值 html_sidebars 将在2.0中删除

可以呈现的内置边栏模板包括：

localtoc.html --当前文档的细粒度目录
globaltoc.html --整个文档集的粗粒度目录已折叠
relations.html --指向上一个和下一个文档的两个链接
sourcelink.html --指向当前文档源的链接（如果在中启用） html_show_sourcelink
searchbox.html --“快速搜索”框

例子：：

html_sidebars = {
   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
   'using/windows': ['windowssidebar.html', 'searchbox.html'],
}

这将呈现自定义模板 windowssidebar.html 以及给定文档侧栏中的快速搜索框，并呈现所有其他页面的默认侧栏（本地目录被全局目录替换的情况除外）。

Added in version 1.0: 使用全局键和指定多个侧栏的功能。

请注意，只有当所选主题不具有侧边栏（如内置主题）时，此值才无效。卷轴和俳句主题。

html_additional_pages¶

应呈现到HTML页面的其他模板必须是将文档名映射到模板名的字典。

例子：：

html_additional_pages = {
    'download': 'customdownload.html',
}

这将呈现模板 customdownload.html 作为页面 download.html .

html_domain_indices¶

如果为true，则除了生成常规索引之外，还生成特定于域的索引。例如，对于python域，这是全局模块索引。默认是 True .

这个值可以是一个bool或者应该生成的索引名列表。要查找特定索引的索引名，请查看HTML文件名。例如，python模块索引具有名称 'py-modindex' .

Added in version 1.0.

html_use_index¶: 如果为true，则向HTML文档添加索引。默认是 True .

Added in version 0.4.

html_split_index¶: 如果为真，则会生成两次索引：一次作为包含所有条目的单页，一次作为每个起始字母的一页。默认是 False .

Added in version 0.4.

html_copy_source¶: 如果为真，其余源代码将作为 _sources/{name} . 默认值为 True .

html_show_sourcelink¶: 如果是真的（和） html_copy_source 也是这样），到其余源的链接将添加到侧边栏。默认值为 True .

Added in version 0.6.

html_sourcelink_suffix¶: 要附加到源链接的后缀（请参见 html_show_sourcelink ，除非他们已经有了这个后缀。默认是 '.txt' .

Added in version 1.5.

html_use_opensearch¶: 如果非空，则返回 OpenSearch 将输出描述文件，并且所有页面都将包含 <link> 引用它的标签。由于OpenSearch不支持其搜索页面位置的相对URL，因此此选项的值必须是提供这些文档的基本URL(没有尾随斜杠)，例如 "https://docs.python.org" 。缺省值为 '' 。

html_file_suffix¶: 这是生成的HTML文件的文件名后缀，如果设置为 str 价值。如果保留为默认设置 None ，后缀将为 ".html" 。

Added in version 0.4.

html_link_suffix¶: 生成的指向HTML文件的链接的后缀。默认值是 html_file_suffix 设置为；可以进行不同的设置（例如，支持不同的Web服务器设置）。

Added in version 0.6.

html_show_copyright¶: 如果为真，“（c）版权…”将显示在HTML页脚中。默认是 True .

Added in version 1.0.

html_show_search_summary¶: 如果为True，则关键字周围的文本显示为每个搜索结果的摘要。缺省值为 True 。

Added in version 4.5.

html_show_sphinx¶: 如果为真，则“使用sphinx创建”将显示在HTML页脚中。默认是 True .

Added in version 0.4.

html_output_encoding¶: HTML输出文件的编码。默认是 'utf-8' . 请注意，此编码名称必须同时是有效的python编码名称和有效的html charset 价值。

Added in version 1.0.

html_compact_lists¶: 如果为真，则列出所有项目由单个段落和/或子列表组成的所有项目等。（递归定义）将不使用 <p> 元素。这是标准的docutils行为。违约： True .

Added in version 1.0.

html_secnumber_suffix¶: 章节编号的后缀。违约： ". " . 设置为 " " 以抑制节号上的最后一个点。

Added in version 1.0.

html_search_language¶

用于生成HTML全文搜索索引的语言。这默认为所选的全局语言 language . 如果不支持这种语言， "en" 用于选择英语。

支持这些语言：

da --丹麦人
nl 荷兰
en --英语
fi ——芬兰
fr --法语
de 德语
hu 匈牙利语
it 意大利语的
ja --日本
no 挪威人
pt ——葡萄牙语
ro 罗马尼亚人
ru --俄语
es 西班牙语
sv --瑞典语
tr ——土耳其语
zh --中国人

加速构建速度

每种语言（日语除外）都提供自己的词干算法。默认情况下，sphinx使用python实现。可以使用C实现加速构建索引文件。

PorterStemmer (en ）
PyStemmer （所有语言）

Added in version 1.1: 支持 en 和 ja .

在 1.3 版本发生变更: 添加了其他语言。

html_search_options¶

带有搜索语言支持选项的字典，默认为空。这些选项的含义取决于所选语言。

英语支持没有选择。

日本支持有以下选项：

类型:

type`是点分模块路径字符串，用于指定应从中派生的拆分器实现 :class:!sphinx.search.ja.BaseSplitter` 。如果未指定或 None 是指定的， 'sphinx.search.ja.DefaultSplitter' 将会被使用。

您可以从以下模块中选择：

'sphinx.search.ja.DefaultSplitter':: tinysegenter算法。这是默认拆分器。
'sphinx.search.ja.MecabSplitter':: MeCAB结合。要使用这个拆分器，需要“mecab”python绑定或动态链接库（“libmecab.so”对于Linux，“libmecab.dll”对于Windows）。
'sphinx.search.ja.JanomeSplitter':: Janome装订。要使用这个拆分器， Janome 是必需的。

自 1.6 版本弃用: 'mecab' ， 'janome' 和 'default' 被贬低。为了保持兼容性， 'mecab' ， 'janome' 和 'default' 也可以接受。

其他选项值取决于您选择的拆分器值。

选项 'mecab' ：

dic_enc:: _` dic_enc option`是mecab算法的编码。
双关语:: _` dict option`是用于mecab算法的字典。
国际清算银行:: _` lib option`是在未安装python绑定的情况下，通过ctypes查找mecab库的库名。

例如：：

html_search_options = {
    'type': 'mecab',
    'dic_enc': 'utf-8',
    'dict': '/path/to/mecab.dic',
    'lib': '/path/to/libmecab.so',
}

选项 'janome' ：

user_dic:: _` user_dic option`是janome的用户字典文件路径。
user_dic_enc:: _` user_dic_enc option`是用户字典文件的编码，由 user_dic 选择权。默认值为“utf8”。

Added in version 1.1.

在 1.4 版本发生变更: 对日语的html_搜索选项进行了重新组织，并且可以使用任何自定义拆分器 type 设置。

中国的支持有以下选择：

dict —— jieba 如果要使用自定义字典，则返回字典路径。

html_search_scorer¶

实现搜索结果记分器的javascript文件的名称（相对于配置目录）。如果为空，将使用默认值。

计分者必须实现以下接口，并且可以选择性地定义 score() 功能，实现更精细的控制。

const Scorer = {
    // Implement the following function to further tweak the score for each result
    score: result => {
      const [docName, title, anchor, descr, score, filename] = result

      // ... calculate a new score ...
      return score
    },

    // query matches the full name of an object
    objNameMatch: 11,
    // or matches in the last dotted part of the object name
    objPartialMatch: 6,
    // Additive scores depending on the priority of the object
    objPrio: {
      0: 15, // used to be importantResults
      1: 5, // used to be objectResults
      2: -5, // used to be unimportantResults
    },
    //  Used when the priority is not in the mapping.
    objPrioDefault: 0,

    // query found in title
    title: 15,
    partialTitle: 7,

    // query found in terms
    term: 5,
    partialTerm: 2,
};

Added in version 1.2.

html_scaled_image_link¶

如果为True，则图像本身链接到原始图像(如果它没有“目标”选项或与缩放相关的选项：“Scale”、“Width”、“Height”)。缺省值为 True 。

文档作者可以使用以下命令手动禁用此功能 no-scaled-link 类添加到图像：

.. image:: sphinx.png
   :scale: 50%
   :class: no-scaled-link

Added in version 1.3.

在 3.0 版本发生变更: 对于具有 no-scaled-link 类

html_math_renderer¶: HTML输出的数学呈现器扩展名。默认值为 'mathjax' .

Added in version 1.8.

html_experimental_html5_writer¶: 输出由HTML5编写器处理。缺省值为 False 。

Added in version 1.6.

自 2.0 版本弃用.

html4_writer¶: 输出由HTML4编写器处理。默认是 False .

单个HTML输出选项¶

singlehtml_sidebars¶: 自定义侧栏模板，必须是将文档名称映射到模板名称的词典。并且它只允许名为的密钥 'index' 。所有其他关键点都将被忽略。有关详细信息，请参阅 html_sidebars 。默认情况下，它与 html_sidebars 。

HTML帮助输出选项¶

htmlhelp_basename¶: HTML帮助生成器的输出文件基名称。默认是 'pydoc' .

htmlhelp_file_suffix¶: 这是生成的HTML帮助文件的文件名后缀。默认值为 ".html" .

Added in version 2.0.

htmlhelp_link_suffix¶: 生成的指向HTML文件的链接的后缀。默认值为 ".html" .

Added in version 2.0.

Apple帮助输出选项¶

Added in version 1.3.

这些选项会影响Apple帮助输出。此生成器派生自HTML生成器，因此HTML选项也适用于适当的情况。

备注

Apple帮助输出只能在Mac OS X 10.6及更高版本上工作，因为它需要 hiutil 和 codesign 命令行工具，两者都不是开源的。

您可以使用 applehelp_disable_external_tools ，但在索引器运行到 .lproj 包中的文件夹。

applehelp_bundle_name¶: Apple帮助手册的基本名称。默认为 project 姓名。

applehelp_bundle_id¶: 帮助书包的包ID。

警告

你 must 设置此值以生成Apple帮助。

applehelp_dev_region¶: 开发区。默认为 'en-us' ，这是苹果推荐的设置。

applehelp_bundle_version¶: 捆绑版本（作为字符串）。默认为 '1' .

applehelp_icon¶: 帮助捆绑图标文件，或 None 没有图标。根据苹果的文档，这应该是应用程序图标的16 x 16像素版本，具有透明背景，保存为PNG文件。

applehelp_kb_product¶: 与一起使用的产品标签 applehelp_kb_url . 默认为 '{<project>}-{<release>}' .

applehelp_kb_url¶

知识库服务器的URL，例如 https://example.com/kbsearch.py?p='product'&q='query'&l='lang' . 帮助查看器将替换这些值 'product' ， 'query' 和 'lang' 在运行时 applehelp_kb_product ，用户在搜索框中输入的文本和用户的系统语言。

默认为 None 不进行远程搜索。

applehelp_remote_url¶

远程内容的URL。你可以放一份你的帮助书 Resources 此位置的文件夹和帮助查看器将尝试使用它来获取更新的内容。

例如，如果将其设置为 https://example.com/help/Foo/ 帮助查看器需要 index.html 对于讲英语的客户，它会 https://example.com/help/Foo/en.lproj/index.html .

默认为 None 没有远程内容。

applehelp_index_anchors¶: 如果 True ，告诉帮助索引器索引生成的HTML中的锚。这对于使用 AHLookupAnchor 函数或 openHelpAnchor:inBook: 方法。它还允许您使用 help:anchor URL；有关此主题的更多信息，请参阅Apple文档。

applehelp_min_term_length¶: 控制帮助索引器的最小期限长度。默认为 None ，这意味着将使用默认值。

applehelp_stopwords¶

语言规范（使用内置stopwords）或stopwords plist的路径，或 None 如果你不想用生字。默认的stopwords plist可以在 /usr/share/hiutil/Stopwords.plist 并在书写时包含以下语言的停止字：

语言	代码
英语	恩
德国的	判定元件
西班牙的	锿
法语	FR
瑞典的	SV
匈牙利语	胡
意大利人	它

默认为 language ，或者如果未设置，则设置为 'en' 。

applehelp_locale¶

指定要为其生成帮助的区域设置。这用于确定 .lproj 帮助手册中的文件夹 Resources ，并传递给帮助索引器。

默认为 language ，或者如果未设置，则设置为 'en' 。

applehelp_title¶: 指定帮助书标题。默认为 '{<project>} Help' .

applehelp_codesign_identity¶

指定用于代码签名的标识，或 None 如果不执行代码签名。

默认为环境变量的值 CODE_SIGN_IDENTITY ，由Xcode为脚本生成阶段设置，或者 None 如果未设置该变量。

applehelp_codesign_flags¶

A list 要传递给的其他参数 codesign 在签署帮助手册时。

默认为基于环境变量值的列表 OTHER_CODE_SIGN_FLAGS ，由Xcode为脚本生成阶段设置，如果未设置该变量，则为空列表。

applehelp_indexer_path¶: 通往那条路的路 hiutil 程序。默认为 '/usr/bin/hiutil' .

applehelp_codesign_path¶: 通往那条路的路 codesign 程序。默认为 '/usr/bin/codesign' .

applehelp_disable_external_tools¶

如果 True ，生成器将不会运行索引器或代码签名工具，无论指定了什么其他设置。

这主要用于测试，或者您希望在非Mac OS X平台上运行sphinx构建，然后出于某种原因在OS X上完成最后的步骤。

默认为 False .

EPUB输出选项¶

这些选项会影响epub输出。由于此构建器派生自HTML构建器，因此在适当的情况下也会应用HTML选项。某些选项的实际值并不重要，只需将它们输入到 Dublin Core metadata 。

epub_basename¶: epub文件的基名称。它默认为 project 姓名。

epub_theme¶: EPUB输出的HTML主题。由于默认主题没有针对小屏幕空间进行优化，因此对HTML和EPUB输出使用相同的主题通常是不明智的。默认为 'epub' 一个旨在节省视觉空间的主题。

epub_theme_options¶: 影响所选主题外观的选项字典。这些是特定主题的。有关内置主题理解的选项，请参见 this section .

Added in version 1.2.

epub_title¶: 文档的标题。它默认为 html_title 选项，但可以独立设置以创建EPUB。它默认为 project 选择权。

在 2.0 版本发生变更: 它默认为 project 选择权。

epub_description¶: 文档的说明。默认值为 'unknown' .

Added in version 1.4.

在 1.5 版本发生变更: 更名为 epub3_description

epub_author¶: 文档的作者。这是都柏林核心元数据。它默认为 author 选择权。

epub_contributor¶: 在电子出版物内容的创建中起次要作用的人、组织等的名称。默认值为 'unknown' .

Added in version 1.4.

在 1.5 版本发生变更: 更名为 epub3_contributor

epub_language¶: 文档的语言。这是都柏林核心元数据。默认值是 language 选项或 'en' 如果未设置。

epub_publisher¶: 文档的发布者。这是都柏林核心元数据。您可以使用任何合理的字符串，例如项目主页。默认为 author 选择权。

epub_copyright¶: 文件的版权。它默认为 copyright 选项，但可以独立设置以创建EPUB。

epub_identifier¶: 文档的标识符。这是都柏林核心元数据。对于已发布的文档，这是ISBN号，但您也可以使用其他方案，例如项目主页。默认值为 'unknown' .

epub_scheme¶: 的发布方案 epub_identifier . 这是都柏林核心元数据。对于已出版的书籍，计划是 'ISBN' . 如果使用项目主页， 'URL' 似乎很合理。默认值为 'unknown' .

epub_uid¶: 文档的唯一标识符。这是都柏林核心元数据。您可以使用 XML's Name format 字符串。不能将连字符、句点和数字用作第一个字符。默认值为 'unknown' .

epub_cover¶

封面信息。这是一个包含封面图像和HTML模板的文件名的元组。呈现的HTML封面将作为脊椎中的第一个项目插入 content.opf . 如果模板文件名为空，则不会创建HTML封面。如果元组为空，则根本不创建封面。实例：

epub_cover = ('_static/cover.png', 'epub-cover.html')
epub_cover = ('_static/cover.png', '')
epub_cover = ()

默认值为 () .

Added in version 1.1.

epub_css_files¶: CSS文件列表。条目必须是 文件名 字符串或包含 文件名 字符串和属性字典。有关详细信息，请参阅 html_css_files .

Added in version 1.8.

epub_guide¶

的引导元素的元数据 content.opf 。这是一个元组序列，包含 type vt.的. uri 以及 title 可选的指南信息。请参阅OPF文档，网址为 https://idpf.org/epub 了解更多细节。如果可能，默认条目为 cover 和 toc 类型将自动插入。但是，如果默认条目不合适，则可以显式覆盖这些类型。示例：：

epub_guide = (('cover', 'cover.html', 'Cover Page'),)

默认值为 () .

epub_pre_files¶

应在Sphinx生成的文本之前插入的其他文件。它是包含文件名和标题的元组列表。如果标题为空，则不会向添加任何条目 toc.ncx .例子：：

epub_pre_files = [
    ('index.html', 'Welcome'),
]

默认值为 [] .

epub_post_files¶: 应在Sphinx生成的文本后插入的其他文件。它是包含文件名和标题的元组列表。此选项可用于添加附录。如果标题为空，则不会向添加任何条目 toc.ncx . 默认值为 [] .

epub_exclude_files¶: 在生成目录中生成/复制但不应包含在EPUB文件中的文件列表。默认值为 [] .

epub_tocdepth¶: 文件中目录的深度 toc.ncx . 它应该是大于零的整数。默认值为3。注意：深度嵌套的目录可能很难导航。

epub_tocdup¶: 此标志确定是否在嵌套的TOC列表的开头再次插入TOC条目。这样可以更容易地导航到章节的顶部，但会令人困惑，因为它在一个列表中混合了不同深度的条目。默认值为 True .

epub_tocscope¶

此设置控制EPUB目录的范围。该设置可以具有以下值：

'default' --包括所有未隐藏的目录项（默认）
'includehidden' --包括所有目录项

Added in version 1.2.

epub_fix_images¶: 此标志确定Sphinx是否应尝试修复某些ePUB读卡器不支持的图像格式。目前，带有小颜色表的调色板图像已升级。您需要安装枕头（python image library）才能使用此选项。默认值为 False 因为自动转换可能会丢失信息。

Added in version 1.2.

epub_max_image_width¶: 此选项指定图像的最大宽度。如果设置为大于零的值，则宽度大于给定值的图像将相应缩放。如果为零，则不执行缩放。默认值为 0 . 您需要安装python图像库（枕头）才能使用此选项。

Added in version 1.2.

epub_show_urls¶

控制是否显示URL地址。这对于没有其他方法显示链接的URL的读者非常有用。设置可以具有以下值：

'inline' --在括号中以内联方式显示URL（默认）
'footnote' --在脚注中显示URL
'no' --不显示URL

通过为类添加CSS规则，可以自定义内联URL的显示。 link-target .

Added in version 1.2.

epub_use_index¶: 如果为真，请向EPUB文档添加索引。它默认为 html_use_index 选项，但可以独立设置以创建EPUB。

Added in version 1.2.

epub_writing_mode¶

它指定了书写方向。它可以接受 'horizontal' （默认） 'vertical'

`epub_writing_mode`	`'horizontal'`	`'vertical'`
写作模式 [2]	`horizontal-tb`	`vertical-rl`
页面前进	从左到右	从左到右
iBook的滚动主题支持	滚动轴是垂直的。	滚动轴是水平的。

Latex 输出选项¶

这些选项影响 Latex 产量。

latex_engine¶

构建文档的 Latex 引擎。该设置可以具有以下值：

'pdflatex' --pdflatex（默认）
'xelatex' ——XeLaTeX
'lualatex' ——LuaLaTeX
'platex' --Platex
'uplatex' --upLaTeX(默认为 language 是 'ja' )

'pdflatex' 对Unicode字符的支持有限。

备注

2增加 'pdflatex' 支持拉丁语文档中偶尔出现的西里尔字母或希腊字母或单词。这不是自动的，参见 latex_elements 'fontenc' 关键。

如果项目使用Unicode字符，请将引擎设置为 'xelatex' 或 'lualatex' 确保使用足够宽的字形覆盖范围的OpenType字体通常比尝试 'pdflatex' 使用额外的Unicode字符。由于sphinx 2.0，默认值是gnu freefont，它覆盖了拉丁语、西里尔语和希腊语。

在 2.1.0 版本发生变更: 使用 xelatex （和 Latex 包装 xeCJK )默认为中文文档。

在 2.2.1 版本发生变更: 使用 xelatex 希腊文件的默认值。

在 2.3 版本发生变更: 添加 uplatex 支持。

在 4.0 版本发生变更: uplatex 成为日语文档的默认设置。

相反地 MathJaX math rendering in HTML output ，LaTex需要一些额外的配置来支持 math ：唯一全面的解决方案（据我们所知）是 'xelatex' 或 'lualatex' and 添加 r'\usepackage{{unicode-math}}' （例如通过 latex_elements 'preamble' 关键）。你可能更喜欢 r'\usepackage[math-style=literal]{{unicode-math}}' 保留Unicode文字，如 α （u+03b1）例如输出中的，而不是呈现为 $\alpha$ .

latex_documents¶

此值确定如何将文档树分组为 Latex 源文件。它必须是元组列表 (startdocname, targetname, title, author, theme, toctree_only) ，其中项为：

启动文档名: 字符串，该字符串指定 document name LaTeX文件的主文档。引用的所有文档 startdoc 目录树中的文档将包含在LaTeX文件中。(如果您希望在LaTeX版本中使用默认根文档，请提供 root_doc 在这里。)
目标名称: 输出目录中 Latex 文件的文件名。
标题: Latex 文件标题。可以为空以使用 启动文档 文件。这是作为 Latex 标记插入的，因此特殊字符（如反斜杠或与号）必须由适当的 Latex 命令表示（如果要从字面上插入）。
作者: Latex 文件的作者。相同的 Latex 标记警告标题应用。使用 \\and 分开多个作者，如： 'John \\and Sarah' （反斜杠必须是 Python 逃到 Latex 处）。
主题: Latex 主题。见 latex_theme .
toctree_only: 必须是 True 或 False . 如果是真的， 启动文档 文档本身不包括在输出中，只包括它通过TOC树引用的文档。使用此选项，您可以在HTML中显示的主文档中放置额外的内容，但不能放置LaTex输出。

Added in version 1.2: 在过去，包括您自己的文档类都要求您在文档类名称前面加上字符串“sphinx”。这不再是必要的了。

Added in version 0.3: 第六项 toctree_only . 包含5个项的元组仍被接受。

latex_logo¶: 如果给定，这必须是作为文档徽标的图像文件（相对于配置目录）的名称。它放在标题页的顶部。违约： None .

latex_toplevel_sectioning¶

该值确定最顶部的剖切单位。应该从中选择 'part' ， 'chapter' 或 'section' . 默认值为 None ；最上面的分段单元由documentClass切换： section 如果documentClass将 howto ，否则 chapter 将被使用。

注意如果 Latex 使用 \part 命令，那么一级深度的分区单元的编号将与HTML编号失去同步，因为 Latex 编号是连续的。 \chapter （或） \section 对于 howto ）

Added in version 1.4.

latex_appendices¶: 作为所有手册附录附加的文件名列表。

latex_domain_indices¶

如果为true，则除了生成常规索引之外，还生成特定于域的索引。例如，对于python域，这是全局模块索引。默认是 True .

这个值可以是bool或应该生成的索引名列表，比如 html_domain_indices .

Added in version 1.0.

latex_show_pagerefs¶: 如果为true，则在内部引用之后添加页引用。这对印刷版的手册非常有用。默认是 False .

Added in version 1.0.

latex_show_urls¶

控制是否显示URL地址。这对印刷版的手册非常有用。该设置可以具有以下值：

'no' --不显示URL（默认）
'footnote' --在脚注中显示URL
'inline' --在括号内显示URL

Added in version 1.0.

在 1.1 版本发生变更: 这个值现在是一个字符串；以前是一个布尔值，而一个真值选择了 'inline' 显示。为了向后兼容， True 仍被接受。

latex_use_latex_multicolumn¶

默认值为 False ：这意味着Sphinx自己的宏用于来自网格表的合并单元格。它们允许常规内容（文本块、列表、块引号等），但如果 tabularcolumns 指令用于注入该类型的 Latex 标记。 >{{..}} ， <{{..}} ， @{{..}} 作为柱规范。

设置为 True 使用 Latex 标准的方法 \multicolumn ；这与水平合并单元格中的文本块不兼容，如果使用 tabulary .

Added in version 1.6.

latex_table_style¶

样式类(字符串)的列表。目前支持：

'booktabs' ：没有垂直线，只有2到3行水平线(如果有标题，则为后者)，使用 booktabs 包裹。
'borderless' ：没有任何台词。
'colorrows' ：表格行以交替的背景颜色呈现。定制它们的界面是通过 dedicated keys 的这个 sphinxsetup 配置设置。

重要

与 'colorrows' 风格， \rowcolors LaTeX命令变成了no-op(该命令有限制，并且从未正确支持Sphinx在LaTeX中生成的所有类型的表)。请更新您的项目以使用 latex table color configuration 钥匙。

默认： ['booktabs', 'colorrows']

Added in version 5.3.0.

在 6.0.0 版本发生变更: 修改默认发件人 [] 至 ['booktabs', 'colorrows'] 。

每个表都可以通过以下方式覆盖全局样式 :class: 选项，或 .. rst-class:: 对于非指令表(参见表格 )。当前可识别的类有 booktabs ， borderless ， standard ， colorrows ， nocolorrows 。后两项可以与前三项中的任何一项组合。这个 standard 类生成同时具有水平线和垂直线的表(这是Sphinx到目前为止的默认设置)。

如果设置了单行多列合并单元格，则它将遵循行颜色。另请参阅 TableMergeColor{Header,Odd,Even} 在这个 sphinxsetup 配置设置一节。

备注

它在LaTeX中是硬编码的，即使有列颜色设置为 \columncolor 从列规范(请参见 tabularcolumns )。Sphinx提供 \sphinxnorowcolor 它可以像这样使用：
```
>{\columncolor{blue}\sphinxnorowcolor}
```
在表列规范中。
Sphinx还提供 \sphinxcolorblend 然而，这需要 xcolor 包裹。下面是一个例子：
```
>{\sphinxcolorblend{!95!red}}
```
这意味着在该列中，行的颜色将略带红色；请参阅 xcolor 有关其语法的更多信息，请参阅文档 \blendcolors 命令(a \blendcolors 代替 \sphinxcolorblend 会修改单元格的颜色 contents ，而不是细胞的 background colour panel ...)。中可以找到一个用法示例不赞成的API 本文档的部分内容为PDF格式。

提示

如果要将特殊颜色用于 contents 给定列的单元格中使用 >{\noindent\color{<color>}} ，可能是除了上述之外。
多行合并单元格，无论是单列还是多列，当前都会忽略任何设置的列、行或单元格颜色。
对于简单的单元格，可以通过 raw 指令和 \cellcolor 在单元格内容中的任何位置使用的LaTeX命令。这目前在合并后的单元格中不起作用，无论是哪种类型。

提示

在未使用的文档中 'booktabs' 在全局范围内，可以通过 booktabs 类，但需要添加 r'\usepackage{booktabs}' Latex 前言。

另一方面，人们可以使用 colorrows 不需要额外包的单个表的类(因为Sphinx从5.3.0开始总是加载 colortbl) 。

latex_use_xindy¶

如果 True ，从Sphinx创建的 Latex 文件生成的PDF将使用 xindy (doc__) 而不是 makeindex 编制通用术语索引（自 index 用法）。这意味着带有utf-8字符的单词将被正确排序 language .

如果 latex_engine 是 'platex' （日本文件； mendex 替换 makeindex 然后）。
默认值为 True 对于 'xelatex' 或 'lualatex' 作为 makeindex ，如果任何索引项以非ASCII字符开头，则创建 .ind 包含用于UTF-8编码的无效字节的文件。用 'lualatex' 这将破坏PDF构建。
默认值为 False 对于 'pdflatex' 但是 True 建议非英语文档在某些索引术语使用语言脚本中的非ASCII字符时立即使用。

Sphinx补充说 xindy 基地分布一些专用的支持使用 'pdflatex' 带有西里尔文脚本的引擎。以及是否与 'pdflatex' 或者Unicode引擎，西里尔文文档可以正确处理拉丁名称的索引，即使是使用音调符号。

Added in version 1.8.

latex_elements¶: Added in version 0.5.

它的 documentation 已经搬到 Latex 定制 .

latex_docclass¶: 字典映射 'howto' 和 'manual' 将用作两个sphinx类的基础的真实文档类的名称。默认为使用 'article' 对于 'howto' 和 'report' 对于 'manual' .

Added in version 1.0.

在 1.5 版本发生变更: 日语文档 (language 是 'ja' ），默认情况下 'jreport' 用于 'howto' 和 'jsbook' 对于 'manual' .

latex_additional_files¶

在生成 Latex 输出时，要复制到生成目录的相对于配置目录的文件名列表。这对于复制Sphinx不会自动复制的文件很有用，例如，如果在添加的自定义 Latex 中引用了这些文件， latex_elements . 源文件中引用的图像文件（例如通过 .. image:: ）自动复制。

您必须确保文件名不会与任何自动复制的文件发生冲突。

注意

带扩展名的文件名 .tex 将自动移交给由以下触发的PDF构建过程 sphinx-build -M latexpdf 或通过 make latexpdf 。如果仅将该文件添加为 \input{} 在修改后的前同步码中，您必须添加另一个后缀，例如 .txt 设置为文件名，并相应地调整 \input{} 命令添加到LaTeX文件序言中。

Added in version 0.6.

在 1.2 版本发生变更: 这将覆盖Sphinx提供的文件，例如 sphinx.sty .

latex_theme¶

Latex 输出应该使用的“主题”。它是 Latex 输出设置的集合（例如文档类、顶级分区单元等）。

作为一个内置的 Latex 主题， manual 和 howto 是捆绑的。

manual: 书写手册的 Latex 主题。它进口 report 文档类（日语文档使用 jsbook ）
howto: 写文章的胶乳主题。它进口 article 文档类（日语文档使用 jreport 而是）。 latex_appendices 仅适用于此主题。

它默认为 'manual' .

Added in version 3.0.

latex_theme_options¶: 影响选定主题外观的选项字典。

Added in version 3.1.

latex_theme_path¶: 包含自定义 Latex 主题作为子目录的路径列表。相对路径被视为相对于配置目录。

Added in version 3.0.

文本输出选项¶

这些选项影响文本输出。

text_newlines¶

确定文本输出中使用的行尾字符。

'unix' ：使用Unix样式的行尾 (\n ）
'windows' ：使用Windows样式的行尾 (\r\n ）
'native' ：使用文档所基于的平台的行尾样式

违约： 'unix' .

Added in version 1.1.

text_sectionchars¶

一个由7个字符组成的字符串，用于给各节加下划线。第一个字符用于第一级标题，第二个字符用于第二级标题等等。

默认值为 '*=-~"+`' .

Added in version 1.1.

text_add_secnumbers¶: 决定文本输出中是否包含节号的布尔值。默认是 True .

Added in version 1.7.

text_secnumber_suffix¶: 文本输出中节号的后缀。违约： ". " . 设置为 " " 以抑制节号上的最后一个点。

Added in version 1.7.

手动页面输出选项¶

这些选项影响手动页面输出。

man_pages¶

此值确定如何将文档树分组为手动页。它必须是元组列表 (startdocname, name, description, authors, section) ，其中项为：

启动文档名: 字符串，该字符串指定 document name 手册页的主文档。引用的所有文档 startdoc 目录树中的文档将包含在手册文件中。(如果要使用默认根文档构建手册页面，请使用您的 root_doc 在这里。)
name: 手册页的名称。这应该是一个没有空格或特殊字符的短字符串。它用于确定文件名以及手册页的名称（在名称部分）。
description: 手册页的说明。这在名称部分中使用。如果不想自动生成NAME节，则可以为空字符串。
作者: 包含作者的字符串列表，或单个字符串。如果不希望在手动页面中自动生成作者部分，则可以是空字符串或列表。
部分: 手册页部分。用于输出文件名以及手动页标题。

Added in version 1.0.

man_show_urls¶: 如果为真，请在链接后添加URL地址。默认是 False .

Added in version 1.1.

man_make_section_directory¶: 如果为True，则在构建手册页上创建一个部分目录。默认为True。

Added in version 3.3.

在 4.0 版本发生变更: 默认设置更改为 False 从… True 。

在 4.0.2 版本发生变更: 默认设置更改为 True 从… False 再来一次。

Texinfo输出选项¶

这些选项影响Texinfo输出。

texinfo_documents¶

此值确定如何将文档树分组为Texinfo源文件。它必须是元组列表 (startdocname, targetname, title, author, dir_entry, description, category, toctree_only) ，其中项为：

启动文档名: 字符串，该字符串指定 document name 纹理信息文件的主文档的。引用的所有文档 startdoc 目录树中的文档将包含在文本信息文件中。(如果您想要为您的纹理信息版本使用默认主文档，请提供您的 root_doc 在这里。)
目标名称: 输出目录中texinfo文件的文件名（无扩展名）。
标题: Texinfo文档标题。可以为空以使用 启动文档 文件。作为texinfo标记插入，因此 @ 和 {{}} 需要从字面上插入转义。
作者: Texinfo文档的作者。作为texinfo标记插入。使用 @* 分开多个作者，如： 'John@*Sarah' .
dir_entry: 将出现在顶级中的名称 DIR 菜单文件。
description: 要在顶层显示的描述性文本 DIR 菜单文件。
类别: 指定此项将在顶层显示的节 DIR 菜单文件。
toctree_only: 必须是 True 或 False . 如果是真的， 启动文档 文档本身不包括在输出中，只包括它通过TOC树引用的文档。使用此选项，您可以在HTML中显示的主文档中放置额外的内容，但不能放置Texinfo输出。

Added in version 1.1.

texinfo_appendices¶: 作为所有手册附录附加的文件名列表。

Added in version 1.1.

texinfo_domain_indices¶

如果为true，则除了生成常规索引之外，还生成特定于域的索引。例如，对于python域，这是全局模块索引。默认是 True .

这个值可以是bool或应该生成的索引名列表，比如 html_domain_indices .

Added in version 1.1.

texinfo_show_urls¶

控制如何显示URL地址。

'footnote' --在脚注中显示URL（默认）
'no' --不显示URL
'inline' --在括号内显示URL

Added in version 1.1.

texinfo_no_detailmenu¶: 如果为真，则不生成 @detailmenu 在“top”节点的菜单中，包含文档中每个子节点的条目。默认是 False .

Added in version 1.2.

texinfo_elements¶

包含Texinfo代码段的字典，重写这些Sphinx通常会将这些代码段放入生成的 .texi 文件夹。

您可能要重写的键包括：

'paragraphindent'
每段第一行缩进的空格数，默认值 2 . 指定 0 没有缩进。

'exampleindent'
默认情况下，用于缩进示例或文本块行的空格数 4 . 指定 0 没有缩进。

'preamble'
在文件开头附近插入的texinfo标记。

'copying'
Texinfo标记插入到 @copying 阻止并在标题后显示。默认值由标识项目的简单标题页组成。
由其他选项设置的不应被重写的键是：

'author' 'body' 'date' 'direntry' 'filename' 'project' 'release' 'title'

Added in version 1.1.

texinfo_cross_references¶: 如果为False，则不在文档中生成内联引用。这使得使用独立阅读器的INFO文件更具可读性 (info )。缺省值为 True 。

Added in version 4.4.

qthelp输出选项¶

这些选项影响qthelp输出。由于此生成器是从HTML生成器派生的，因此HTML选项也适用于适当的情况。

qthelp_basename¶: qthelp文件的基名称。它默认为 project 姓名。

qthelp_namespace¶: qthelp文件的命名空间。它默认为 org.sphinx.<project_name>.<project_version> .

qthelp_theme¶: qthelp输出的HTML主题。默认为 'nonav' .

qthelp_theme_options¶: 影响所选主题外观的选项字典。这些是特定主题的。有关内置主题理解的选项，请参见 this section .

链接检查生成器的选项¶

linkcheck_ignore¶

与在执行以下操作时不应检查的uri匹配的正则表达式列表 linkcheck 建造。例子：：

linkcheck_ignore = [r'https://localhost:\d+/']

Added in version 1.1.

linkcheck_allowed_redirects¶

将源URI的模式映射到规范URI的模式的字典。在以下情况下，LinkCheck构建器将重定向的链接视为“工作”：

文档中的链接与源URI模式匹配，并且
重定向位置与规范URI模式匹配。

例子：

linkcheck_allowed_redirects = {
    # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
    r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
}

如果设置，则LinkCheck生成器将在发现不允许的重定向时发出警告。下检测意外重定向非常有用 the warn-is-error mode 。

Added in version 4.1.

linkcheck_request_headers¶

将baseurl映射到HTTP请求头的字典。

键是基于URL的字符串，如下所示 "https://www.sphinx-doc.org/" 。要为其他主机指定标头，请执行以下操作： "*" 可以使用。仅当URL与其他设置不匹配时，它才匹配所有主机。

该值是一个将头名称映射到其值的字典。

例子：

linkcheck_request_headers = {
    "https://www.sphinx-doc.org/": {
        "Accept": "text/html",
        "Accept-Encoding": "utf-8",
    },
    "*": {
        "Accept": "text/html,application/xhtml+xml",
    }
}

Added in version 3.1.

linkcheck_retries¶: LinkCheck生成器在声明某个URL断开之前尝试检查该URL的次数。默认为1次尝试。

Added in version 1.4.

linkcheck_timeout¶: 链接检查生成器在每个超链接请求后等待响应的持续时间(秒)。默认为30秒。

Added in version 1.1.

linkcheck_workers¶: 检查链接时要使用的工作线程数。默认为5个线程。

Added in version 1.1.

linkcheck_anchors¶: 如果为真，请检查 #anchor 在链接中。因为这需要下载整个文档，所以启用时速度要慢得多。默认是 True .

Added in version 1.2.

linkcheck_anchors_ignore¶

当检查链接中锚的有效性时，匹配锚sphinx的正则表达式列表应该跳过。这允许跳过网站的javascript添加到控制动态页面或触发内部REST请求的锚。默认是 ["^!"] .

小技巧

使用 linkcheck_anchors_ignore_for_url 检查URL，但跳过验证锚点是否存在。

备注

如果要忽略特定页面或与特定模式匹配的页面的锚定（但仍要检查没有锚定的同一页面的出现情况），请使用 linkcheck_ignore 相反，例如：

linkcheck_ignore = [
   'https://www.sphinx-doc.org/en/1.7/intro.html#',
]

Added in version 1.5.

linkcheck_anchors_ignore_for_url¶: 与Sphinx不应检查其锚的有效性的URL匹配的正则表达式的列表或元组。这允许跳过基于每个页面的锚点检查，同时仍然检查页面本身的有效性。默认为空的元组 () 。

Added in version 7.1.

linkcheck_auth¶

执行以下操作时传递身份验证信息 linkcheck 建造。

列表 (regex_pattern, auth_info) 项目所在的元组：

regex_pattern: 与URI匹配的正则表达式。
auth_info: 用于该URI的身份验证信息。该值可以是 requests 库(请参见 requests Authentication 有关详细信息，请参见)。

这个 linkcheck 生成器将使用第一个匹配 auth_info 它可以在 linkcheck_auth 列表，因此列表中较早的值具有更高的优先级。

例子：：

linkcheck_auth = [
  ('https://foo\.yourcompany\.com/.+', ('johndoe', 'secret')),
  ('https://.+\.yourcompany\.com/.+', HTTPDigestAuth(...)),
]

Added in version 2.3.

linkcheck_rate_limit_timeout¶

这个 linkcheck 建筑商可能会在短时间内向同一站点发出大量请求。当服务器指示请求受到速率限制时，此设置控制生成器行为。

如果服务器指示何时重试(使用 Retry-After 标题)， linkcheck 始终遵循服务器指示。

否则， linkcheck 在重试之前等待一分钟，并持续将两次尝试之间的等待时间增加一倍，直到成功或超过 linkcheck_rate_limit_timeout 。默认情况下，超时为300秒，自定义超时应以秒为单位。

Added in version 3.4.

linkcheck_exclude_documents¶

与Sphinx不应检查链接有效性的文档匹配的正则表达式列表。这可用于允许文档的遗留或历史部分中的链接衰减。

例子：：

# ignore all links in documents located in a subfolder named 'legacy'
linkcheck_exclude_documents = [r'.*/legacy/.*']

Added in version 4.4.

linkcheck_allow_unauthorized¶

当Web服务器使用HTTP 401(未经授权)响应进行响应时，Sphinx当前的默认行为是将链接视为“工作”。要更改该行为，请将此选项设置为 False 。

该选项的缺省值将在Sphinx 8.0中更改；从该版本开始，默认情况下，对选中的超链接的HTTP401响应将被视为“断开”。

Added in version 7.3.

XML生成器选项¶

xml_pretty¶: 如果为真，则漂亮地打印XML。默认是 True .

Added in version 1.2.

脚注

C域的选项¶

c_id_attributes¶: 解析器还应接受的字符串列表，作为属性。例如，当属性 #define d表示可移植性。

Added in version 3.0.

c_paren_attributes¶: 解析器还应接受的字符串列表，作为带有一个参数的属性。也就是说，如果 my_align_as 在名单上，那么 my_align_as(X) 被分析为所有字符串的属性 X 有平衡支撑的 (() ， [] 和 {{}} ）例如，当属性 #define d表示可移植性。

Added in version 3.0.

c_extra_keywords¶: 要被C解析器识别为关键字的标识符列表。默认为 ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local'] 。

Added in version 4.0.3.

c_maximum_signature_line_length¶: 如果签名的字符长度超过设置的数字，则每个参数将显示在单独的逻辑行上。这是特定于域的设置，重写 maximum_signature_line_length 。

Added in version 7.1.

C++域的选项¶

cpp_index_common_prefix¶: 在全局索引中排序C++对象时会忽略的前缀列表。例如 ['awesome_lib::'] .

Added in version 1.5.

cpp_id_attributes¶: 解析器还应接受的字符串列表，作为属性。例如，当属性 #define d表示可移植性。

Added in version 1.5.

cpp_paren_attributes¶: 解析器还应接受的字符串列表，作为带有一个参数的属性。也就是说，如果 my_align_as 在名单上，那么 my_align_as(X) 被分析为所有字符串的属性 X 有平衡支撑的 (() ， [] 和 {{}} ）例如，当属性 #define d表示可移植性。

Added in version 1.5.

cpp_maximum_signature_line_length¶: 如果签名的字符长度超过设置的数字，则每个参数将显示在单独的逻辑行上。这是特定于域的设置，重写 maximum_signature_line_length 。

Added in version 7.1.

用于Python域的选项¶

python_display_short_literal_types¶

该值控制如何 Literal 将显示类型。该设置为布尔值，默认为 False 。

实例¶

下面的示例使用以下内容 py:function 指令：

.. py:function:: serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

什么时候 False ， Literal 类型按照标准的Python语法显示，即：

serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

什么时候 True ， Literal 类型显示为短的、 PEP 604 -受启发的语法，即：

serve_food(item: "egg" | "spam" | "lobster thermidor") -> None

Added in version 6.2.

python_use_unqualified_type_names¶: 如果为True，则在可以解析的情况下取消显示Python引用的模块名称。缺省值为 False 。

Added in version 4.0.

备注

此配置仍处于实验阶段

python_maximum_signature_line_length¶

如果签名的字符长度超过设置的数字，则每个参数或类型参数将显示在单独的逻辑行上。这是特定于域的设置，重写 maximum_signature_line_length 。

对于Python域，签名长度取决于是否设置了类型参数或参数列表的格式。对于前者，签名长度忽略参数列表的长度；对于后者，签名长度忽略类型参数列表的长度。

例如，使用 python_maximum_signature_line_length = 20 ，则仅类型参数列表将被换行，而参数列表将呈现在一行上

.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)

Added in version 7.1.

用于Java Script域的选项¶

javascript_maximum_signature_line_length¶: 如果签名的字符长度超过设置的数字，则每个参数将显示在单独的逻辑行上。这是特定于域的设置，重写 maximum_signature_line_length 。

Added in version 7.1.

配置文件示例¶

# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is executed through importlib.import_module with 
# the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
#
# source_encoding = 'utf-8-sig'

# The master toctree document.
root_doc = 'index'

# General information about the project.
project = 'test'
copyright = '2016, test'
author = 'test'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'test'
# The full version, including alpha/beta/rc tags.
release = 'test'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []

# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False


# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []

# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = 'test vtest'

# A shorter title for the navigation bar.  Default is the same as html_title.
#
# html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None

# The name of an image file (relative to this directory) to use as a favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []

# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None

# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}

# If false, no module index is generated.
#
# html_domain_indices = True

# If false, no index is generated.
#
# html_use_index = True

# If true, the index is split into individual pages for each letter.
#
# html_split_index = False

# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'

# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}

# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (root_doc, 'test.tex', 'test Documentation',
     'test', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None

# If true, show page references after internal links.
#
# latex_show_pagerefs = False

# If true, show URL addresses after external links.
#
# latex_show_urls = False

# Documents to append as an appendix to all manuals.
#
# latex_appendices = []

# If false, no module index is generated.
#
# latex_domain_indices = True


# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (root_doc, 'test', 'test Documentation',
     [author], 1)
]

# If true, show URL addresses after external links.
#
# man_show_urls = False


# -- Options for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (root_doc, 'test', 'test Documentation',
     author, 'test', 'One line description of project.',
     'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []

# If false, no module index is generated.
#
# texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'

# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False

# If false, do not generate in manual @ref nodes.
#
# texinfo_cross_references = False

# -- A random example -----------------------------------------------------

import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']

numfig = True
#language = 'ja'

extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
#extensions.append('sphinx.ext.autosummary')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')


autosummary_generate = True
html_theme = 'default'
#source_suffix = ['.rst', '.txt']

Sphinx

On this page

Site navigation

配置¶

项目信息¶

一般配置¶

国际化的选择¶

数学选项¶

HTML输出选项¶

单个HTML输出选项¶

HTML帮助输出选项¶

Apple帮助输出选项¶

EPUB输出选项¶

Latex 输出选项¶

文本输出选项¶

手动页面输出选项¶

Texinfo输出选项¶

qthelp输出选项¶

链接检查生成器的选项¶

XML生成器选项¶

C域的选项¶

C++域的选项¶

用于Python域的选项¶

实例¶

用于Java Script域的选项¶

配置文件示例¶