配置¶

配置目录必须包含一个名为 conf.py 的文件。此文件（包含 Python 代码）被称为“构建配置文件”，其中包含（几乎）所有自定义 Sphinx 输入和输出行为所需的配置。

可以将可选文件 docutils.conf 添加到配置目录，以调整 Docutils 配置，除非被 Sphinx 覆盖或设置。

需要注意的要点

如果没有另行说明，值必须是字符串，并且其默认值为空字符串。
术语“完全限定名称”（FQN）指的是一个字符串，该字符串命名模块内可导入的 Python 对象；例如，完全限定名称 "sphinx.builders.Builder" 指的是 sphinx.builders 模块中的 Builder 类。
文档名称使用 / 作为路径分隔符，并且不包含文件名扩展名。

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

提示

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

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

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

项目标签¶

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

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

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

项目信息¶

project¶

类型:: str
默认值:: '项目名称未设置'

文档化项目的名称。示例

project = 'Thermidor'

author¶

类型:: str
默认值:: '作者姓名未设置'

项目的作者。示例

author = 'Joe Bloggs'

copyright¶

project_copyright¶

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

copyright = 'YYYY'
copyright = 'YYYY, 作者姓名'
copyright = 'YYYY 作者姓名'
copyright = 'YYYY-YYYY, 作者姓名'
copyright = 'YYYY-YYYY 作者姓名'

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

copyright = '%Y'
copyright = '%Y, 作者姓名'
copyright = 'YYYY-%Y, 作者姓名'

3.5 版本新增: project_copyright 别名。

version¶

类型:: str
默认值:: ''

项目的主要版本，用作 |version| 默认替换的替换项。

这可能类似于 version = '4.2'。完整的项目版本在 release 中定义。

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

release¶

类型:: str
默认值:: ''

完整的项目版本，用作 |release| 默认替换的替换项，例如在 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)>。可用的模式有

页面: 手册页 (man)
章节: 手册章节 (1)
路径: 原始手册页和指定的章节 (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| 默认替换的替换项。

如果您将 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 文档。

示例

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 证书验证。

user_agent¶

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

设置 Sphinx 用于 HTTP 请求的 User-Agent。

在 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 – 印尼语
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¶

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

在其中搜索其他消息目录的目录（请参阅 language），相对于源目录。此路径上的目录由 gettext 模块搜索。

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

注意

sphinx-build 的 -v 选项 对于检查 locale_dirs 设置是否按预期工作非常有用。如果未找到消息目录，则会发出调试消息。

0.5 版本新增。

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

gettext_allow_fuzzy_translations¶

类型:: bool
默认值:: False

如果为 True，则消息目录中的“模糊”消息将用于翻译。

在 4.3 版本中添加。

gettext_compact¶

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

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

使用 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 之间的相似度。（此计算可能需要很长时间。）

提示

如果要加速计算，可以使用第三方软件包 (Levenshtein)，方法是运行 pip install levenshtein。

1.3 版本新增。

gettext_location¶

类型:: bool
默认值:: True

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

1.3 版本新增。

gettext_auto_build¶

类型:: bool
默认值:: True

如果为 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 版本中变更: 默认情况下翻译图像的 alt 文本。

在 7.4 版本中变更: 允许并首选 set 类型。

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 版本中添加。

标记选项¶

default_role¶

类型:: str
默认值:: None

要用作默认角色的 reStructuredText 角色（内置角色或 Sphinx 扩展角色）的名称，即用于标记为 `像这样` 的文本。可以将其设置为 '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'

默认域的名称。也可以为 None 以禁用默认域。默认值为 'py'，用于 Python 域。

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

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 版本中添加。

数学选项¶

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

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¶

类型:: bool
默认值:: False

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

您可以使用 --nitpicky 命令行选项临时激活此模式。请参阅 nitpick_ignore，了解如何将丢失的引用标记为“已知丢失”。

nitpicky = True

1.0 版本新增。

nitpick_ignore¶

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

当在 “挑剔模式” 下生成警告时，应忽略的 (warning_type, target) 元组的集合或列表。请注意，warning_type 应包含域名（如果存在）。示例

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

在 1.1 版本中添加。

在 6.2 版本中变更: 将允许的容器类型更改为 set、list 或 tuple

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 实体的挑剔警告，例如 ('py:const', 'foo_package.bar.BAZ_VALUE') 或 ('py:class', 'food.bar.Barman')。

在 4.1 版本中添加。

在 6.2 版本中变更: 将允许的容器类型更改为 set、list 或 tuple

对象签名选项¶

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 样式模式列表。它们与相对于源目录的源文件名进行匹配，在所有平台上都使用斜杠作为目录分隔符。exclude_patterns 优先于 include_patterns。

模式示例

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

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

1.0 版本新增。

include_patterns¶

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

用于查找源文件的 glob 风格模式列表。这些模式相对于源目录下的源文件名进行匹配，并在所有平台上使用斜杠作为目录分隔符。默认情况下，所有文件都从源目录递归包含。 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 版本新增。

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 中变更: 更改为文件扩展名到文件类型的映射。

智能引号选项¶

smartquotes¶

类型:: bool
默认值:: True

如果为 True ，将使用智能引号转换将引号和破折号转换为排版正确的实体。

在版本 1.6.6 中新增: 替换现在已移除的 html_use_smartypants。默认情况下，它适用于除 man 和 text 之外的所有构建器（请参阅 smartquotes_excludes。）

注意

如果位于配置目录中的 docutils.conf 文件（或全局 ~/.docutils 文件）通过相应的 Docutils 选项 *停用* 智能引号，则会无条件地遵守该文件。但如果它 *启用* 它们，则 smartquotes 将优先。

smartquotes_action¶

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

自定义智能引号转换。请参阅下文了解允许的代码。默认的 'qDe' 将普通 **q**uote 字符 " ， ' ，长破折号和短破折号 **D**ashes --- ， -- 和 **e**llipses ... 转换为智能引号。

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

在版本 1.6.6 中新增。

smartquotes_excludes¶

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

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

每个条目都给出了忽略 smartquotes 设置并停用智能引号转换的充分条件。示例

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 中新增。

模板选项¶

template_bridge¶

类型:: str
默认值:: ''

一个字符串，其中包含返回 TemplateBridge 实例的可调用对象（或仅类）的完全限定名称。然后，此实例用于渲染 HTML 文档，以及可能的其他构建器（当前为 changes 构建器）的输出。（请注意，如果要使用 HTML 主题，则必须使模板桥具有主题感知能力。）示例

template_bridge = 'module.CustomTemplateBridge'

templates_path¶

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

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

templates_path = ['.templates']

在版本 1.3 中变更: 由于这些文件并非旨在构建，因此在发现源文件时会自动排除它们。

警告控制选项¶

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.footnote
ref.keyword
ref.numref
ref.option
ref.python
ref.ref
ref.term
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
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 。

构建器选项¶

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
默认值:: '项目版本文档'

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

html_short_title¶

类型:: str
默认值:: html_title 的值

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

在 0.4 版本中添加。

html_baseurl¶

类型:: str
默认值:: ''

指向 HTML 文档根目录的基础 URL。它用于指示使用 规范链接关系 的文档的位置。

在版本 1.8 中新增。

html_codeblock_linenos_style¶

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

代码块的行号样式。

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

在版本 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
默认值:: ''

如果给定，则这必须是图像文件的名称（相对于配置目录的路径），它是文档的网站图标，或者是指向网站图标图像文件的 URL。浏览器使用它作为选项卡、窗口和书签的图标。它应该是 PNG、SVG、GIF 或 ICO 文件格式的 16x16 像素图标。

示例

html_favicon = 'static/favicon.png'

在版本 0.4 中新增: 图像文件将被复制到 _static ，但仅当该文件尚不存在于该目录中时。

在版本 4.0 中变更: 也接受网站图标的 URL。

html_css_files¶

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

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() 。

在版本 1.8 中新增。

在版本 3.5 中变更: 支持 *priority* 属性

html_js_files¶

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

JavaScript 文件列表。条目必须是 *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() 。

在版本 1.8 中新增。

在版本 3.5 中变更: 支持 *priority* 属性

html_static_path¶

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

包含自定义静态文件（例如样式表或脚本文件）的路径列表。相对路径被视为相对于配置目录的路径。它们在主题的静态文件之后被复制到输出的 _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¶

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

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

由于这些文件并非旨在构建，因此会自动从源文件中排除它们。

在版本 1.2 中新增。

在 1.4 版本中变更: extra 目录中的点文件将会被复制到输出目录。它在复制额外文件和目录时参考 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
默认值:: '¶' (段落符号)

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

在 3.5 版本中添加。

html_sidebars¶

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

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

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

每个值必须是字符串列表，其中指定要包含的完整侧边栏模板列表。如果要包含全部或部分默认侧边栏，也必须将其放入此列表。

默认侧边栏（对于不匹配任何模式的文档）由主题本身定义。内置主题默认使用以下模板：'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 和给定文档侧边栏中的快速搜索框，并为所有其他页面渲染默认侧边栏（除了本地 TOC 被全局 TOC 替换）。

请注意，如果所选主题没有侧边栏，例如内置的 scrolls 和 haiku 主题，则此值无效。

在 1.0 版本中添加: 使用 globbing 键和指定多个侧边栏的功能。

在 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，则除了通用索引之外，还生成特定于域的索引。例如，对于 Python 域，这是全局模块索引。

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

示例

html_domain_indices = {
    'py-modindex',
}

1.0 版本新增。

在 7.4 版本中变更: 允许并首选 set 类型。

html_use_index¶

类型:: bool
默认值:: True

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

在 0.4 版本中添加。

html_split_index¶

类型:: bool
默认值:: False

生成两个版本的索引：一个版本是包含所有条目的单个页面，另一个版本是每个起始字母一个页面。

在 0.4 版本中添加。

html_copy_source¶

类型:: bool
默认值:: True

如果为 True，则 reStructuredText 源文件将作为 _sources/文档名 包含在 HTML 构建中。

html_show_sourcelink¶

类型:: bool
默认值:: True

如果为 True（且 html_copy_source 也为 true），则指向 reStructuredText 源文件的链接将添加到侧边栏。

在 0.6 版本中添加。

html_sourcelink_suffix¶

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

要附加到源链接的后缀 (请参阅 html_show_sourcelink)，除非文件已具有此后缀。

1.5 版本新增。

html_use_opensearch¶

类型:: str
默认值:: ''

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

在 0.2 版本中添加。

html_file_suffix¶

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

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

在 0.4 版本中添加。

html_link_suffix¶

类型:: str
默认值:: html_file_suffix 的值

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

在 0.6 版本中添加。

html_show_copyright¶

类型:: bool
默认值:: True

1.0 版本新增。

html_show_search_summary¶

类型:: bool
默认值:: True

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

在 4.5 版本中添加。

html_show_sphinx¶

类型:: bool
默认值:: True

在 HTML 页脚中添加 “使用 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
默认值:: language 的值

用于生成 HTML 全文搜索索引的语言。这默认为使用 language 选择的全局语言。如果不支持此语言，则使用英语 ('en') 作为备用选项。

支持以下语言

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

提示

加速构建速度

每种语言（日语除外）都提供自己的词干提取算法。Sphinx 默认使用 Python 实现。如果要加速构建索引文件，可以使用第三方软件包 (PyStemmer)，方法是运行 pip install 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 选项是 MeCab 算法的编码。
dict:: dict 选项是用于 MeCab 算法的字典。
lib:: lib 选项是通过 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 选项是 Janome 的用户字典文件路径。
user_dic_enc:: user_dic_enc 选项是由 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 指令中

.. 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 中新增。

Single HTML 输出的选项¶

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

singlehtml_sidebars¶

类型:: dict[str, Sequence[str]]
默认值:: html_sidebars 的值

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

这与 html_sidebars 具有相同的效果，但唯一允许的键是 'index'，所有其他键都将被忽略。

HTML 帮助输出的选项¶

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

htmlhelp_basename¶

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

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

htmlhelp_file_suffix¶

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

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

在 2.0 版本中添加。

htmlhelp_link_suffix¶

类型:: str
默认值:: 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 禁用这些工具的使用，但在索引器在 bundle 中 .lproj 目录上运行之前，结果将不是有效的帮助手册。

applehelp_bundle_name¶

类型:: str
默认值:: project 的值

Apple Help Book 的基本名称。默认值是 project name，其中空格被移除。

applehelp_bundle_id¶

类型:: str
默认值:: None

帮助手册 bundle 的 bundle ID。

警告

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

applehelp_bundle_version¶

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

bundle 版本，以字符串形式表示。

applehelp_dev_region¶

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

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

applehelp_icon¶

类型:: str
默认值:: None

帮助 bundle 图标文件的路径，或者 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'。在运行时，Help Viewer 将把 'product' 替换为 applehelp_kb_product 的内容，'query' 替换为用户在搜索框中输入的文本，'lang' 替换为用户的系统语言。

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

applehelp_remote_url¶

类型:: str
默认值:: None

远程内容的 URL。您可以将 Help Book 的 Resources 目录的副本放在此位置，Help Viewer 将尝试使用它来获取更新的内容。

例如，如果您将其设置为 https://example.com/help/Foo/，并且 Help Viewer 想要英语客户的 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
默认值:: language 的值

语言规范（用于使用内置停用词）、停用词 plist 的路径，或者 None （如果您不想使用停用词）。默认的停用词 plist 可以在 /usr/share/hiutil/Stopwords.plist 中找到，并且在编写本文时，包含以下语言的停用词

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

applehelp_locale¶

类型:: str
默认值:: language 的值

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

applehelp_title¶

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

指定帮助手册标题。

applehelp_codesign_identity¶

类型:: str
默认值:: CODE_SIGN_IDENTITY 的值

指定用于代码签名的身份。如果不需要代码签名，请使用 None。

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

applehelp_codesign_flags¶

类型:: list[str]
默认值:: OTHER_CODE_SIGN_FLAGS 的值

传递给 codesign 以对帮助手册进行签名的一系列附加参数。

默认为基于 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 元数据所必需的。

epub_basename¶

类型:: str
默认值:: project 的值

EPUB 文件的基本名称。

epub_theme¶

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

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

epub_theme_options¶

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

影响所选主题外观和感觉的选项字典。这些是特定于主题的。内置主题理解的选项在此处描述。

在版本 1.2 中新增。

epub_title¶

类型:: str
默认值:: project 的值

文档的标题。

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

epub_description¶

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

文档的描述。

在 1.4 版本中添加。

在 1.5 版本中变更: 从 epub3_description 重命名

epub_author¶

类型:: str
默认值:: author 的值

文档的作者。这会放入 Dublin Core 元数据中。

epub_contributor¶

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

在 EPUB 出版物的内容创作中起次要作用的个人、组织等的名称。

在 1.4 版本中添加。

在 1.5 版本中变更: 从 epub3_contributor 重命名

epub_language¶

类型:: str
默认值:: language 的值

文档的语言。这会放入 Dublin Core 元数据中。

epub_publisher¶

类型:: str
默认值:: author 的值

文档的发布者。这会放入 Dublin Core 元数据中。您可以使用任何合理的字符串，例如项目主页。

epub_copyright¶

类型:: str
默认值:: copyright 的值

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

epub_identifier¶

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

文档的标识符。这会放入 Dublin Core 元数据中。对于已发布的文档，这是 ISBN 编号，但您也可以使用其他方案，例如项目主页。

epub_scheme¶

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

用于 epub_identifier 的出版方案。这会放入 Dublin Core 元数据中。对于已出版的书籍，该方案为 'ISBN'。如果您使用项目主页，则 'URL' 似乎是合理的。

epub_uid¶

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

文档的唯一标识符。这被放入 Dublin Core 元数据中。您可以使用符合 XML Name 格式的字符串。您不能使用连字符、句点、数字作为第一个字符。

epub_cover¶

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

封面页信息。这是一个元组，包含封面图像和 html 模板的文件名。渲染后的 html 封面页作为 spine 中的第一个条目插入到 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，或者是以 scheme 开头的完整 URI，例如 'https://example.org/style.css'。 attributes 字典用于 <link> 标签的属性。有关更多信息，请参阅 html_css_files。

在版本 1.8 中新增。

epub_guide¶

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

用于 content.opf 的 guide 元素的元数据。这是一个元组序列，包含可选引导信息的 type、uri 和 title。有关详细信息，请参阅 OPF 文档。如果可能，会自动插入 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 图像库 (Pillow) 才能使用此选项。

在版本 1.2 中新增。

epub_max_image_width¶

类型:: int
默认值:: 0

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

在版本 1.2 中新增。

epub_show_urls¶

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

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

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

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

在版本 1.2 中新增。

epub_use_index¶

类型:: bool
默认值:: 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 的滚动主题支持	scroll-axis is vertical.（滚动轴是垂直的。）	scroll-axis is horizontal.（滚动轴是水平的。）

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' 的文档中添加了对偶尔出现的西里尔字母和希腊字母或单词的支持。要启用此功能，必须适当使用 'fontenc' 键，该键位于 latex_elements 中。

注意

与 HTML 输出中的 MathJaX 数学渲染相反，LaTeX 需要一些额外的配置来支持 math 中的 Unicode 字面量：据我们所知，唯一的综合解决方案是使用 'xelatex' 或 'lualatex' 并添加 r'\usepackage{unicode-math}' (例如，通过 'preamble' 键，该键位于 latex_elements 中)。您可能更喜欢 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]]
默认值:: 默认的 LaTeX 文档

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

startdocname: 字符串，指定 LaTeX 文件主文档的文档名称。 startdoc 文档在目录树中引用的所有文档都将包含在 LaTeX 文件中。 (如果您想为 LaTeX 构建使用默认主文档，请在此处提供您的 master_doc。)
targetname: 输出目录中 LaTeX 文件的文件名。
title: LaTeX 文档标题。可以为空以使用 startdoc 文档的标题。这将作为 LaTeX 标记插入，因此如果特殊字符 (如反斜杠或 & 符号) 要按字面插入，则必须用适当的 LaTeX 命令表示。
作者: LaTeX 文档的作者。与 title 相同的 LaTeX 标记注意事项适用。使用 \\and 分隔多个作者，如: 'John \\and Sarah' (反斜杠必须进行 Python 转义才能到达 LaTeX)。
theme: LaTeX 主题。请参阅 latex_theme。
toctree_only: 必须是 True 或 False。如果为 True，则输出中不包含 startdoc 文档本身，仅包含通过目录树引用的文档。使用此选项，您可以将额外的材料放在主文档中，这些材料会显示在 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 编号不同步，因为默认情况下，当遇到 \part 命令时，LaTeX 不会重置 \chapter 编号 (或 \section 用于 'howto' 主题)。

在 1.4 版本中添加。

latex_appendices¶

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

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

latex_domain_indices¶

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

如果为 True，则除了通用索引之外，还生成特定于域的索引。例如，对于 Python 域，这是全局模块索引。

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

示例

latex_domain_indices = {
    'py-modindex',
}

1.0 版本新增。

在 7.4 版本中变更: 允许并首选 set 类型。

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 配置设置中。

重要提示

使用 'colorrows' 样式时，\rowcolors LaTeX 命令变为 no-op (此命令有限制，并且从未正确支持 Sphinx 在 LaTeX 中生成的所有类型的表格)。请更新您的项目以使用 latex 表格颜色配置键。

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

当前识别的类是 booktabs、borderless、standard、colorrows、nocolorrows。后两个可以与前三个中的任何一个组合使用。 standard 类生成具有水平线和垂直线的表格 (到目前为止，这是 Sphinx 的默认设置)。

单行多列合并的单元格将服从行颜色 (如果已设置)。另请参阅 sphinxsetup 配置设置部分中的 TableMergeColor{Header,Odd,Even}。

注意

在 LaTeX 中硬编码的是，即使通过来自列规范的 \columncolor 设置了列颜色，单个单元格也会服从行颜色 (请参阅 tabularcolumns)。 Sphinx 提供了 \sphinxnorowcolor，可以在表格列规范中像这样使用它
```
>{\columncolor{blue}\sphinxnorowcolor}
```
Sphinx 还提供了 \sphinxcolorblend，但这需要 xcolor 包。这是一个示例
```
>{\sphinxcolorblend{!95!red}}
```
这意味着在此列中，行颜色将略微被红色着色；有关其 \blendcolors 命令的语法的更多信息，请参阅 xcolor 文档 (\blendcolors 代替 \sphinxcolorblend 将修改单元格内容的颜色，而不是单元格背景颜色面板的颜色…)。您可以在本文档的 PDF 格式的已弃用的 API 部分中找到用法示例。

提示

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

提示

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

另一方面，对于没有额外包的单个表格，可以使用 colorrows 类 (因为自 5.3.0 起 Sphinx 始终加载 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 意味着对于 language，将正确排序包含 UTF-8 字符的单词。

如果 latex_engine 是 'platex' (日语文档； mendex 替换 makeindex)，则忽略此选项。
对于 'xelatex' 或 'lualatex'，默认值为 True，因为如果任何索引术语以非 ASCII 字符开头，makeindex 会创建包含 UTF-8 编码的无效字节的 .ind 文件。使用 'lualatex'，这会破坏 PDF 构建。
对于 'pdflatex'，默认值为 False，但对于非英语文档，建议使用 True，只要某些索引术语使用来自语言脚本的非 ASCII 字符即可。如果 latex_use_xindy 保留其默认值 False，则尝试索引第一个字符为非 ASCII 字符的术语将破坏构建。

Sphinx 为 xindy 基本发行版添加了一些专用支持，以便将 'pdflatex' 引擎与西里尔文字符集一起使用。对于 '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: 用于编写手册的 LaTeX 主题。它导入了 report 文档类（日语文档使用 jsbook）。
howto: 用于编写文章的 LaTeX 主题。它导入了 article 文档类（日语文档使用 jreport）。latex_appendices 仅适用于此主题。

在 3.0 版本中添加。

latex_theme_options¶

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

影响所选主题外观的选项字典。这些是特定于主题的。

在版本 3.1 中添加。

latex_theme_path¶

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

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

在 3.0 版本中添加。

文本输出选项¶

这些选项影响文本输出。

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]]
默认值:: 默认手册页

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

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

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]]
默认值:: 默认 Texinfo 文档

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

startdocname: 字符串，指定 Texinfo 文件主文档的文档名称。在 ToC 树中，startdoc 文档引用的所有文档都将包含在 Texinfo 文件中。（如果您想为 Texinfo 构建使用默认主文档，请在此处提供您的 master_doc。）
targetname: 输出目录中 Texinfo 文件的文件名（无扩展名）。
title: Texinfo 文档标题。可以为空以使用 startdoc 文档的标题。作为 Texinfo 标记插入，因此像 @ 和 {} 这样的特殊字符需要转义才能按字面插入。
作者: 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，则除了通用索引之外，还生成特定于域的索引。例如，对于 Python 域，这是全局模块索引。

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

示例

texinfo_domain_indices = {
    'py-modindex',
}

在 1.1 版本中添加。

在 7.4 版本中变更: 允许并首选 set 类型。

texinfo_elements¶

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

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

您可能想要覆盖的键包括

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

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

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

'copying'
在 @copying 块中插入并在标题后显示的 Texinfo 标记。默认值由一个简单的标题页组成，用于标识项目。
由其他选项设置因此不应覆盖的键是 '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
默认值:: project 的值

qthelp 文件的基本名称。

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]
默认值:: {}

一个字典，将源 URI 的模式映射到规范 URI 的模式。当满足以下条件时，linkcheck 构建器将重定向的链接视为 “工作正常”：

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

当 linkcheck 构建器发现不符合上述规则的重定向链接时，它将发出警告。当使用 fail-on-warnings 模式 时，这对于检测意外重定向非常有用。

示例

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 版本中添加。

linkcheck_anchors¶

类型:: bool
默认值:: True

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

在版本 1.2 中新增。

linkcheck_anchors_ignore¶

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

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

提示

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

注意

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

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

1.5 版本新增。

linkcheck_anchors_ignore_for_url¶

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

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

在 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 匹配的正则表达式列表。

与 忽略的 URI 匹配的服务器发出的重定向将不会被跟踪。

示例

linkcheck_ignore = [r'https://127.0.0.1:\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 身份验证）。

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 构建器当前的默认行为是将链接视为 “损坏”。要更改该行为，请将此选项设置为 True。

在版本 8.0 中更改: 此选项的默认值已更改为 False，这意味着默认情况下，对检查的超链接的 HTTP 401 响应被视为 “损坏”。

在版本 7.3 中添加。

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 请求标头。

键是 URL 基本字符串，如 'https://sphinx-doc.cn/'。要为其他主机指定标头，可以使用 "*"。仅当 URL 与其他设置不匹配时，它才匹配所有主机。

值是将标头名称映射到其值的字典。

示例

linkcheck_request_headers = {
    "https://sphinx-doc.cn/": {
        "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 在列表中，则对于所有具有平衡大括号（()、[] 和 {}）的字符串 X，my_align_as(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 在列表中，则对于所有具有平衡大括号（()、[] 和 {}）的字符串 X，my_align_as(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

一个布尔值，决定是否将模块名称添加到所有对象名称（对于定义了某种 “模块” 的对象类型），例如对于 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 会话（即 doctests）的所有代码块行尾的 doctest 标志（看起来像 # doctest: FLAG, ... 的注释）和 <BLANKLINE> 标记。有关包含 doctests 的更多可能性，请参阅扩展 doctest。

1.0 版本新增。

在 1.1 版本中变更：现在也删除 <BLANKLINE>。

扩展选项¶

扩展通常有自己的配置选项。Sphinx 第一方扩展的配置选项记录在每个扩展页面中。

示例配置文件¶

# -- Project information -----------------------------------------------------
# https://sphinx-doc.cn/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://sphinx-doc.cn/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://sphinx-doc.cn/en/master/usage/configuration.html#options-for-html-output

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