配置

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

可以在配置目录中添加一个可选文件 docutils.conf 来调整 Docutils 配置，前提是它没有被 Sphinx 覆盖或设置。

重要注意事项

• 如果文档中未另行说明，则值必须为字符串，默认值为空字符串。

• 术语“完全限定名称”（FQN）指的是一个字符串，它命名了一个模块中可导入的 Python 对象；例如，完全限定名称 "sphinx.builders.Builder" 表示 Builder 类位于 sphinx.builders 模块中。

• 文档名称使用 / 作为路径分隔符，并且不包含文件名扩展名。

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

提示

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

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

config 命名空间的内容被 pickle（这样 Sphinx 可以知道配置何时发生更改），因此它可能不包含不可 pickle 的值——如果需要，请使用 del 从命名空间中删除它们。模块会自动删除，因此不需要删除导入的模块。

项目标签

在配置文件中有一个名为 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]

默认值:

''

版权声明。允许的样式如下，其中“YYYY”代表四位数年份。

• copyright = 'YYYY'

• copyright = 'YYYY, 作者姓名'

• copyright = 'YYYY 作者姓名'

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

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

版本 3.5 中新增： The project_copyright 别名。

版本 7.1 中变更： 该值现在可以是上述形式的版权声明序列，每个声明将显示在它们自己的行中。

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 时，请确保使用绝对路径。如果您的自定义扩展位于相对于 配置文件目录 的目录中，请使用 os.path.abspath()，如下所示

import os, sys; sys.path.append(os.path.abspath('sphinxext'))

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| 默认替换 的替换。

• 如果您将 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 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 请求的 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]

默认值:

['locale']

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

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

注意

-v option to sphinx-build 非常有用，可以检查 locale_dirs 设置是否按预期工作。如果找不到消息目录，则会发出调试消息。

在版本 0.5 中添加。

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

gettext_allow_fuzzy_translations

类型:

bool

默认值:

False

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

在版本 4.3 中添加。

gettext_compact

类型:

bool | str

默认值:

True

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

• 如果 False，则文档的文本域为完整的 docname。

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

使用 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 中变更： 默认情况下会翻译图片的替代文字。

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

标记选项

default_role

类型:

str

默认值:

None

要使用的 reStructuredText 角色（内置或 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'

默认 域 的名称。也可以为 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) 元组的集合或列表，在 "nitpicky mode" 中生成警告时应该被忽略。请注意， 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 实体的挑剔警告，例如 ('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 风格模式 的列表。它们与相对于源目录的源文件名进行匹配，在所有平台上使用斜杠作为目录分隔符。 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 风格模式 列表。它们与相对于源目录的源文件名匹配，在所有平台上使用斜杠作为目录分隔符。默认情况下，所有文件都将从源目录递归包含。 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' 将教育正常的 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']}

控制何时禁用智能引号转换。允许的键是 '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]

默认值:

()

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

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

• app.add_node

• app.add_directive

• app.add_role

• app.add_generic_role

• app.add_source_parser

• config.cache

• docutils

• download.not_readable

• epub.unknown_project_files

• epub.duplicated_toc_entry

• i18n.inconsistent_references

• index

• image.not_readable

• ref.term

• ref.ref

• ref.numref

• ref.keyword

• ref.option

• ref.citation

• ref.footnote

• ref.doc

• ref.python

• misc.copy_overwrite

• misc.highlighting_failure

• toc.circular

• toc.excluded

• toc.no_title

• toc.not_readable

• toc.secnum

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

• autodoc

• autodoc.import_object

• autosectionlabel.<document name>

• autosummary

• autosummary.import_cycle

• intersphinx.external

您可以从这些类型中进行选择。您也可以只给出第一个组件来排除所有与它相关联的警告。

在版本 1.4 中添加。

在 1.5 版中变更: 添加了 misc.highlighting_failure

在 1.5.1 版中变更: 添加了 epub.unknown_project_files

在 1.6 版中变更: 添加了 ref.footnote

在 2.1 版中变更: 添加了 autosectionlabel.<document name>

在 3.3.0 版中变更: 添加了 epub.duplicated_toc_entry

在 4.3 版中变更: 添加了 toc.excluded 和 toc.not_readable

在 4.5 版中添加: 添加了 i18n.inconsistent_references

在 7.1 版中添加: 添加了 index。

在 7.3 版中添加: 添加了 config.cache。

在 7.3 版中添加: 添加了 toc.no_title。

在 8.0 版中添加: 添加了 misc.copy_overwrite。

构建器选项

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

默认值:

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

默认值:

''

如果给出，则必须是图像文件的名称（相对于 配置目录 的路径），该文件是文档的 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 文件列表。条目必须是文件名字符串，或者包含文件名字符串和属性字典的元组。文件名必须相对于 html_static_path，或者带有方案的完整 URI，例如 'https://example.org/style.css'。属性字典用于 <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 文件列表。条目必须是文件名字符串，或包含文件名字符串和属性字典的元组。文件名必须相对于 html_static_path，或者是一个带有方案的完整 URI，例如 'https://example.org/script.js'。属性字典用于 <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 中变更: 额外目录中的点文件将被复制到输出目录。它引用 exclude_patterns 来复制额外文件和目录，并且如果路径与模式匹配，则忽略。

html_last_updated_fmt

类型:

str

默认值:

'%b %d, %Y'

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

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 以及给定文档侧边栏中的快速搜索框，并渲染所有其他页面的默认侧边栏（除了本地目录被全局目录替换）。

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

在版本 1.0 中添加: 使用 glob 模式键和指定多个侧边栏的能力。

从版本 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 中变更： 允许并优先使用集合类型。

html_use_index

类型:

bool

默认值:

True

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

在版本 0.4 中添加。

html_split_index

类型:

bool

默认值:

False

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

在版本 0.4 中添加。

html_copy_source

类型:

bool

默认值:

True

如果为 True，则 reStructuredText 源文件将作为 _sources/docname 包含在 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

如果为真，则“© 版权所有 …” 将显示在 HTML 页脚中，其值来自 copyright。

版本 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

如果为真，则所有项目都包含单个段落和/或所有项目都包含子列表等的列表（递归定义）将不会为其任何项目使用 <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 指令上给出的任何链接（如果有），如果存在的话。

提示

要禁用此功能，方法是将 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]]

默认值:

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 帮助输出的选项

版本 1.3 中新增。

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

注意

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

可以使用 applehelp_disable_external_tools 禁用这些工具的使用，但结果将不会是有效的帮助手册，除非对捆绑包内的 .lproj 目录运行索引器。

applehelp_bundle_name

类型:

str

默认值:

project 的值

Apple 帮助手册的基本名称。默认值为 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。根据苹果的文档，这应该是应用程序图标的 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；有关此主题的更多信息，请参阅苹果的文档。

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 的值

指定要生成帮助的区域设置。这用于确定帮助手册的 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 选项在适当的情况下也适用。

注意

这些选项中一些的实际值并不重要，但它们是 都柏林核心元数据 所必需的。

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 的值

文档的作者。它将被放入都柏林核心元数据中。

epub_contributor

类型:

str

默认值:

'unknown'

在 EPUB 出版物的內容創建中扮演次要角色的個人、組織等的姓名。

在版本 1.4 中添加。

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

epub_language

类型:

str

默认值:

language 的值

文档的语言。它将被放入都柏林核心元数据中。

epub_publisher

类型:

str

默认值:

author 的值

文档的发布者。它将被放入都柏林核心元数据中。您可以使用任何合理的字符串，例如项目主页。

epub_copyright

类型:

str

默认值:

copyright 的值

文档的版权。

epub_identifier

类型:

str

默认值:

'unknown'

文档的标识符。它将被放入都柏林核心元数据中。对于已发布的文档，这是 ISBN 号，但您也可以使用其他方案，例如项目主页。

epub_scheme

类型:

str

默认值:

'unknown'

用于 epub_identifier 的出版方案。它将被放入都柏林核心元数据中。对于已发布的书籍，该方案是 'ISBN'。如果您使用项目主页，'URL' 似乎是合理的。

epub_uid

类型:

str

默认值:

'unknown'

文档的唯一标识符。它将被放入都柏林核心元数据中。您可以使用 XML 的名称格式 字符串。您不能使用连字符、句点、数字作为第一个字符。

epub_cover

类型:

tuple[str, str]

默认值:

()

封面页信息。这是一个元组，包含封面图像和 HTML 模板的文件名。渲染后的 HTML 封面页将作为第一个项目插入到 content.opf 的 spine 中。如果模板文件名为空，则不会创建 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 文件列表。条目必须是文件名字符串或包含文件名字符串和属性字典的元组。文件名必须相对于 html_static_path，或者具有方案的完整 URI，例如 'https://example.org/style.css'。属性字典用于 <link> 标签的属性。有关更多信息，请参阅 html_css_files。

在 1.8 版中添加。

epub_guide

类型:

Sequence[tuple[str, str, str]]

默认值:

()

content.opf 的 guide 元素的元数据。这是一个包含类型、uri 和可选 guide 信息的标题的元组序列。有关详细信息，请参阅 OPF 文档。如果可能，会自动插入封面和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
页面进度	从左到右	从右到左
iBook 的滚动主题支持	scroll-axis 为垂直方向。	scroll-axis 为水平方向。

LaTeX 输出的选项

这些选项影响 LaTeX 输出。

latex_engine

类型:

'pdflatex' | 'xelatex' | 'lualatex' | 'platex' | 'uplatex'

默认值:

'pdflatex'

用于构建文档的 LaTeX 引擎。此设置可以具有以下值

• 'pdflatex' – PDFLaTeX（默认）

• 'xelatex' – XeLaTeX

• '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 文件主文档的 文档名称 的字符串。ToC 树中由 *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 编号（或 'howto' 主题的 \section）。

在版本 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 中变更： 允许并优先使用集合类型。

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 中更改： 此值现在是字符串；以前它是一个布尔值，真值为选择 '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 命令将成为一个空操作（此命令有局限性，而且从未正确地支持 Sphinx 在 LaTeX 中生成的各种类型的表格）。请更新您的项目以改用 latex 表格颜色配置 键。

每个表格都可以通过 :class: 选项覆盖全局样式，或者对于无指令表格使用 .. rst-class::（参见 表格）。当前识别的类是 booktabs、borderless、standard、colorrows、nocolorrows。后两个可以与前三个中的任何一个组合。standard 类生成带有水平线和垂直线的表格（到目前为止，这是 Sphinx 中的默认行为）。

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

注意

• 在 LaTeX 中，硬编码为单个单元格将服从行颜色，即使通过列规范（参见 tabularcolumns）设置了列颜色，也会服从行颜色（通过 \columncolor 设置）。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 类对单个表格进行样式设置，但需要在 LaTeX 前言中添加 r'\usepackage{booktabs}'。

另一方面，可以使用 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 会创建包含 UTF-8 编码无效字节的 .ind 文件。使用 'lualatex' 时，这会破坏 PDF 构建。

• 对于 'pdflatex'，默认值为 False，但对于非英语文档，建议使用 True，只要某些索引项使用来自语言脚本的非 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

startdoc

name

手册页的名称。这应该是一个没有空格或特殊字符的短字符串。它用于确定文件名以及手册页的名称（在 NAME 部分）。

描述

手册页的描述。这在 NAME 部分使用。如果您不想自动生成 NAME 部分，可以为空字符串。

作者

作者字符串列表或单个字符串。如果不想在手册页中自动生成 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]]

默认值:

默认的 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 标记，因此像 @ 和 {} 这样的特殊字符需要转义才能按字面插入。

author

Texinfo 文档的作者。插入为 Texinfo 标记。使用 @* 来分隔多个作者，例如：'John@*Sarah'。

dir_entry

将在顶级 DIR 菜单文件中显示的名称。

描述

将在顶级 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 中变更： 允许并优先使用集合类型。

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

不要在“顶部”节点的菜单中生成一个 @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 的模式。当

• 文档中的链接与源 URI 模式匹配，并且

• 重定向位置与规范 URI 模式匹配时，linkcheck 构建器会将重定向链接视为“有效”。

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

linkcheck_anchors

类型:

bool

默认值:

True

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

在版本 1.2 中添加。

linkcheck_anchors_ignore

类型:

Sequence[str]

默认值:

["^!"]

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

提示

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

注意

如果您想忽略特定页面的锚点或与特定模式匹配的页面的锚点（但仍然检查不包含锚点的相同页面（s）的出现），请改用 linkcheck_ignore，例如：

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

在版本 1.5 中添加。

linkcheck_anchors_ignore_for_url

类型:

Sequence[str]

默认值:

()

一个正则表达式列表或元组，匹配 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。

示例

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

在版本 1.1 中添加。

HTTP 请求

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

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，这意味着在检查超链接时发生的超时将使用新的“超时”状态代码报告。

在版本 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 在列表中，则 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 中添加。

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_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 的第一方扩展的配置选项在每个 扩展页面 中有说明。

示例配置文件

# -- 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']

Previous

交叉引用语法

Next

构建器