配置¶

配置目录须包含 conf.py 文件(内为Python代码)。该文件称为"构建配置文件"，包含定制Sphinx输入和输出行为所需的（几乎）所有配置项。

如果没有被Sphinx覆盖或设置, 可以在配置目录中添加一个可选文件 docutils.conf 来调整 Docutils 配置。

重点注意：

如果没有另外记录, 则值必须是字符串, 并且它们的默认值为空字符串。
“完全限定名称”（FQN）一词是指命名模块内可导入的Python对象的字符串；例如，完全限定名称 "sphinx.builders.Builder" 表示 sphinx.builders 模块中的 Builder 类。
文档名称使用 / 作为路径分隔符, 并且不包含文件名扩展名。

在允许使用glob模式的地方，您可以使用标准的shell构造（*, ?, [...], 和 [!...]），但这些都不会匹配斜杠（/）。可以使用双星号 ** 来匹配包括斜杠在内的任何字符序列。

小技巧

配置文件在构建时作为Python代码执行（使用 importlib.import_module()，当前目录设置为配置目录），因此可以执行任意复杂的代码。

Sphinx然后从文件的命名空间中读取简单名称作为其配置。通常，配置值应该是简单的字符串、数字，或简单值的列表或字典。

配置命名空间的内容被序列化（以便Sphinx可以找出配置何时更改），因此它可能不包含不可序列化的值 -- 如果适用，请使用 del 从命名空间中删除它们。模块会自动删除，因此不需要删除导入的模块。

项目标签¶

配置文件中有一个名为 tags 的特殊对象，它暴露了 project tags。标签是通过 --tag 命令行选项或 tags.add('tag') 定义的。请注意，构建器的名称和格式标签在 conf.py 中不可用。

它可用于查询和更改已定义的标签，如下所示：

使用 'tag' in tags 来查询是否设置了标签。
添加标签，请使用 tags.add('tag')。
删除标签，请使用 tags.remove('tag')。

项目信息¶

project¶

类型:: str
默认:: 'Project name not set'

文档项目的名称。例如：

project = 'Thermidor'

author¶

类型:: str
默认:: 'Author name not set'

项目的作者。例如：

author = 'Joe Bloggs'

copyright¶

project_copyright¶

类型:: str | Sequence[str]
默认:: ''

copyright = 'YYYY'
copyright = 'YYYY, Author Name'
copyright = 'YYYY Author Name'
copyright = 'YYYY-YYYY, Author Name'
copyright = 'YYYY-YYYY Author Name'

如果版权行中出现字符串 '%Y'，则将其替换为当前的四位数年份。例如：

copyright = '%Y'
copyright = '%Y, Author Name'
copyright = 'YYYY-%Y, Author Name'

在 3.5 版本加入: project_copyright 别名。

version¶

类型:: str
默认:: ''

工程的主版本，用作 |version| default substitutions 的替换。

这会像 version = '4.2'。完整的项目版本在 release 中定义。

如果您的项目在“完整”版本和“主要”版本之间没有明显区别，请将 version 和 release 都设置为相同的值。

release¶

类型:: str
默认:: ''

完整的项目版本，用作 |release| default substitutions 的替换，例如在HTML模板中。

这可能类似于 release = '4.2.1b0'。主要（简短）项目版本在 version 中定义。

如果您的项目在“完整”版本和“主要”版本之间没有明显区别，请将 version 和 release 都设置为相同的值。

一般配置¶

needs_sphinx¶

类型:: str
默认:: ''

设置构建项目所需的Sphinx最低版本要求。格式应为 'major.minor' 版本字符串，如 '1.1' Sphinx将其与其版本进行比较，如果运行的Sphinx版本过旧，则拒绝构建该项目。默认情况下，没有最低版本要求。

在 1.0 版本加入.

在 1.4 版本发生变更: 允许 'major.minor.micro' 版本字符串。

extensions¶

类型:: list[str]
默认:: []

一个字符串列表，这些字符串是 Sphinx扩展的模块名称。这些可以是Sphinx内置的扩展（命名为 sphinx.ext.*）或自定义的第一方或第三方扩展。

要使用第三方扩展，必须确保已安装它并将其包含在 extensions 列表中，如下所示：

extensions = [
    ...
    'numpydoc',
]

第一方扩展有两种选择。配置文件本身可以是一个扩展；为此，您只需要在其中提供一个 setup() 函数。否则，您必须确保您的自定义扩展是可导入的，并且位于Python路径中的目录中。

在修改 sys.path 时确保使用绝对路径。如果您的自定义扩展位于相对于配置目录的目录中，请使用 pathlib.Path.resolve()，如下所示：

import sys
from pathlib import Path

sys.path.append(str(Path('sphinxext').resolve()))

extensions = [
   ...
   'extname',
]

上述目录结构如下所示：

<project directory>/
├── conf.py
└── sphinxext/
    └── extname.py

needs_extensions¶

类型:: dict[str, str]
默认:: {}

如果设置, 该值必须是一个字典, 指定 extensions 中扩展的版本要求。版本字符串应为 'major.minor' 形式。并不需要为所有扩展指定要求, 只需为您想要检查的那些指定即可。例如：

needs_extensions = {
    'sphinxcontrib.something': '1.5',
}

这要求扩展在 setup() 函数中声明其版本。有关更多详细信息，请参见 Sphinx API接口。

在 1.3 版本加入.

manpages_url¶

类型:: str
默认:: ''

用于交叉引用 manpage 角色的URL。如果将其定义为 https://manpages.debian.org/{path}， :manpage:`man(1)` 角色会被链接到<https://manpages.debian.org/man(1)>。可用的模式有：

page: 手册页（man）
section: 手册章节（1）
path: 原始手册页和指定的章节（man(1)）

这也支持指定为 man.1 的联机帮助页。

# To use manpages.debian.org:
manpages_url = 'https://manpages.debian.org/{path}'
# To use man7.org:
manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
# To use linux.die.net:
manpages_url = 'https://linux.die.net/man/{section}/{page}'
# To use helpmanual.io:
manpages_url = 'https://helpmanual.io/man{section}/{page}'

在 1.7 版本加入.

today¶

today_fmt¶

这些值决定如何格式化当前日期，用作 |today| default substitutions 的替换。

如果将 today 设置为非空值，则使用它。
否则，使用 time.strftime() 格式化当前时间，格式为 today_fmt。

today 的默认值为 ''，today_fmt 的默认值为 '%b %d, %Y' （或者，如果使用 language 启用了翻译，则为所选语言环境的等效格式）。

用于图像编号的选项¶

numfig¶

类型:: bool
默认:: False

如果为 True，则如果图像、表格和代码块具有标题，则会自动对其进行编号。启用 numref 角色。到目前为止，仅HTML和LaTeX构建器遵守此规则。

备注

无论是否启用此选项, LaTeX构建器始终会分配数字。

在 1.3 版本加入.

numfig_format¶

类型:: dict[str, str]
默认:: {}

将 'figure'、'table'、'code-block' 和 'section' 映射到用于图像编号格式的字符串的字典。标记 %s 将被替换为图像编号。

默认值为：

numfig_format = {
    'code-block': 'Listing %s',
    'figure': 'Fig. %s',
    'section': 'Section',
    'table': 'Table %s',
}

在 1.3 版本加入.

numfig_secnum_depth¶

类型:: int
默认:: 1

如果设置为 0，则图像、表格和代码块将从 1 开始连续编号。
如果为 1，则编号将为 x.1、x.2，... 其中 x 表示章节编号。(如果没有顶级章节，则不会添加前缀)。这自然只适用于通过 toctree 指令的 :numbered: 选项激活章节编号的情况。
如果为 2，则编号将为 x.y.1、x.y.2，... 其中 x 表示章节编号，y 表示子章节编号。如果直接位于章节下，则不会有 y. 前缀；如果没有顶级章节，则不会添加前缀。
可以使用任何其他正整数，遵循上述规则。

在 1.3 版本加入.

在 1.7 版本发生变更: 如果 numfig 设置为 True，则LaTeX构建器会遵守此设置。

用于高亮显示的选项¶

highlight_language¶

类型:: str
默认:: 'default'

用于高亮显示源代码的默认语言。默认为'default'，若以Python代码进行高亮显示失败，则会抑制警告。

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

在 0.5 版本加入.

在 1.4 版本发生变更: 默认值现在是 'default'。

highlight_options¶

类型:: dict[str, dict[str, Any]]
默认:: {}

一个将Pygments词法分析器名称映射到其选项的字典。这些是特定于词法分析器的；有关每个词法分析器所理解的选项，请参见 Pygments documentation 。

举例如下：

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

在 1.3 版本加入.

在 3.5 版本发生变更: 允许为多个词法分析器配置高亮选项。

pygments_style¶

类型:: str
默认:: 'sphinx'

Pygments高亮显示源代码时使用的样式名称。如未设置, 则HTML输出将选择主题的默认样式或'sphinx'。

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

用于HTTP请求的选项¶

tls_verify¶

类型:: bool
默认:: True

如果为True, Sphinx会验证服务器证书。

在 1.5 版本加入.

tls_cacerts¶

类型:: str | dict[str, str]
默认:: ''

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

在 1.5 版本加入.

小技巧

Sphinx在内部使用 requests 作为HTTP库。如果 tls_cacerts 未设置，Sphinx将回退到requests的默认行为。有关更多详细信息，请参见 SSL Cert Verification 。

user_agent¶

类型:: str
默认:: 'Mozilla/5.0 (X11; Linux x86_64; rv:100.0) Gecko/20100101 Firefox/100.0 Sphinx/X.Y.Z'

设置Sphinx用于HTTP请求的用户代理。

在 2.3 版本加入.

用于国际化的选项¶

这些选项影响Sphinx的 本地语言支持。详情请参见国际化文档。

language¶

类型:: str
默认:: 'en'

文档所用语言的代码。Sphinx自动生成的任何文本都将使用该语言。此外，Sphinx将尝试用从 locale_dirs 获取的翻译集替换文档中的各个段落。Sphinx将搜索由 figure_language_filename 命名的特定语言图形（例如，默认设置下 myfigure.png 的德语版本将是 myfigure.de.png），并将其替换为原始图形。在LaTeX构建器中，将选择适当的语言作为 Babel 包的选项。

在 0.5 版本加入.

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

在 5.0 版本发生变更: 默认值现在是 'en' （以前是 None）。

目前Sphinx支持的语言是：

ar -- 阿拉伯语
bg -- 保加利亚语
bn -- 孟加拉语
ca -- 加泰罗尼亚语
cak -- 喀克其奎语
cs -- 捷克语
cy-- 威尔士语
da -- 丹麦语
de -- 德语
el -- 希腊语
en -- 英语（默认）
eo -- 世界语
es -- 西班牙语
et -- 爱沙尼亚语
eu -- 巴斯克语
fa -- 伊朗语
fi -- 芬兰语
fr -- 法语
he -- 希伯来语
hi -- 北印度语
hi_IN -- 北印度语（印度）
hr -- 克罗地亚语
hu -- 匈牙利语
id -- 印度尼西亚语
id -- 印度尼西亚语
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¶

类型:: list[str]
默认:: ['locales']

在其中搜索其他消息目录的目录(见language)，相对于源目录。gettext模块将搜索此路径上的目录。

内部消息来自 sphinx 的文本域；因此，如果将目录 ./locales 添加到此设置中，则消息目录（使用 msgfmt 从 .po 格式编译而成）必须位于 ./locales/language/LC_MESSAGES/sphinx.mo。各个文档的文本域取决于 gettext_compact。

备注

-v 选项用于 sphinx-build 可用于检查 locale_dirs 设置是否按预期工作。

在 0.5 版本加入.

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

gettext_allow_fuzzy_translations¶

类型:: bool
默认:: False

如果为 True，则使用消息目录中的 “模糊(fuzzy)” 消息进行翻译。

在 4.3 版本加入.

gettext_compact¶

类型:: bool | str
默认:: True

如果为 True，则文档的文本域是其文档名称（如果它是顶级项目文件）否则是其基目录。
如果为 False，则文档的文本域是完整的文档名称。
If 设置为字符串，则每个文档的文本域都设置为该字符串，使所有文档使用单一文本域。

使用 gettext_compact = True，文档 markup/code.rst 最终位于 markup 文本域中。将此选项设置为 False，则为 markup/code。将此选项设置为 'sample'，则为 sample。

在 1.1 版本加入.

在 3.3 版本发生变更: 允许字符串值。

gettext_uuid¶

类型:: bool
默认:: False

如果为 True，Sphinx会为消息目录生成用于版本跟踪的UUID信息。它用于：

在 .pot 文件中的每个 msgid 添加 UUID 行。
计算新 msgid 与先前保存的旧 msgid 之间的相似性。（此计算可能需要很长时间。）

小技巧

如果想加快计算速度，可以通过运行 pip install levenshtein 使用第三方包 (Levenshtein) 。

在 1.3 版本加入.

gettext_location¶

类型:: bool
默认:: True

If True，Sphinx会为消息目录中的消息生成位置信息。

在 1.3 版本加入.

gettext_auto_build¶

类型:: bool
默认:: True

If True，Sphinx为每个翻译目录文件构建一个 .mo 文件。

在 1.3 版本加入.

gettext_additional_targets¶

类型:: set[str] | Sequence[str]
默认:: []

使能某些元素类型的 gettext 翻译。举例如下：

gettext_additional_targets = {'literal-block', 'image'}

支持以下元素类型：

'index' -- 索引项
'literal-block' -- 字面量块（:: 注释和 code-block 指令）
'doctest-block' -- doctest 块
'raw' -- 原始内容
'image' -- 图像/图形 uri

在 1.3 版本加入.

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

在 7.4 版本发生变更: 允许并优先使用集合类型。

figure_language_filename¶

类型:: str
默认:: '{root}.{language}{ext}'

文件名格式用于特定语言的图形。可用的格式标记有：

{root}: 文件名，包括任何路径组件，不包括文件扩展名。例如： images/filename 。
{path}: 文件名的目录路径组件，如果非空则带有尾随斜杠。例如： images/ 。
{basename}: 不带目录路径或文件扩展名组件的文件名。例如： filename 。
{ext}: 文件扩展名。例如： .png 。
{language}: 翻译语言。例如： en 。
{docpath}: 当前文档的目录路径组件，如果非空则带有尾随斜杠。例如： dirname/ 。

默认情况下，图像指令 .. image:: images/filename.png，使用位于 images/filename.png 的图像，将使用特定语言的图形文件名 images/filename.en.png 。

如果将 figure_language_filename 设置如下，则特定语言的图形文件名将改为 images/en/filename.png 。

figure_language_filename = '{path}{language}/{basename}{ext}'

在 1.4 版本加入.

在 1.5 版本发生变更: 添加了 {path} 和 {basename} 标记。

在 3.2 版本发生变更: 添加 {docpath} 标记。

translation_progress_classes¶

类型:: bool | 'translated' | 'untranslated'
默认:: False

控制是否添加类以指示翻译进度。此设置可能仅由文档的翻译人员使用，以快速指示已翻译和未翻译的内容。

True: 向所有具有可翻译内容的节点添加 translated 和 untranslated 类。
'translated': 只添加 translated 类。
'untranslated': 只添加 untranslated 类。
False: 不添加任何类来指示翻译进度。

在 7.1 版本加入.

用于markup的选项¶

default_role¶

类型:: str
默认:: None

默认角色的名称（内置或Sphinx扩展）用作默认角色，即用于标记为 `like this` 的文本。可以将其设置为 'py:obj' 以使 `filter` 成为对Python函数“filter”的交叉引用。

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

在 0.4 版本加入.

keep_warnings¶

类型:: bool
默认:: False

在渲染的文档中将警告保留为“系统消息”段落。无论此设置如何, 运行 sphinx-build 时, 警告始终写入标准错误流。

在 0.5 版本加入.

option_emphasise_placeholders¶

类型:: bool
默认:: False

启用时, 强调 option 指令中的占位符。要显示文字大括号, 请使用反斜杠（\{）进行转义。例如, option_emphasise_placeholders=True 和 .. option:: -foption={TYPE} 将以强调的 TYPE 渲染。

在 5.1 版本加入.

primary_domain¶

类型:: str
默认:: 'py'

默认 domain 的名称。也可以是 None 来禁用默认域。默认值为 'py', 用于Python域。

其他域中的那些对象（无论域名是明确给出, 还是由 default-domain 指令选择）在命名时将显式地添加域名（例如, 当默认域为C时, Python函数将被命名为“Python function”, 而不仅仅是“function”）。例：

primary_domain = 'cpp'

在 1.0 版本加入.

rst_epilog¶

类型:: str
默认:: ''

一个 reStructuredText 字符串, 将包含在读取的每个源文件的末尾。这是添加替换项以在每个文件中可用的可能位置（另一个是 rst_prolog）。例：

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

在 0.6 版本加入.

rst_prolog¶

类型:: str
默认:: ''

一个 reStructuredText 字符串, 将包含在读取的每个源文件的开头。这是添加替换项以在每个文件中可用的可能位置（另一个是 rst_epilog）。例：

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

在 1.0 版本加入.

show_authors¶

类型:: bool
默认:: False

一个布尔值，决定 codeauthor 和 sectionauthor 指令在构建的文件中产生任何输出。

trim_footnote_reference_space¶

类型:: bool
默认:: False

在脚注引用之前修剪空格, 这些空格对于reStructuredText解析器识别脚注是必要的, 但输出不太好看。

在 0.6 版本加入.

用于Maths的选项¶

这些选项控制数学标记和符号。

math_eqref_format¶

类型:: str
默认:: '({number})'

用于格式化方程式引用标签的字符串。 {number} 占位符代表等式编号。

例: 'Eq.{number}' 被渲染为, 例如， Eq.10。

在 1.7 版本加入.

math_number_all¶

类型:: bool
默认:: False

强制对所有显示的方程式进行编号。例：

math_number_all = True

在 1.4 版本加入.

math_numfig¶

类型:: bool
默认:: True

如果为 True, 则在启用 numfig 时, 跨页对数学方程式进行编号。 numfig_secnum_depth 设置优先。必须使用 eq, 而不是 numref 角色来引用方程的编号。

在 1.7 版本加入.

math_numsep¶

类型:: str
默认:: '.'

一个字符串, 定义当启用 numfig 且 numfig_secnum_depth 为正时, 章节编号和方程编号之间的分隔符。

例: '-' 被渲染为 1.2-3。

在 7.4 版本加入.

用于nitpicky模式的选项¶

nitpicky¶

类型:: bool
默认:: False

如果为 True，则启用 nitpicky 模式。在 nitpicky 模式下，Sphinx 将警告所有找不到目标的引用。建议用于新项目，因为它确保所有引用均指向有效目标。

您可以使用命令行选项 --nitpicky 临时激活此模式。有关将缺失引用标记为“已知缺失”的方法，请参见 nitpick_ignore。

nitpicky = True

在 1.0 版本加入.

nitpick_ignore¶

类型:: set[tuple[str, str]] | Sequence[tuple[str, str]]
默认:: ()

在生成 “nitpicky 模式” 中的警告时, 应忽略的 (warning_type, target) 元组的集合或列表。请注意, warning_type 如果存在, 应包括域名。例：

nitpick_ignore = {
    ('py:func', 'int'),
    ('envvar', 'LD_LIBRARY_PATH'),
}

在 1.1 版本加入.

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

nitpick_ignore_regex¶

类型:: set[tuple[str, str]] | Sequence[tuple[str, str]]
默认:: ()

nitpick_ignore 的扩展版本, 其中 warning_type 和 target 字符串被解释为正则表达式。请注意, 正则表达式必须匹配整个字符串（就像插入了 ^ 和 $ 标记一样）。

例如, (r'py:.*', r'foo.*bar\.B.*') 将忽略所有以 'foo' 开头且包含 'bar.B' 的 python 实体的 nitpicky 警告, 例如 ('py:const', 'foo_package.bar.BAZ_VALUE') 或 ('py:class', 'food.bar.Barman')。

在 4.1 版本加入.

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

用于对象签名的选项¶

add_function_parentheses¶

类型:: bool
默认:: True

布尔值，用于决定是否在函数和方法角色文本(例如:func:`input`的内容)后附加括号以表示其是可调用的。

maximum_signature_line_length¶

类型:: int | None
默认:: None

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

当为 None 时，没有最大长度，整个签名将显示在单个逻辑行上。

'逻辑行'类似于硬换行——构建器或主题可以选择`软换行`单个逻辑行，此设置不影响该行为。

域可以提供选项以抑制单个对象指令上的任何硬换行, 例如在 C、C++ 和 Python 域中看到的（例如 py:function:single-line-parameter-list）。

在 7.1 版本加入.

strip_signature_backslash¶

类型:: bool
默认:: False

启用反斜杠剥离后，域指令中的每个 \\ 都将更改为 \，即使在字符串字面量中也是如此。这是 3.0 版本之前的行为，将此变量设置为 True 将恢复该行为。

在 3.0 版本加入.

toc_object_entries¶

类型:: bool
默认:: True

为域对象（例如函数、类、属性等）创建目录条目。

在 5.2 版本加入.

toc_object_entries_show_parents¶

类型:: 'domain' | 'hide' | 'all'
默认:: 'domain'

一个字符串，确定域对象（函数、类、属性等）在其目录条目中的显示方式。

使用 'domain' 允许域确定要显示的适当父级数量。例如，Python 域将显示 Class.method() 和 function()，省略 module. 级别的父级。

使用 'hide' 仅显示元素的名称，而不显示任何父级（即 method()）。

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

在 5.2 版本加入.

用于源文件的选项¶

exclude_patterns¶

类型:: Sequence[str]
默认:: ()

在查找源文件时应排除的 glob-style patterns 列表。它们与相对于源目录的源文件名进行匹配，在所有平台上使用斜杠作为目录分隔符。 exclude_patterns 优先于 include_patterns。

示例模式：

'library/xml.rst' -- 忽略 library/xml.rst 文件
'library/xml' -- 忽略 library/xml 目录
'library/xml*' -- 忽略所有以 library/xml 开头的文件和目录
'**/.git' -- 忽略所有 .git 目录
'Thumbs.db' -- 忽略所有 Thumbs.db 文件

exclude_patterns 也会被查询，当查找 html_static_path 和 html_extra_path 静态文件时

在 1.0 版本加入.

include_patterns¶

类型:: Sequence[str]
默认:: ('**',)

用于查找源文件的 glob-style patterns 列表。它们与相对于源目录的源文件名进行匹配，在所有平台上使用斜杠作为目录分隔符。默认情况下，从源目录递归包含所有文件。 exclude_patterns 优先于 include_patterns。

示例模式：

'**' -- 源目录和子目录中的所有文件，递归地
'library/xml' -- 仅仅是 library/xml 目录
'library/xml*' -- 所有以 library/xml 开头的文件和目录
'**/doc' -- 所有 doc 目录（如果文档与源文件共置，这可能很有用）

在 5.1 版本加入.

master_doc¶

root_doc¶

类型:: str
默认:: 'index'

Sphinx 基于源文件中包含的 toctree 指令构建文档树。此设置指定包含主 toctree 指令的文档的名称, 因此是整个树的根。例：

master_doc = 'contents'

在 2.0 版本发生变更: 默认值为 'index' （以前为 'contents'）。

在 4.0 版本加入: root_doc 别名。

source_encoding¶

类型:: str
默认:: 'utf-8-sig'

所有源文件的文件编码。推荐的编码是 'utf-8-sig'。

在 0.5 版本加入.

自 9.0 版本弃用: 对 UTF-8 以外的源编码的支持已被弃用。Sphinx 11 将仅支持 UTF-8 文件。

source_suffix¶

类型:: dict[str, str] | Sequence[str] | str
默认:: {'.rst': 'restructuredtext'}

将源文件的文件扩展名（后缀）映射到其文件类型的字典。Sphinx 将所有具有 source_suffix 中后缀的文件视为源文件。例：

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

默认情况下，Sphinx 仅支持 'restructuredtext' 文件类型。可以使用注册不同源文件解析器的扩展添加其他文件类型, 例如 MyST-Parser。请参阅扩展的文档以查看它支持哪些文件类型。

如果值是字符串或字符串序列，Sphinx 将认为它们都是 'restructuredtext' 文件。

备注

文件扩展名必须以点（'.'）开头。

在 1.3 版本发生变更: 支持文件扩展名列表。

在 1.8 版本发生变更: 更改为文件扩展名到文件类型的映射。

用于smart quotes的选项¶

smartquotes¶

类型:: bool
默认:: True

如果为 True, 将使用 Smart Quotes transform 将引号和破折号转换为排版正确的实体。

在 1.6.6 版本加入: 取代了现已删除的 html_use_smartypants。默认情况下, 它适用于除 man 和 text 之外的所有构建器（请参见 smartquotes_excludes）。

备注

位于配置目录中的 docutils.conf 文件（或全局 ~/.docutils 文件）无条件遵守, 如果它通过相应的 Docutils option 停用智能引号。但如果它*激活*它们, 则 smartquotes 确实占上风。

smartquotes_action¶

类型:: str
默认:: 'qDe'

自定义 Smart Quotes 转换。有关允许的代码, 请参见下文。默认的 'qDe' 教育普通 quote 字符 ", ', em- 和 en-Dashes ---, --, 和 ellipses .....

'q': 转换引号
'b': 转换反引号 (仅仅 ``double'')
'B': 转换反引号 (``double'' 和 `single')
'd': 转换破折号（将 -- 转换为em破折号，将 --- 转换为en破折号）
'D': 转换破折号（老式）（将 -- 转换为en破折号，将 --- 转换为em破折号）
'i': 转换破折号（反转的老式）（将 -- 转换为em破折号，将 --- 转换为en破折号）
'e': 转换省略号 ...
'w': 转换 '"' 实体为 '"'

在 1.6.6 版本加入.

smartquotes_excludes¶

类型:: dict[str, list[str]]
默认:: {'languages': ['ja'], 'builders': ['man', 'text']}

控制何时禁用 Smart Quotes 转换。允许的键是 'builders' 和 'languages'，值是字符串列表。

每个条目都提供了一个充分的条件来忽略 smartquotes 设置并停用 Smart Quotes 转换。例：

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

备注

目前，在使用多个目标调用 make 的情况下，只有第一个目标名称会针对 'builders' 条目进行测试，并决定所有目标。此外，紧随 make html 之后的 make text 需要以 make text SPHINXOPTS="-E" 的形式发出，以强制重新解析源文件, 因为缓存的文件已经被转换。另一方面，使用 sphinx-build 直接使用时不会出现此问题, 因为它在每个构建器位置缓存（在其默认用法中）解析的源文件。

提示

对于给定的构建器（例如 latex），有效地停用（或自定义）智能引号的另一种方法是使用 make 这种方式：

make latex SPHINXOPTS="-D smartquotes_action="

这可以跟随一些 make html 没有问题, 与前一条注释中的情况形成对比。

在 1.6.6 版本加入.

用于templating的选项¶

template_bridge¶

类型:: str
默认:: ''

一个带有可调用对象（或简单类）的完全限定名称的字符串, 返回 TemplateBridge 的实例。然后使用该实例来渲染 HTML 文档, 以及其他构建器的输出（当前为更改构建器）。（请注意, 如果要使用 HTML 主题, 则必须使模板桥接器具有主题感知能力。）例：

template_bridge = 'module.CustomTemplateBridge'

templates_path¶

类型:: Sequence[str]
默认:: ()

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

templates_path = ['.templates']

在 1.3 版本发生变更: 由于这些文件不打算被构建，所以在发现源文件时会自动排除它们。

用于warning控制的选项¶

show_warning_types¶

类型:: bool
默认:: True

将每个警告的类型作为后缀添加到警告消息中。例如, WARNING: [...] [index] 或 WARNING: [...] [toc.circular]。此设置对于确定要包含在 suppress_warnings 列表中的警告类型非常有用。

在 7.3.0 版本加入.

在 8.0.0 版本发生变更: 默认值现在是 True。

suppress_warnings¶

类型:: Sequence[str]
默认:: ()

一个列表，用于抑制任意警告消息的警告代码。

在 1.4 版本加入.

默认情况下，Sphinx 支持以下警告代码：

app.add_directive
app.add_generic_role
app.add_node
app.add_role
app.add_source_parser
config.cache
docutils
download.not_readable
duplicate_declaration.c
duplicate_declaration.cpp
epub.duplicated_toc_entry
epub.unknown_project_files
i18n.babel
i18n.inconsistent_references
i18n.not_readable
i18n.not_writeable
image.not_readable
index
misc.copy_overwrite
misc.highlighting_failure
ref.any
ref.citation
ref.doc
ref.equation
ref.footnote
ref.keyword
ref.numref
ref.option
ref.python
ref.ref
ref.term
source_code_parser.c
source_code_parser.cpp
toc.circular
toc.duplicate_entry
toc.empty_glob
toc.excluded
toc.no_title
toc.not_included
toc.not_readable
toc.secnum

扩展也可以定义它们自己的警告类型。由第一方 sphinx.ext 扩展定义的有：

autodoc
autodoc.import_object
autodoc.mocked_object
autosectionlabel.<document name>
autosummary
autosummary.import_cycle
duration
intersphinx.external

你可以从这些类型中进行选择。你也可以只给出第一个组件来排除所有附加到它的警告。

在 1.4 版本加入: ref.citation, ref.doc, ref.keyword, ref.numref, ref.option, ref.ref, 和 ref.term。

在 1.4.2 版本加入: app.add_directive, app.add_generic_role, app.add_node, app.add_role, 和 app.add_source_parser。

在 1.5 版本加入: misc.highlighting_failure。

在 1.5.1 版本加入: epub.unknown_project_files。

在 1.5.2 版本加入: toc.secnum。

在 1.6 版本加入: ref.footnote, download.not_readable, 和 image.not_readable。

在 1.7 版本加入: ref.python.

在 2.0 版本加入: autodoc.import_object.

在 2.1 版本加入: autosectionlabel.<document name>.

在 3.1 版本加入: toc.circular.

在 3.3 版本加入: epub.duplicated_toc_entry.

在 4.3 版本加入: toc.excluded 和 toc.not_readable。

在 4.5 版本加入: i18n.inconsistent_references。

在 7.1 版本加入: index。

在 7.3 版本加入: config.cache, intersphinx.external, 和 toc.no_title。

在 7.4 版本加入: docutils 和 autosummary.import_cycle。

在 8.0 版本加入: misc.copy_overwrite。

在 8.2 版本加入: autodoc.mocked_object, duplicate_declaration.c, duplicate_declaration.cpp, i18n.babel, i18n.not_readable, i18n.not_writeable, ref.any, toc.duplicate_entry, toc.empty_glob, 和 toc.not_included。

在 9.0 版本加入: duration。

构建器选项¶

用于HTML输出的选项¶

这些选项影响 HTML 输出。各种其他构建器都是从 HTML 输出派生的, 并且也利用这些选项。

html_theme¶

类型:: str
默认:: 'alabaster'

HTML 输出的主题。请参阅 HTML 主题部分。

在 0.6 版本加入.

在 1.3 版本发生变更: 默认主题现在是 'alabaster'。

html_theme_options¶

类型:: dict[str, Any]
默认:: {}

一个字典，包含影响所选主题外观和感觉的选项。这些是特定于主题的。内置主题所理解的选项在这里进行了描述。

在 0.6 版本加入.

html_theme_path¶

类型:: list[str]
默认:: []

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

在 0.6 版本加入.

html_style¶

类型:: Sequence[str] | str
默认:: ()

用于 HTML 页面的样式表。默认情况下使用所选主题提供的样式表, 该名称的文件必须存在于 Sphinx 的 static/ 路径中或在 html_static_path 中给出的自定义路径之一中。如果您只想添加或覆盖主题中的一些内容, 请使用 CSS @import 导入主题的样式表。

在 5.1 版本发生变更: 该值可以是字符串的可迭代对象。

html_title¶

类型:: str
默认:: 'project release documentation'

使用 Sphinx 自己的模板生成的 HTML 文档的“标题”。这将附加到各个页面的 <title> 标签中, 并在导航栏中用作“最顶部”的元素。

html_short_title¶

类型:: str
默认:: The value of html_title

HTML 文档的较短“标题”。这用于标题中的链接和 HTML 帮助文档中。

在 0.4 版本加入.

html_baseurl¶

类型:: str
默认:: ''

指向 HTML 文档根目录的基本 URL。它用于使用 the Canonical Link Relation 指示文档的位置。

在 1.8 版本加入.

html_codeblock_linenos_style¶

类型:: 'inline' | 'table'
默认:: 'inline'

代码块的行号样式。

'table': 使用 <table> tag显示行号
'inline': 使用 <span> tag显示行号

在 3.2 版本加入.

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

自 4.0 版本弃用.

html_context¶

类型:: dict[str, Any]
默认:: {}

一个字典，包含要传递到所有页面的模板引擎上下文中的值。也可以使用 sphinx-build 的 --html-define 命令行选项将单个值放入此字典中。

在 0.5 版本加入.

html_logo¶

类型:: str
默认:: ''

如果提供, 这必须是文档徽标的图像文件的名称（相对于配置目录的路径）, 或指向徽标图像文件的 URL。它放置在侧边栏的顶部；因此其宽度不应超过 200 像素。

在 0.4.1 版本加入: 图像文件将被复制到 _static 目录，但前提是该文件在那里尚不存在。

在 4.0 版本发生变更: 也接受一个URL。

html_favicon¶

类型:: str
默认:: ''

如果提供, 这必须是文档的favicon_的图像文件的名称（相对于配置目录的路径）, 或指向 favicon 图像文件的URL。浏览器将其用作选项卡、窗口和书签的图标。它应该是 PNG、SVG、GIF 或 ICO 文件格式的 16x16 像素图标。

举例如下：

html_favicon = 'static/favicon.png'

在 0.4 版本加入: 图像文件将被复制到 _static 目录，但前提是该文件在那里尚不存在。

在 4.0 版本发生变更: 也接受favicon的URL。

html_css_files¶

类型:: Sequence[str | tuple[str, dict[str, str]]]
默认:: []

CSS 文件的列表。条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典的元组。 filename 必须相对于 html_static_path, 或具有类似 'https://example.org/style.css' 方案的完整 URI。 attributes 字典用于 <link> 标签的属性。

举例如下：

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

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

在 1.8 版本加入.

在 3.5 版本发生变更: 支持 priority 属性

html_js_files¶

类型:: Sequence[str | tuple[str, dict[str, str]]]
默认:: []

JavaScript 文件的列表。条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典的元组。 filename 必须相对于 html_static_path, 或具有类似 'https://example.org/script.js' 方案的完整 URI。 attributes 字典用于 <script> 标签的属性。

举例如下：

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

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

在 1.8 版本加入.

在 3.5 版本发生变更: 支持 priority 属性

html_static_path¶

类型:: list[str]
默认:: []

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

由于这些文件不打算被构建，它们将自动从源文件中被排除。

备注

出于安全原因, html_static_path 下的dotfiles将不会被复制。如果您想有意地复制它们, 请将每个文件显式添加到此设置中：

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

另一种方法是使用 html_extra_path, 它允许复制目录下的dotfiles。

参见

add_static_dir(), for use in extensions to copy static files to the output directory.

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

在 1.0 版本发生变更: 以下条目 html_static_path 现在可以单目录。

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

html_extra_path¶

类型:: list[str]
默认:: []

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

由于这些文件不打算被构建，它们将自动从源文件中被排除。

在 1.2 版本加入.

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

html_last_updated_fmt¶

类型:: str
默认:: None

如果设置, 则使用给定的 strftime() 格式在页面页脚中插入“最后更新于:”时间戳。空字符串等同于 '%b %d, %Y' （或依赖于区域设置的等效项）。

html_last_updated_use_utc¶

类型:: bool
默认:: False

对于提供给 html_last_updated_fmt 的时间, 使用 GMT/UTC (+00:00) 而不是系统的本地时区。当使用的格式包含时间时, 这非常有用。

html_permalinks¶

类型:: bool
默认:: True

为每个标题和描述环境添加链接锚点。

在 3.5 版本加入.

html_permalinks_icon¶

类型:: str
默认:: '¶' (the paragraph sign)

每个标题和描述环境的链接锚点文本。允许使用 HTML 实体和 Unicode。

在 3.5 版本加入.

html_sidebars¶

类型:: dict[str, Sequence[str]]
默认:: {}

一个定义自定义侧边栏模板的字典，将文档名称映射到模板名称。例：

键可以包含 glob-style patterns，在这种情况下，所有匹配的文档都将获得指定的侧边栏。（当任何文档匹配多个通配符样式模式时，会发出警告。）

每个值必须是字符串列表，指定要包含的侧边栏模板的完整列表。如果要包含所有或某些默认侧边栏，它们也必须放入此列表中。

默认侧边栏（对于不匹配任何模式的文档）由主题本身定义。内置主题默认使用这些模板：'localtoc.html', 'relations.html', 'sourcelink.html', 和 'searchbox.html'。

捆绑的第一方侧边栏模板可以呈现为：

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

举例如下：

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

这将在给定文档的侧边栏中呈现自定义模板 windows-sidebar.html 和快速搜索框, 并为所有其他页面呈现默认侧边栏（除了本地目录被全局目录替换）。

请注意, 如果所选主题不具有侧边栏, 则此值仅无效, 例如内置**scrolls**和**haiku**。

在 1.0 版本加入: 能够使用通配键并指定多个侧边栏。

自 1.7 版本弃用: html_sidebars 的单个字符串值将被删除。

在 2.0 版本发生变更: html_sidebars 必须是字符串列表, 不再接受单个字符串值。

html_additional_pages¶

类型:: dict[str, str]
默认:: {}

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

举例如下：

html_additional_pages = {
    'download': 'custom-download.html.jinja',
}

这将把模板 custom-download.html.jinja 渲染为页面 download.html。

html_domain_indices¶

类型:: bool | Sequence[str]
默认:: True

如果为 True, 则生成特定于域的索引, 以及通用索引。

该值可以是布尔值或应生成的索引名称列表。要找出特定索引的索引名称, 请查看 HTML 文件名。例如, Python 模块索引的名称为 'py-modindex'。

举例如下：

html_domain_indices = {
    'py-modindex',
}

在 1.0 版本加入.

在 7.4 版本发生变更: 允许并优先使用集合类型。

html_use_index¶

类型:: bool
默认:: True

控制是否将索引添加到 HTML 文档中。

在 0.4 版本加入.

html_split_index¶

类型:: bool
默认:: False

生成索引的两个版本：一次作为包含所有条目的单个页面, 一次作为每个起始字母的一个页面。

在 0.4 版本加入.

html_copy_source¶

类型:: bool
默认:: True

如果为 True， reStructuredText 源包含在 HTML 构建中，作为 _sources/docname。

html_show_sourcelink¶

类型:: bool
默认:: True

如果为 True（并且 html_copy_source 也为真）, 则将链接到 reStructuredText 源添加到侧边栏。

在 0.6 版本加入.

html_sourcelink_suffix¶

类型:: str
默认:: '.txt'

要附加到源链接的后缀（请参阅 html_show_sourcelink）, 除非它们已经具有此后缀。

在 1.5 版本加入.

html_use_opensearch¶

类型:: str
默认:: ''

如果非空，会输出一个 OpenSearch 描述文件，并且所有页面都将包含一个 <link> 标签引用它。由于 OpenSearch 不支持其搜索页面位置的相对 URL，此选项的值必须是提供这些文档的基本 URL（不带尾部斜杠），例如 'https://docs.python.org'。

在 0.2 版本加入.

html_file_suffix¶

类型:: str
默认:: '.html'

生成的HTML文件的文件名后缀（文件扩展名）。

在 0.4 版本加入.

html_link_suffix¶

类型:: str
默认:: The value of html_file_suffix

生成的HTML文件链接的后缀。旨在支持更为复杂的服务器设置。

在 0.6 版本加入.

html_show_copyright¶

类型:: bool
默认:: True

如果为 True，HTML 页脚中将显示“© Copyright ...”，以及来自 copyright 的值。

在 1.0 版本加入.

html_show_search_summary¶

类型:: bool
默认:: True

显示搜索结果的摘要，即关键字周围的文本。

在 4.5 版本加入.

html_show_sphinx¶

类型:: bool
默认:: True

在HTML页脚中添加“Created using Sphinx”。

在 0.4 版本加入.

html_output_encoding¶

类型:: str
默认:: 'utf-8'

HTML 输出文件的编码。该编码名称必须既是有效的 Python 编码名称, 又是有效的 HTML charset 值。

在 1.0 版本加入.

html_compact_lists¶

类型:: bool
默认:: True

如果为 True，则其项目由单个段落和/或子列表组成的列表（递归定义）将不会为其任何项目使用 <p> 元素。这是标准的 docutils 行为。默认值： True。

在 1.0 版本加入.

html_secnumber_suffix¶

类型:: str
默认:: '. '

HTML输出中章节编号的后缀。设置为 ' ' 以抑制章节编号上的最后一个点。

在 1.0 版本加入.

html_search_language¶

类型:: str
默认:: The value of language

用于生成 HTML 全文搜索索引的语言。默认情况下, 选择使用 language 的全局语言。如果不支持此语言, 则使用英语（'en'）作为后备选项。

支持以下语言：

da -- 丹麦语
nl -- 荷兰语
en -- 英语
fi -- 芬兰语
fr -- 法语
de -- 德语
hu -- 匈牙利语
id -- 印度尼西亚语
ja -- 日语
no -- 挪威语
pt -- 葡萄牙语
ro -- 罗马尼亚语
ru -- 俄语
es -- 西班牙语
sv -- 瑞典语
tr -- 土耳其语
zh -- 中文

小技巧

加快构建速度

每种语言（除日语外）都提供自己的词干提取算法。Sphinx 默认使用 Python 实现。如果要加快索引文件的构建, 可以通过运行 pip install PyStemmer 使用第三方包 (PyStemmer)。

在 1.1 版本加入: 支持英语（en）和日语（ja）。

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

html_search_options¶

类型:: dict[str, str]
默认:: {}

一个包含搜索语言支持选项的字典。这些选项的含义取决于所选择的语言。目前, 只有日语和中文支持选项。

日语:

type -- 要使用的拆分器类型。

所使用的拆分器取决于其他选项。

'sphinx.search.ja.DefaultSplitter': 默认使用的 TinySegmenter 算法。
'sphinx.search.ja.MecabSplitter':: MeCab 绑定要使用此拆分器, 需要 'mecab' python 绑定或动态链接库（Linux 的 'libmecab.so', Windows 的 'libmecab.dll'）。
'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:: lib option 是用于通过 ctypes 查找 MeCab 库的库名称（如果未安装 Python 绑定）。

例如：

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'。

中文:

dict: 使用自定义词典的 jieba 词典路径。

在 1.1 版本加入.

在 1.4 版本发生变更: 允许在日语的 type 设置中使用任何自定义拆分器。

html_search_scorer¶

类型:: str
默认:: ''

实现搜索结果评分器的 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,
};

在 1.2 版本加入.

html_scaled_image_link¶

类型:: bool
默认:: True

将使用缩放选项（scale、width 或 height）调整大小的图像链接到其原始全分辨率图像。如果存在, 这不会覆盖 image 指令上 target 选项提供的任何链接。

小技巧

向图像指令添加 no-scaled-link 类，以逐个图像禁用此功能：

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

在 1.3 版本加入.

在 3.0 版本发生变更: no-scaled-link 类的图像将不会被链接。

html_math_renderer¶

类型:: str
默认:: 'mathjax'

用于HTML输出的数学渲染器。捆绑的渲染器是 mathjax 和 imgmath。您还必须在 extensions 中加载相关扩展。

在 1.8 版本加入.

用于单一HTML输出的选项¶

这些选项影响单一HTML输出。此构建器派生自HTML构建器，因此HTML选项在适当的情况下也适用。

singlehtml_sidebars¶

类型:: dict[str, Sequence[str]]
默认:: The value of html_sidebars

一个定义自定义侧边栏模板的字典，将文档名称映射到模板名称。例：

这与 html_sidebars 具有相同的效果, 但唯一允许的键是 'index', 并且忽略所有其他键。

用于HTML help输出选项¶

这些选项影响HTML帮助输出。此构建器派生自HTML构建器，因此HTML选项在适当的情况下也适用。

htmlhelp_basename¶

类型:: str
默认:: '{project}doc'

HTML帮助构建器的输出文件基本名称。默认值是 project name 并删除空格并附加 doc。

htmlhelp_file_suffix¶

类型:: str
默认:: '.html'

生成的HTML帮助文件的文件名后缀。

在 2.0 版本加入.

htmlhelp_link_suffix¶

类型:: str
默认:: The value of htmlhelp_file_suffix

生成的链接到HTML文件的后缀。

在 2.0 版本加入.

用于Apple Help输出选项¶

在 1.3 版本加入.

这些选项影响Apple Help输出。此构建器派生自HTML构建器，因此HTML选项在适当的情况下也适用。

备注

Apple Help 输出仅适用于 Mac OS X 10.6 及更高版本, 因为它需要 hiutil 和 codesign 命令行工具, 这两个工具都不是开源的。

您可以使用 applehelp_disable_external_tools 禁用这些工具的使用, 但在对包内的 .lproj 目录运行索引器之前, 结果将不是有效的帮助手册。

applehelp_bundle_name¶

类型:: str
默认:: The value of project

Apple Help Book的basename。默认值是 project name 并删除空格。

applehelp_bundle_id¶

类型:: str
默认:: None

帮助手册包的软件包ID。

警告

您必须设置此值才能生成Apple帮助。

applehelp_bundle_version¶

类型:: str
默认:: '1'

帮助手册包的版本，作为字符串。

applehelp_dev_region¶

类型:: str
默认:: 'en-us'

开发区域。默认为 Apple 推荐的设置, 'en-us'。

applehelp_icon¶

类型:: str
默认:: None

帮助手册包图标文件的路径或 None 表示没有图标。根据 Apple 的文档, 这应该是应用程序图标的 16x16 像素版本, 具有透明背景, 并保存为 PNG 文件。

applehelp_kb_product¶

类型:: str
默认:: 'project-release'

和 applehelp_kb_url 一起使用的产品标签。

applehelp_kb_url¶

类型:: str
默认:: None

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

将此设置为 None 以禁用远程搜索。

applehelp_remote_url¶

类型:: str
默认:: None

远程内容的URL。您可以将帮助手册的 Resources 目录的副本放在此位置, 并且帮助查看器将尝试使用它来获取更新的内容。

例如, 如果将其设置为 https://example.com/help/Foo/, 并且帮助查看器想要为讲英语的客户提供 index.html 的副本, 它将查看 https://example.com/help/Foo/en.lproj/index.html。

如果没有远程内容, 将此设置为 None。

applehelp_index_anchors¶

类型:: bool
默认:: False

告诉帮助索引器索引生成的HTML中的锚点。这对于使用 AHLookupAnchor 函数或代码中的 openHelpAnchor:inBook: 方法跳转到特定主题非常有用。它还允许您使用 help:anchor URL；有关此主题的更多信息, 请参阅 Apple 文档。

applehelp_min_term_length¶

类型:: str
默认:: None

控制帮助索引器的最小术语长度。如果为 None, 则使用默认长度。

applehelp_stopwords¶

类型:: str
默认:: The value of language

要么是语言规范（以使用内置的停用词）, 要么是停用词 plist 的路径, 或者如果您不想使用停用词, 则为 None。默认的停用词 plist 可以在 /usr/share/hiutil/Stopwords.plist 找到, 截至撰写本文时, 包含以下语言的停用词：

德语 (de)
英语 (en)
西班牙语 (es)
法语 (fr)
匈牙利语 (hu)
意大利语 (it)
瑞典语 (sv)

applehelp_locale¶

类型:: str
默认:: The value of language

指定要生成帮助的区域设置。这用于确定帮助手册 Resources 内的 .lproj 目录的名称, 并传递给帮助索引器。

applehelp_title¶

类型:: str
默认:: 'project Help'

指定帮助手册标题。

applehelp_codesign_identity¶

类型:: str
默认:: The value of CODE_SIGN_IDENTITY

指定用于代码签名的身份。如果不执行代码签名, 则使用 None。

默认为 CODE_SIGN_IDENTITY 环境变量的值, 该变量由 Xcode 为脚本构建阶段设置, 如果未设置该变量, 则为 None。

applehelp_codesign_flags¶

类型:: list[str]
默认:: The value of OTHER_CODE_SIGN_FLAGS

签署帮助手册时要传递给 codesign 的附加参数的 list。

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

applehelp_codesign_path¶

类型:: str
默认:: '/usr/bin/codesign'

codesign 程序的路径。

applehelp_indexer_path¶

类型:: str
默认:: '/usr/bin/hiutil'

hiutil 程序的路径。

applehelp_disable_external_tools¶

类型:: bool
默认:: False

无论指定了什么其他设置, 都不要运行索引器或代码签名工具。

主要用于测试, 或者当您想在非macOS平台上运行Sphinx构建, 然后出于某种原因在Mac上完成最后的步骤时。

用于EPUB输出的选项¶

这些选项影响EPUB输出。该构建器派生自HTML构建器, 因此HTML选项在适当的情况下也适用。

备注

某些选项的实际值并不重要, 但它们是 Dublin Core metadata 所必需的。

epub_basename¶

类型:: str
默认:: The value of project

EPUB文件的basename。

epub_theme¶

类型:: str
默认:: 'epub'

EPUB输出的HTML主题。由于默认主题未针对较小的屏幕空间进行优化, 因此将HTML和EPUB输出使用相同的主题通常是不明智的。它默认为 'epub', 这是一个旨在节省视觉空间的主题。

epub_theme_options¶

类型:: dict[str, Any]
默认:: {}

一个字典，包含影响所选主题外观和感觉的选项。这些是特定于主题的。内置主题所理解的选项在这里进行了描述。

在 1.2 版本加入.

epub_title¶

类型:: str
默认:: The value of project

文档的标题。

在 2.0 版本发生变更: 它默认为 project 选项（以前为 html_title）。

epub_description¶

类型:: str
默认:: 'unknown'

对文档的描述。

在 1.4 版本加入.

在 1.5 版本发生变更: 重命名自 epub3_description

epub_author¶

类型:: str
默认:: The value of author

文档的作者。这被放在Dublin Core metadata中。

epub_contributor¶

类型:: str
默认:: 'unknown'

在创建EPUB出版物内容中扮演次要角色的个人、组织等的名称。

在 1.4 版本加入.

在 1.5 版本发生变更: 重命名自 epub3_contributor

epub_language¶

类型:: str
默认:: The value of language

该文档的语言。它被放在Dublin Core metadata中。

epub_publisher¶

类型:: str
默认:: The value of author

该文档的发布者。这被放在Dublin Core metadata中。您可以使用任何合理的字符串, 例如项目主页。

epub_copyright¶

类型:: str
默认:: The value of copyright

该文档的版权。有关允许的格式，请参见 copyright。

epub_identifier¶

类型:: str
默认:: 'unknown'

文档的标识符。这被放在Dublin Core metadata中。对于已发布的文档, 这是ISBN号码, 但您也可以使用替代方案, 例如项目主页。

epub_scheme¶

类型:: str
默认:: 'unknown'

epub_identifier 的出版方案。这被放在Dublin Core metadata中。对于已发布的书籍, 该方案是 'ISBN'。如果您使用项目主页, 'URL' 似乎是合理的。

epub_uid¶

类型:: str
默认:: 'unknown'

文档的唯一标识符。这被放在Dublin Core metadata中。您可以使用 XML's Name format 字符串。您不能使用连字符、句点、数字作为第一个字符。

epub_cover¶

类型:: tuple[str, str]
默认:: ()

封面页信息。这是一个包含封面图像和html模板文件名的元组。渲染的html封面页作为 content.opf 中主轴的第一项插入。如果模板文件名为空, 则不创建html封面页。如果元组为空, 则根本不创建封面。

示例：

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

在 1.1 版本加入.

epub_css_files¶

类型:: Sequence[str | tuple[str, dict[str, str]]]
默认:: []

CSS 文件列表。条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典的元组。filename 必须相对于 html_static_path, 或者是带有类似 'https://example.org/style.css' 方案的完整 URI。attributes 字典用于 <link> 标签的属性。有关更多信息, 请参见 html_css_files。

在 1.8 版本加入.

epub_guide¶

类型:: Sequence[tuple[str, str, str]]
默认:: ()

content.opf 的 guide 元素的元数据。这是包含可选指南信息的 type、uri 和 title 的元组序列。有关详细信息, 请参阅 the OPF documentation。如果可能, cover 和 toc 类型的默认条目会自动插入。但是, 如果默认条目不合适, 则可以显式覆盖这些类型。

举例如下：

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

默认值为 ()。

epub_pre_files¶

类型:: Sequence[tuple[str, str]]
默认:: ()

应在 Sphinx 生成的文本之前插入的其他文件。这是一个包含文件名和标题的元组列表。如果标题为空, 则不会向 toc.ncx 添加条目。

举例如下：

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

epub_post_files¶

类型:: Sequence[tuple[str, str]]
默认:: ()

应在 Sphinx 生成的文本之后插入的其他文件。这是一个包含文件名和标题的元组列表。此选项可用于添加附录。如果标题为空, 则不会向 toc.ncx 添加条目。

举例如下：

epub_post_files = [
    ('appendix.xhtml', 'Appendix'),
]

epub_exclude_files¶

类型:: Sequence[str]
默认:: []

一个文件序列，这些文件在构建目录中生成/复制，但不应包含在 EPUB 文件中。

epub_tocdepth¶

类型:: int
默认:: 3

toc.ncx 文件中的目录深度。它应该是一个大于零的整数。

小技巧

一个深度嵌套的目录可能难以导航。

epub_tocdup¶

类型:: bool
默认:: True

此标志确定是否在其嵌套的目录列表的开头再次插入目录条目。这允许更容易地导航到章节的顶部，但可能会令人困惑，因为它将不同深度的条目混合在一个列表中。

epub_tocscope¶

类型:: 'default' | 'includehidden'
默认:: 'default'

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

'default': 包含所有未隐藏的目录条目
'includehidden': 包含所有目录条目

在 1.2 版本加入.

epub_fix_images¶

类型:: bool
默认:: False

尝试修复某些EPUB阅读器不支持的图像格式。目前, 具有小颜色表的调色板图像已升级。默认情况下禁用此功能, 因为自动转换可能会丢失信息。您需要安装Python Image Library (Pillow)才能使用此选项。

在 1.2 版本加入.

epub_max_image_width¶

类型:: int
默认:: 0

此选项指定图像的最大宽度。如果将其设置为大于零的值, 则宽度大于给定值的图像将相应地缩放。如果为零, 则不执行缩放。您需要安装Python Image Library (Pillow)才能使用此选项。

在 1.2 版本加入.

epub_show_urls¶

类型:: 'footnote' | 'no' | 'inline'
默认:: 'footnote'

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

'inline': 在括号中内联显示 URL。
'footnote': 在脚注中显示 URL。
'no': 不显示 URL。

内联 URL 的显示可以通过为 link-target 类添加 CSS 规则来定制。

在 1.2 版本加入.

epub_use_index¶

类型:: bool
默认:: The value of html_use_index

向 EPUB 文档添加索引。

在 1.2 版本加入.

epub_writing_mode¶

类型:: 'horizontal' | 'vertical'
默认:: 'horizontal'

指定书写方向。它可以接受 'horizontal' 和 'vertical'

`epub_writing_mode`	`'horizontal'`	`'vertical'`
writing-mode	`horizontal-tb`	`vertical-rl`
page progression	left to right	right to left
iBook's 滚动主题支持	scroll-axis 是垂直的。	scroll-axis 是水平的。

用于LaTeX输出的选项¶

这些选项会影响LaTeX输出。

latex_engine¶

类型:: 'pdflatex' | 'xelatex' | 'lualatex' | 'platex' | 'uplatex'
默认:: 'pdflatex'

构建文档所使用的 LaTeX 引擎。该设置可以是以下值：

'pdflatex' -- PDFLaTeX (默认)
'xelatex' -- XeLaTeX (如果 language 是 el, zh_CN, 或 zh_TW 则为默认)
'lualatex' -- LuaLaTeX
'platex' -- pLaTeX
'uplatex' -- upLaTeX (如果 language 是 'ja' 则为默认)

重要

'pdflatex' 对 Unicode 字符的支持有限。如果您的项目使用 Unicode 字符, 将引擎设置为 'xelatex' 或 'lualatex', 并确保使用具有足够宽字形覆盖范围的 OpenType 字体, 通常比尝试使 'pdflatex' 与额外的 Unicode 字符一起工作更容易。自 Sphinx 2.0 起, 默认字体是 GNU FreeFont, 它对拉丁文、西里尔文和希腊字形有很好的覆盖。

备注

Sphinx 2.0 为使用拉丁语言和 'pdflatex' 的文档添加了对偶尔出现的西里尔字母和希腊字母或单词的支持。要启用此功能, 必须适当地使用 latex_elements 配置设置的 'fontenc' 键。

备注

与 HTML 输出中的 MathJaX 数学渲染相反, LaTeX 需要一些额外的配置来支持在 math 中的 Unicode 字面值：唯一全面的解决方案（据我们所知）是使用 'xelatex' 或 'lualatex' 和添加 r'\usepackage{unicode-math}' （例如通过 latex_elements 配置设置的 'preamble' 键）。您可能更喜欢 r'\usepackage[math-style=literal]{unicode-math}' 来保持 Unicode 字面值（例如 α (U+03B1)）在输出中保持不变, 而不是被渲染为 $\alpha$。

在 2.1.0 版本发生变更: 对于中文文档，默认使用 'xelatex' （和 LaTeX 包 xeCJK）。

在 2.2.1 版本发生变更: 对于希腊文文档，默认使用 'xelatex'。

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

在 4.0 版本发生变更: 对于日文文档，默认使用 'uplatex'。

latex_documents¶

类型:: Sequence[tuple[str, str, str, str, str, bool]]
默认:: The default LaTeX documents

此值确定如何将文档树分组为LaTeX源文件。它必须是元组列表“(startdocname, targetname, title, author, theme, toctree_only)”, 其中的项目是:

startdocname: 字符串，指定 LaTeX 文件主文档的 document name。startdoc 文档在目录树中引用的所有文档都将包含在 LaTeX 文件中。(如果您想为 LaTeX 构建使用默认主文档, 请在此处提供您的 master_doc。)
targetname: 输出目录中LaTeX文件的文件名。
title: LaTeX 文档标题。可以为空以使用 startdoc 文档的标题。这作为 LaTeX 标记插入, 因此如果要逐字插入, 则必须使用适当的 LaTeX 命令来表示反斜杠或和号等特殊字符。
author: LaTeX 文档的作者。与 title 相同的 LaTeX 标记警告适用。使用 \\and 来分隔多个作者, 如: 'John \\and Sarah' (反斜杠必须经过 Python 转义才能到达 LaTeX)。
theme: LaTeX 主题。请参阅 latex_theme。
toctree_only: 必须是 True 或 False。如果为 True，则不包括 startdoc 文档本身在输出中，而只包括它通过 ToC 树引用的文档。使用此选项，您可以将额外的内容放入主文档中，这些内容会显示在 HTML 中，但不会显示在 LaTeX 输出中。

在 0.3 版本加入: 第6项 toctree_only。仍然接受包含5个项的元组。

在 1.2 版本加入: 过去，包含自己的文档类需要在文档类名前加上字符串“sphinx”。现在这已经没有必要了。

latex_logo¶

类型:: str
默认:: ''

如果给出, 则这必须是图像文件的名称（相对于配置目录的路径）, 它是文档的徽标。它放置在标题页的顶部。

latex_toplevel_sectioning¶

类型:: 'part' | 'chapter' | 'section'
默认:: None

此值确定最顶层的分节单元。如果 latex_theme 是 'howto'，则默认设置为 'section'，如果是 'manual'，则为 'chapter'。两种情况下的替代方案都是指定 'part'，这意味着 LaTeX 文档将使用 \part 命令。

在这种情况下，一层深的分节单元的编号与 HTML 编号不同步，因为默认情况下，LaTeX 在遇到 \part 命令时不会重置 \chapter 编号（或 \section 用于 'howto' 主题）。

在 1.4 版本加入.

latex_appendices¶

类型:: Sequence[str]
默认:: ()

作为附录附加到所有手册的文档名称列表。如果 latex_theme 设置为 'howto'，则忽略此选项。

latex_domain_indices¶

类型:: bool | Sequence[str]
默认:: True

如果为 True, 则生成特定于域的索引, 以及通用索引。

该值可以是布尔值或应生成的索引名称列表。要找出特定索引的索引名称, 请查看 HTML 文件名。例如, Python 模块索引的名称为 'py-modindex'。

举例如下：

latex_domain_indices = {
    'py-modindex',
}

在 1.0 版本加入.

在 7.4 版本发生变更: 允许并优先使用集合类型。

latex_show_pagerefs¶

类型:: bool
默认:: False

在内部引用后添加页面引用。这对于手册的打印副本非常有用。

在 1.0 版本加入.

latex_show_urls¶

类型:: 'no' | 'footnote' | 'inline'
默认:: 'no'

控制如何显示URL地址。这对于手册的打印副本非常有用。该设置可以具有以下值:

'no': 不显示URL
'footnote': 在脚注中显示URL
'inline': 在括号中内联显示URL

在 1.0 版本加入.

在 1.1 版本发生变更: 此值现在是一个字符串; 以前它是一个布尔值，true 值选择 'inline' 显示。为了向后兼容，仍然接受 True。

latex_use_latex_multicolumn¶

类型:: bool
默认:: False

在表格中使用标准 LaTeX 的 \multicolumn 进行合并单元格。

False: Sphinx 自己的宏用于网格表中的合并单元格。它们允许一般内容（文字块、列表、引用块等），但如果使用 tabularcolumns 指令注入类型为 >{..}, <{..}, @{..} 的 LaTeX 标记作为列规范，则可能会出现问题。
True: 使用 LaTeX 的标准 \multicolumn; 这与水平合并单元格中的文字块不兼容，如果使用 tabulary 渲染表格，这种单元格中的多个段落也不兼容。

在 1.6 版本加入.

latex_table_style¶

类型:: list[str]
默认:: ['booktabs', 'colorrows']

当前支持的样式类（字符串）列表：

'booktabs': 不使用垂直线，并且仅使用2或3条水平线（如果有标题则为后者），使用 booktabs 包。
'borderless': 完全没有线条。
'colorrows': 表格行以交替的背景颜色呈现。自定义它们的界面是通过 sphinxsetup 配置设置的 dedicated keys。

重要

使用 'colorrows' 样式时，\rowcolors LaTeX 命令变为无操作（此命令有局限性，并且从未正确支持 Sphinx 在 LaTeX 中生成的所有类型的表格）。请改用 latex table color configuration 键。

要自定义表格的样式, 如果使用指令定义表格, 请使用 :class: 选项, 否则请在表格前插入 rst-class 指令 (参见表格)。

当前识别的类有 booktabs, borderless, standard, colorrows, nocolorrows。后两者可以与前三者中的任何一个结合使用。 standard 类生成具有水平和垂直线的表格（这是 Sphinx 6.0.0 之前的默认设置）。

单行多l列合并单元格将遵守行颜色（如果设置了）。另请参见 sphinxsetup 配置设置部分中的 TableMergeColor{Header,Odd,Even}。

备注

在 LaTeX 中, 即使通过列规范（请参见 tabularcolumns）设置了列颜色, 单个单元格也会遵守行颜色。Sphinx 提供了 \sphinxnorowcolor, 可以在表格列规范中使用，如下所示：
```
>{\columncolor{blue}\sphinxnorowcolor}
```
Sphinx 还提供了 \sphinxcolorblend, 但它需要 xcolor 包。以下是一个示例：
```
>{\sphinxcolorblend{!95!red}}
```
这意味着在此列中，行颜色将被红色轻微染色；有关其 \blendcolors 命令语法的更多信息，请参阅 xcolor 文档（\blendcolors 替代 \sphinxcolorblend 将修改单元格内容的颜色, 而不是单元格 背景颜色面板...）。您可以在本文件的 PDF 格式的弃用的接口部分中找到使用示例。

提示

如果您想为给定列的单元格的内容使用特殊颜色, 请使用 >{\noindent\color{<color>}}, 可能还需要添加上述内容。
无论是单列还是多列, 多行合并单元格目前都忽略任何设置的列、行或单元格颜色。
简单单元格可以通过 raw 指令和单元格内容中任何位置使用的 \cellcolor LaTeX 命令来设置自定义颜色。这在合并单元格中目前无效, 无论其类型如何。

提示

在未全局使用 'booktabs' 的文档中, 可以通过 booktabs 类为单个表格设置样式, 但需要将 r'\usepackage{booktabs}' 添加到 LaTeX 前言中。

另一方面，可以使用 colorrows 类为单个表格使用，无需额外的软件包（因为 Sphinx 自 5.3.0 起始终加载 colortbl）。

在 5.3.0 版本加入.

在 6.0.0 版本发生变更: 将默认值从 [] 修改为 ['booktabs', 'colorrows']。

latex_use_xindy¶

类型:: bool
默认:: True if latex_engine in {'xelatex', 'lualatex'} else False

使用 Xindy 来准备一般术语的索引。默认情况下, LaTeX 构建器使用 makeindex 来准备一般术语的索引。使用 Xindy 意味着具有 UTF-8 字符的单词将根据 language 正确排序。

如果 latex_engine 是 'platex' （日文文档；mendex 取代 makeindex），则忽略此选项。
对于 'xelatex' 或 'lualatex', 默认值为 True, 因为如果任何索引术语以非 ASCII 字符开头, makeindex 会创建包含无效字节的 .ind 文件。使用 'lualatex' 会破坏 PDF 构建。
对于 'pdflatex', 默认值为 False, 但对于非英语文档, 只要一些索引术语使用来自语言脚本的非 ASCII 字符, 就建议使用 True。如果索引的术语的第一个字符是非 ASCII, 则如果 latex_use_xindy 保持为其默认的 False, 则会破坏构建。

Sphinx 为使用 'pdflatex' 引擎与西里尔字母脚本的 xindy 基础发行版添加了一些专用支持。使用 'pdflatex' 和 Unicode 引擎的西里尔文档都能正确处理拉丁名称的索引, 即使是那些带有变音符号的名称。

在 1.8 版本加入.

latex_elements¶

类型:: dict[str, str]
默认:: {}

在 0.5 版本加入.

请参阅 latex_elements 的完整文档。

latex_docclass¶

类型:: dict[str, str]
默认:: {}

一个字典, 将 'howto' 和 'manual' 映射到将用作两个 Sphinx 类基础的真实文档类的名称。默认情况下, 对于 'howto' 使用 'article', 对于 'manual' 使用 'report'。

在 1.0 版本加入.

在 1.5 版本发生变更: 在日文档 (language 为 'ja') 中, 默认情况下, 对于 'howto' 使用 'jreport', 对于 'manual' 使用 'jsbook'。

latex_additional_files¶

类型:: Sequence[str]
默认:: ()

一个文件名列表, 相对于配置目录, 在构建 LaTeX 输出时复制到构建目录。这对于复制 Sphinx 不会自动复制的文件或使用自定义版本覆盖 Sphinx LaTeX 支持文件非常有用。在源文件中引用的图像文件（例如通过 .. image::）会自动复制, 不应在此列出。

注意

具有 .tex 扩展名的文件名将自动移交给由 sphinx-build -M latexpdf 或 make latexpdf 触发的 PDF 构建过程。如果该文件仅被添加为从修改后的前言中 \input{}，则必须向文件名添加进一步的后缀（例如 .txt），并相应地调整 \input{} 宏。

在 0.6 版本加入.

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

latex_theme¶

类型:: str
默认:: 'manual'

LaTeX 输出应使用的“主题”。它是 LaTeX 输出的一组设置（例如文档类、顶级分节单元等）。

自带的第一方LaTeX主题是 manual 和 howto :

manual: 用于编写manual类型文档的LaTeX主题。它导入了 report 文档类（日本文档使用 jsbook）。
howto: 用于编写article类型文档的LaTeX主题。它导入了 article 文档类（日本文档使用 jreport）。 latex_appendices 仅适用于此主题。

在 3.0 版本加入.

latex_theme_options¶

类型:: dict[str, Any]
默认:: {}

一个字典, 其中包含影响所选主题外观和感觉的选项。这些是特定于主题的。

在 3.1 版本加入.

latex_theme_path¶

类型:: list[str]
默认:: []

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

在 3.0 版本加入.

用于text输出的选项¶

这些选项会影响文本输出。

text_add_secnumbers¶

类型:: bool
默认:: True

在文本输出中包含章节编号。

在 1.7 版本加入.

text_newlines¶

类型:: 'unix' | 'windows' | 'native'
默认:: 'unix'

确定在文本输出中使用哪个行尾字符。

'unix': 使用Unix风格的行结尾（ \n ）。
'windows': 使用Windows风格的行结尾（ \r\n ）。
'native': 使用构建文档的平台的行结尾样式。

在 1.1 版本加入.

text_secnumber_suffix¶

类型:: str
默认:: '. '

文本输出中章节编号的后缀。设置为 ' ' 以抑制章节编号上的最后一个点。

在 1.7 版本加入.

text_sectionchars¶

类型:: str
默认:: '*=-~"+`'

一个7个字符的字符串, 应该用于下划线部分。第一个字符用于第一级标题, 第二个字符用于第二级标题, 依此类推。

在 1.1 版本加入.

用于手动页面输出的选项¶

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

man_pages¶

类型:: Sequence[tuple[str, str, str, str, str]]
默认:: The default manual pages

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

startdocname: 字符串，指定手册页面主文档的 document name 。所有由 startdoc 文档在 ToC 树中引用的文档都将包含在手册页面中。（如果您想使用手册页面构建的默认主文档，请在此处提供您的 master_doc 。）
name: 手册页面的名称。这应该是一个没有空格或特殊字符的简短字符串。它用于确定文件名以及手册页面的名称（在 NAME 部分中）。
description: 手册页面的描述。这用于 NAME 部分。如果您不想自动生成 NAME 部分，则可以是一个空字符串。
authors: 包含作者的字符串列表，或单个字符串。如果您不想在手册页面中自动生成 AUTHORS 部分，则可以是一个空字符串或列表。
section: 手册页面部分。用于输出文件名以及手册页面标题中。

在 1.0 版本加入.

man_show_urls¶

类型:: bool
默认:: False

在链接后添加URL地址。

在 1.1 版本加入.

man_make_section_directory¶

类型:: bool
默认:: True

在构建手册页面时创建一个章节目录。

在 3.3 版本加入.

在 4.0 版本发生变更: 默认值现在是 False （以前是 True）。

在 4.0.2 版本发生变更: 恢复默认值的更改。

用于Texinfo输出的选项¶

这些选项会影响Texinfo输出。

texinfo_documents¶

类型:: Sequence[tuple[str, str, str, str, str, str, str, bool]]
默认:: The default Texinfo documents

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

startdocname: 字符串，指定 Texinfo 文件主文档的 document name 。所有由 startdoc 文档在 ToC 树中引用的文档都将包含在 Texinfo 文件中。（如果您想使用 Texinfo 构建的默认主文档，请在此处提供您的 master_doc 。）
targetname: 输出目录中Texinfo文件的文件名（无扩展名）。
title: Texinfo 文档标题。可以为空以使用 startdoc 文档的标题。作为 Texinfo 标记插入，因此需要转义 @ 和 {} 等特殊字符才能逐字插入。
author: Texinfo 文档的作者。作为 Texinfo 标记插入。使用 @* 分隔多个作者，例如： 'John@*Sarah' 。
dir_entry: 将出现在顶级“DIR”菜单文件中的名称。
description: 描述性文本出现在顶级“DIR”菜单文件中。
category: 指定此条目将出现在顶级“DIR”菜单文件中的部分。
toctree_only: 必须是 True 或 False 。如果为 True，则不包括 startdoc 文档本身在输出中，只有通过 ToC 树引用的文档。使用此选项，您可以将额外的内容放入主文档中，这些内容会显示在 HTML 中，但不会显示在 Texinfo 输出中。

在 1.1 版本加入.

texinfo_appendices¶

类型:: Sequence[str]
默认:: []

要作为所有手册的附录附加的文档名称列表。

在 1.1 版本加入.

texinfo_cross_references¶

类型:: bool
默认:: True

在文档中生成内联引用。禁用内联引用可以使信息文件在独立阅读器（info）中更易读。

在 4.4 版本加入.

texinfo_domain_indices¶

类型:: bool | Sequence[str]
默认:: True

如果为 True, 则生成特定于域的索引, 以及通用索引。

该值可以是布尔值或应生成的索引名称列表。要找出特定索引的索引名称, 请查看 HTML 文件名。例如, Python 模块索引的名称为 'py-modindex'。

举例如下：

texinfo_domain_indices = {
    'py-modindex',
}

在 1.1 版本加入.

在 7.4 版本发生变更: 允许并优先使用集合类型。

texinfo_elements¶

类型:: dict[str, Any]
默认:: {}

一个包含 Texinfo 片段的字典，这些片段覆盖了 Sphinx 通常放入生成的 .texi 文件中的片段。

您可能想要覆盖的键包括：

'paragraphindent'
每个段落的第一行缩进的空格数，默认为 2。指定 0 表示不缩进。

'exampleindent'
用于缩进示例或文字块行的空格数，默认为 4。指定 0 表示不缩进。

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

'copying'
Texinfo 标记插入 @copying 块中，并显示在标题之后。默认值由一个简单的标题页组成，用于识别项目。
由其他选项设置的键，因此不应被覆盖的是 'author'、 'body'、 'date'、 'direntry' 'filename'、 'project'、 'release' 和 'title' 。

在 1.1 版本加入.

texinfo_no_detailmenu¶

类型:: bool
默认:: False

不要在“Top”节点的菜单中生成包含每个子节点条目的 @detailmenu 。

在 1.2 版本加入.

texinfo_show_urls¶

类型:: 'footnote' | 'no' | 'inline'
默认:: 'footnote'

控制如何显示URL地址。该设置可以具有以下值：

'footnote': 在脚注中显示 URL。
'no': 不显示 URL。
'inline': 在括号中内联显示 URL。

在 1.1 版本加入.

用于QtHelp输出的选项¶

这些选项会影响qthelp输出。此构建器派生自HTML构建器，因此HTML选项在适当的情况下也适用。

qthelp_basename¶

类型:: str
默认:: The value of project

qthelp文件的basename。

qthelp_namespace¶

类型:: str
默认:: 'org.sphinx.{project_name}.{project_version}'

qthelp文件的命名空间。

qthelp_theme¶

类型:: str
默认:: 'nonav'

qthelp输出的HTML主题。

qthelp_theme_options¶

类型:: dict[str, Any]
默认:: {}

一个字典，包含影响所选主题外观和感觉的选项。这些是特定于主题的。内置主题所理解的选项在这里进行了描述。

用于XML输出的选项¶

xml_pretty¶

类型:: bool
默认:: True

XML美化打印。

在 1.2 版本加入.

用于linkcheck构建器的选项¶

过滤¶

这些选项控制 linkcheck 构建器检查哪些链接，以及忽略哪些失败和重定向。

linkcheck_allowed_redirects¶

类型:: dict[str, str]

A dictionary that maps a pattern of the source URI to a pattern of the canonical URI. The linkcheck builder treats the redirected link as "working" when:

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

当 linkcheck 构建器发现不符合上述规则的重定向链接时，它将发出警告。在使用 the fail-on-warnings mode 时，检测意外重定向可能很有用。

举例如下：

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/.*'
}

在 4.1 版本加入.

在 9.0 版本发生变更: 将 linkcheck_allowed_redirects 设置为空字典现在可用于警告 linkcheck 构建器遇到的所有重定向。

linkcheck_anchors¶

类型:: bool
默认:: True

检查链接中 #anchors 的有效性。由于这需要下载整个文档，因此启用时速度会明显变慢。

在 1.2 版本加入.

linkcheck_anchors_ignore¶

类型:: Sequence[str]
默认:: ["^!"]

一个正则表达式列表，匹配 linkcheck 构建器在检查链接中锚点的有效性时应跳过的锚点。例如，这允许跳过由网站的JavaScript添加的锚点。

小技巧

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

备注

如果您想忽略特定页面或匹配特定模式的页面的锚点（但仍检查不带锚点的同一页面的出现），请改用 linkcheck_ignore，例如如下所示：

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

在 1.5 版本加入.

linkcheck_anchors_ignore_for_url¶

类型:: Sequence[str]
默认:: ()

一个匹配URL的正则表达式列表或元组，linkcheck 构建器不应检查其锚点的有效性。这允许在逐页的基础上跳过锚点检查，同时仍然检查页面本身的有效性。

在 7.1 版本加入.

linkcheck_exclude_documents¶

类型:: Sequence[str]
默认:: ()

一个正则表达式列表，匹配 linkcheck 构建器不应检查其链接有效性的文档。这可用于允许文档的传统或历史部分中的链接衰减。

举例如下：

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

在 4.4 版本加入.

linkcheck_ignore¶

类型:: Sequence[str]
默认:: ()

一个正则表达式列表，匹配在进行 linkcheck 构建时不应检查的URI。

与 ignored URIs 匹配的服务器发出的重定向将不会被跟随。

举例如下：

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

在 1.1 版本加入.

HTTP请求¶

这些选项控制linkcheck构建器如何发出HTTP请求，包括如何处理重定向和身份验证，以及要使用的工作线程数。

linkcheck_auth¶

类型:: Sequence[tuple[str, Any]]
默认:: []

在进行 linkcheck 构建时提供身份验证信息。

一个由 (regex_pattern, auth_info) 元组组成的列表，其中的项目是：

regex_pattern: 匹配URI的正则表达式。
auth_info: 该URI使用的身份验证信息。该值可以是 requests 库理解的任何内容（有关详细信息，请参见 requests authentication ）。

linkcheck 构建器将使用它在 linkcheck_auth 列表中找到的第一个匹配的 auth_info 值，因此列表中较早的值具有更高的优先级。

举例如下：

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

在 2.3 版本加入.

linkcheck_allow_unauthorized¶

类型:: bool
默认:: False

当Web服务器响应HTTP 401（未经授权）响应时，linkcheck 构建器的当前默认行为是将链接视为“broken”。要更改该行为，请将此选项设置为 True 。

在 8.0 版本发生变更: 默认值更改为 False，意味着对检查的超链接的HTTP 401响应默认被视为"broken"。

在 7.3 版本加入.

linkcheck_case_insensitive_urls¶

类型:: Set[str] | Sequence[str]
默认:: ()

一组正则表达式，匹配 linkcheck 构建器应执行不区分大小写比较的URL。这对于链接到不区分大小写或规范化URL大小写的网站非常有用。

默认情况下，linkcheck 要求目标URL区分大小写地匹配文档化的URL。例如，链接到 http://example.org/PATH 的链接重定向到 http://example.org/path 将被报告为 redirected 。

如果URL与 linkcheck_case_insensitive_urls 中包含的模式匹配，则将其报告为 working 。

例如，将所有GitHub URL视为不区分大小写：

linkcheck_case_insensitive_urls = [
    r'https://github\.com/.*',
]

或者，将所有URL视为不区分大小写：

linkcheck_case_insensitive_urls = ['.*']

备注

URI片段（HTML锚点）不受此选项的影响。它们始终使用区分大小写的比较进行检查。

在 9.0 版本加入.

linkcheck_rate_limit_timeout¶

类型:: int
默认:: 300

linkcheck 构建器可能在短时间内向同一站点发出大量请求。此设置控制当服务器指示请求受到速率限制时构建器的行为，方法是设置构建器在记录失败之前每次尝试之间等待的最长持续时间（以秒为单位）。

linkcheck 构建器始终尊重服务器何时重试的指示（使用 Retry-After 头）。否则，linkcheck 会在重试前等待一分钟，并在尝试之间不断加倍等待时间，直到成功或超过 linkcheck_rate_limit_timeout （以秒为单位）。自定义超时应以秒数给出。

在 3.4 版本加入.

linkcheck_report_timeouts_as_broken¶

类型:: bool
默认:: False

如果在等待超链接的响应时 linkcheck_timeout 到期，linkcheck 构建器将默认将链接报告为 timeout 。要将超时报告为 broken ，您可以将 linkcheck_report_timeouts_as_broken 设置为 True 。

在 8.0 版本发生变更: 此选项的默认值更改为 False ，这意味着在检查超链接时发生的超时将使用新的“timeout”状态代码进行报告。

在 7.3 版本加入.

linkcheck_request_headers¶

类型:: dict[str, dict[str, str]]
默认:: {}

一个将URL（不带路径）映射到HTTP请求头的字典。

键是一个类似于 'https://www.sphinx-doc.org/' 的URL基础字符串。要为其他主机指定标题，可以使用 "*" 。仅当URL不匹配其他设置时，它才匹配所有主机。

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

举例如下：

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

在 3.1 版本加入.

linkcheck_retries¶

类型:: int
默认:: 1

linkcheck 构建器在宣布URL损坏之前尝试检查URL的次数。

在 1.4 版本加入.

linkcheck_timeout¶

类型:: int
默认:: 30

以秒为单位的持续时间，linkcheck 构建器将在每个超链接请求后等待响应的时间。

在 1.1 版本加入.

linkcheck_workers¶

类型:: int
默认:: 5

使用检查链接时的工作线程数。

在 1.1 版本加入.

语言域选项¶

用于C语言域的选项¶

c_extra_keywords¶

类型:: Set[str] | Sequence[str]
默认:: ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local']

C解析器识别为关键字的标识符列表。

在 4.0.3 版本加入.

在 7.4 版本发生变更: c_extra_keywords 现在可以是一个集合。

c_id_attributes¶

类型:: Sequence[str]
默认:: ()

一个字符串序列，解析器应应额外把它们作为属性接受。例如，当#define用于属性时，可以出于可移植性的目的使用它。

举例如下：

c_id_attributes = [
    'my_id_attribute',
]

在 3.0 版本加入.

在 7.4 版本发生变更: c_id_attributes 现在可以是一个元组。

c_maximum_signature_line_length¶

类型:: int | None
默认:: None

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

当为 None 时，没有最大长度，整个签名将显示在单个逻辑行上。

这是一个特定于语言域的设置，覆盖了 maximum_signature_line_length。

在 7.1 版本加入.

c_paren_attributes¶

类型:: Sequence[str]
默认:: ()

一个字符串序列，解析器应另外接受为带有一个参数的属性。也就是说，如果 my_align_as 在列表中，那么 my_align_as(X) 被解析为所有具有平衡括号的字符串 X 的属性（()、 [] 和 {}）。例如，当 #define 用于属性时，可以出于可移植性的目的使用它。

举例如下：

c_paren_attributes = [
    'my_align_as',
]

在 3.0 版本加入.

在 7.4 版本发生变更: c_paren_attributes 现在可以是一个元组。

用于C++语言域的选项¶

cpp_id_attributes¶

类型:: Sequence[str]
默认:: ()

一个字符串序列，解析器应另外接受为属性。例如，当 #define 用于属性时，可以出于可移植性的目的使用它。

举例如下：

cpp_id_attributes = [
    'my_id_attribute',
]

在 1.5 版本加入.

在 7.4 版本发生变更: cpp_id_attributes 现在可以是一个元组。

cpp_index_common_prefix¶

类型:: Sequence[str]
默认:: ()

一个前缀列表, 在对全局索引中的C++对象进行排序时将被忽略。

举例如下：

cpp_index_common_prefix = [
    'awesome_lib::',
]

在 1.5 版本加入.

cpp_maximum_signature_line_length¶

类型:: int | None
默认:: None

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

当为 None 时，没有最大长度，整个签名将显示在单个逻辑行上。

这是一个特定于语言域的设置，覆盖了 maximum_signature_line_length。

在 7.1 版本加入.

cpp_paren_attributes¶

类型:: Sequence[str]
默认:: ()

一个字符串序列，解析器应另外接受为带有一个参数的属性。也就是说，如果 my_align_as 在列表中，那么 my_align_as(X) 被解析为所有具有平衡括号的字符串 X 的属性（()、 [] 和 {}）。例如，当 #define 用于属性时，可以出于可移植性的目的使用它。

举例如下：

cpp_paren_attributes = [
    'my_align_as',
]

在 1.5 版本加入.

在 7.4 版本发生变更: cpp_paren_attributes 现在可以是一个元组。

用于Javascript域的选项¶

javascript_maximum_signature_line_length¶

类型:: int | None
默认:: None

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

当为 None 时，没有最大长度，整个签名将显示在单个逻辑行上。

这是一个特定于语言域的设置，覆盖了 maximum_signature_line_length。

在 7.1 版本加入.

javascript_trailing_comma_in_multi_line_signatures¶

类型:: bool
默认:: True

如果为true，则在跨多行的参数列表中使用尾随逗号。

在 8.2 版本加入.

用于Python语言域的选项¶

add_module_names¶

类型:: bool
默认:: True

一个布尔值，决定是否将模块名称添加到所有 object 名称之前（对于定义了某种“模块”的对象类型），例如用于 py:function 指令。

modindex_common_prefix¶

类型:: list[str]
默认:: []

一个前缀列表, 用于排序Python模块索引时会被忽略（例如, 如果设置为 ['foo.'] , 则 foo.bar 显示在 B 下, 而不是 F ）。如果您记录一个由单个包组成的项目, 这会很方便。

小心

目前仅适用于HTML构建器。

在 0.6 版本加入.

python_display_short_literal_types¶

类型:: bool
默认:: False

此值控制 Literal 类型的显示方式。

实际案例¶

下面的示例使用以下 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

在 6.2 版本加入.

python_maximum_signature_line_length¶

类型:: int | None
默认:: None

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

当为 None 时，没有最大长度，整个签名将显示在单个逻辑行上。

这是一个特定于语言域的设置，覆盖了 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)

在 7.1 版本加入.

python_trailing_comma_in_multi_line_signatures¶

类型:: bool
默认:: True

如果为true，则在跨多行的参数列表中使用尾随逗号。

在 8.2 版本加入.

python_use_unqualified_type_names¶

类型:: bool
默认:: False

如果可以解析，则抑制python引用的模块名称。

在 4.0 版本加入.

小心

该特性是实验性的。

trim_doctest_flags¶

类型:: bool
默认:: True

删除所有显示交互式Python会话（即doctest）的代码块末尾的doctest标志（类似于 # doctest: FLAG, ... 的注释）和 <BLANKLINE> 标记。有关包含doctest的更多可能性，请参见扩展 doctest 。

在 1.0 版本加入.

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

扩展的选项¶

扩展通常有自己的配置选项。Sphinx第一方扩展的选项记录在每个 extension's page 中。

配置文件示例¶

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'Test Project'
copyright = '2000-2042, The Test Project Authors'
author = 'The Authors'
version = release = '4.16'

# -- General configuration ------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

exclude_patterns = [
    '_build',
    'Thumbs.db',
    '.DS_Store',
]
extensions = []
language = 'en'
master_doc = 'index'
pygments_style = 'sphinx'
source_suffix = '.rst'
templates_path = ['_templates']

# -- Options for HTML output ----------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']