配置

配置目录必须包含一个名为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]

默认:

''

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

• 版权 = 'YYYY'

• 版权 = 'YYYY, 作者姓名'

• 版权 = 'YYYY 作者姓名'

• 版权 = 'YYYY-YYYY, 作者姓名'

• 版权 = 'YYYY-YYYY 作者姓名'

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

• 版权 = '%Y'

• 版权 = '%Y, 作者姓名'

• 版权 = 'YYYY-%Y, 作者姓名'

版本 3.5 新增: project_copyright别名。

版本 7.1 更改: 该值现在可以是上述形式的版权声明序列，每个声明都将显示为单独的行。

版本 8.1 更改: 版权声明支持'%Y'占位符。

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)>。可用的模式有

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

user_agent

类型:

str

默认:

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

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

版本 2.3 新增。

国际化选项

这些选项影响 Sphinx 的本地语言支持。有关详细信息，请参阅国际化文档。

language

类型:

str

默认:

'en'

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

版本 0.5 中新增。

版本 1.4 更改: 支持图形替换

版本 5.0 更改: 默认值现在为'en'（以前为None）。

Sphinx 目前支持的语言有

• ar – 阿拉伯语

• bg – 保加利亚语

• bn – 孟加拉语

• ca – 加泰罗尼亚语

• cak – 卡奇克语

• cs – 捷克语

• cy – 威尔士语

• da – 丹麦语

• de – 德语

• el – 希腊语

• en – 英语 (默认)

• eo – 世界语

• es – 西班牙语

• et – 爱沙尼亚语

• eu – 巴斯克语

• fa – 伊朗语

• fi – 芬兰语

• fr – 法语

• he – 希伯来语

• hi – 印地语

• hi_IN – 印地语 (印度)

• hr – 克罗地亚语

• hu – 匈牙利语

• id – 印度尼西亚语

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

提示

如果您想加速计算，可以通过运行pip install levenshtein来使用第三方包（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 更改: 允许并优先使用集合类型。

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

默认:

无

用作默认角色的 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 function”，而不仅仅是“function”）。示例

primary_domain = 'cpp'

版本 1.0 新增。

rst_epilog

类型:

str

默认:

''

一个 reStructuredText 字符串，它将包含在每个读取的源文件的末尾。这是一个可以添加应在每个文件中可用的替换的地方（另一个是rst_prolog）。示例

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

0.6 版本新增。

rst_prolog

类型:

str

默认:

''

一个 reStructuredText 字符串，它将包含在每个读取的源文件的开头。这是一个可以添加应在每个文件中可用的替换的地方（另一个是rst_epilog）。示例

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

版本 1.0 新增。

show_authors

类型:

bool

默认:

False

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

trim_footnote_reference_space

类型:

bool

默认:

False

修剪脚注引用前的空格，这些空格对于 reStructuredText 解析器识别脚注是必需的，但在输出中看起来不太美观。

0.6 版本新增。

数学选项

这些选项控制数学标记和表示法。

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时，没有最大长度，整个签名将显示在单个逻辑行上。

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

领域可以提供选项来抑制单个对象指令上的任何硬换行，如 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

类型:

序列[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

类型:

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

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

source_suffix

类型:

dict[str, str] | Sequence[str] | str

默认:

{'.rst': 'restructuredtext'}

一个字典，将源文件的文件扩展名（后缀）映射到其文件类型。Sphinx 认为所有 source_suffix 中具有后缀的文件都是源文件。示例

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

默认情况下，Sphinx 只支持 'restructuredtext' 文件类型。可以通过注册不同源文件解析器的扩展（例如 MyST-Parser）添加更多文件类型。请参阅扩展的文档以了解它支持哪些文件类型。

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

注意

文件扩展名必须以点 ('.') 开头。

版本 1.3 中已更改: 支持文件扩展名列表。

版本 1.8 中已更改: 更改为文件扩展名到文件类型的映射。

智能引号选项

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 字符 "、'、长短Dash ---、-- 和省略号 ...。

'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

类型:

序列[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

类型:

序列[str]

默认:

()

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

版本 1.4 中新增。

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

• app.add_directive

• app.add_generic_role

• app.add_node

• app.add_role

• app.add_source_parser

• config.cache

• docutils

• download.not_readable

• duplicate_declaration.c

• duplicate_declaration.cpp

• epub.duplicated_toc_entry

• epub.unknown_project_files

• i18n.babel

• i18n.inconsistent_references

• i18n.not_readable

• i18n.not_writeable

• image.not_readable

• index

• misc.copy_overwrite

• misc.highlighting_failure

• ref.any

• ref.citation

• ref.doc

• ref.equation

• ref.footnote

• ref.keyword

• ref.numref

• ref.option

• ref.python

• ref.ref

• ref.term

• source_code_parser.c

• source_code_parser.cpp

• toc.circular

• toc.duplicate_entry

• toc.empty_glob

• toc.excluded

• toc.no_title

• toc.not_included

• toc.not_readable

• toc.secnum

扩展还可以定义自己的警告类型。第一方 sphinx.ext 扩展定义的警告类型有

• autodoc

• autodoc.import_object

• autodoc.mocked_object

• autosectionlabel.<document name>

• autosummary

• autosummary.import_cycle

• duration

• intersphinx.external

您可以从这些类型中选择。您还可以只提供第一个组件以排除所有附加到它的警告。

版本 1.4 中新增: ref.citation、ref.doc、ref.keyword、ref.numref、ref.option、ref.ref 和 ref.term。

版本 1.4.2 中新增: app.add_directive、app.add_generic_role、app.add_node、app.add_role 和 app.add_source_parser。

版本 1.5 中新增: misc.highlighting_failure。

版本 1.5.1 中新增: epub.unknown_project_files。

版本 1.5.2 中新增: toc.secnum。

版本 1.6 中新增: ref.footnote、download.not_readable 和 image.not_readable。

版本 1.7 中新增: ref.python。

版本 2.0 中新增: autodoc.import_object。

版本 2.1 中新增: autosectionlabel.<document name>。

版本 3.1 中新增: toc.circular。

版本 3.3 中新增: epub.duplicated_toc_entry。

版本 4.3 中新增: toc.excluded 和 toc.not_readable。

版本 4.5 中新增: i18n.inconsistent_references。

版本 7.1 中新增: index。

版本 7.3 中新增: config.cache、intersphinx.external 和 toc.no_title。

版本 7.4 中新增: docutils 和 autosummary.import_cycle。

版本 8.0 中新增: misc.copy_overwrite。

版本 8.2 中新增: autodoc.mocked_object、duplicate_declaration.c、duplicate_declaration.cpp、i18n.babel、i18n.not_readable、i18n.not_writeable、ref.any、toc.duplicate_entry、toc.empty_glob 和 toc.not_included。

版本 9.0 中新增: duration。

构建器选项

HTML 输出选项

这些选项影响 HTML 输出。其他各种构建器都源自 HTML 输出，并且也使用这些选项。

html_theme

类型:

str

默认:

'alabaster'

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

0.6 版本新增。

版本 1.3 中已更改: 默认主题现在是 'alabaster'。

html_theme_options

类型:

dict[str, Any]

默认:

{}

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

0.6 版本新增。

html_theme_path

类型:

list[str]

默认:

[]

一个路径列表，其中包含自定义主题，可以是子目录或 zip 文件。相对路径是相对于 配置目录 的。

0.6 版本新增。

html_style

类型:

Sequence[str] | str

默认:

()

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

版本 5.1 中已更改: 该值可以是字符串的可迭代对象。

html_title

类型:

str

默认:

'project release documentation'

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

html_short_title

类型:

str

默认:

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。浏览器将其用作选项卡、窗口和书签的图标。它应该是一个 16x16 像素的 PNG、SVG、GIF 或 ICO 文件格式的图标。

示例

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

默认:

无

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

请注意，如果选择的主题不包含侧边栏，例如内置的 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

如果为 True，则 HTML 页脚中会显示“© Copyright …”，并带有 copyright 的值或多个值。

版本 1.0 新增。

html_show_search_summary

类型:

bool

默认:

True

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

版本 4.5 中新增。

html_show_sphinx

类型:

bool

默认:

True

将“使用 Sphinx 创建”添加到 HTML 页脚。

版本 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 选项 是在未安装 Python 绑定时，通过 ctypes 查找 MeCab 库的库名称。

例如

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

'janome' 的选项

user_dic:

user_dic 选项 是 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:: 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 帮助构建器的输出文件基本名称。默认值是删除空格并附加 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 帮助手册的基本名称。默认值是删除空格后的 项目名称。

applehelp_bundle_id

类型:

str

默认:

无

帮助手册捆绑包的捆绑包 ID。

警告

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

applehelp_bundle_version

类型:

str

默认:

'1'

捆绑包版本，作为字符串。

applehelp_dev_region

类型:

str

默认:

'en-us'

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

applehelp_icon

类型:

str

默认:

无

帮助捆绑包图标文件的路径，或 None 表示没有图标。根据 Apple 的文档，这应该是一个 16x16 像素的应用程序图标版本，带有透明背景，保存为 PNG 文件。

applehelp_kb_product

类型:

str

默认:

'project-release'

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

applehelp_kb_url

类型:

str

默认:

无

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

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

applehelp_remote_url

类型:

str

默认:

无

远程内容的 URL。您可以将帮助手册的 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，则使用默认长度。

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

默认:

'项目 帮助'

指定帮助书标题。

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

默认:

'未知'

文档的描述。

版本 1.4 中新增。

版本 1.5 中有更改: 从 epub3_description 重命名

epub_author

类型:

str

默认:

作者 的值

文档的作者。这放在都柏林核心元数据中。

epub_contributor

类型:

str

默认:

'未知'

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

版本 1.4 中新增。

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

epub_language

类型:

str

默认:

language 的值

文档的语言。这放在都柏林核心元数据中。

epub_publisher

类型:

str

默认:

作者 的值

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

epub_copyright

类型:

str

默认:

版权 的值

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

epub_identifier

类型:

str

默认:

'未知'

文档的标识符。这放在都柏林核心元数据中。对于已出版的文档，这是 ISBN 号，但您也可以使用替代方案，例如项目主页。

epub_scheme

类型:

str

默认:

'未知'

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

epub_uid

类型:

str

默认:

'未知'

文档的唯一标识符。这放在都柏林核心元数据中。您可以使用 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 文件列表。条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典的元组。filename 必须相对于 html_static_path，或者是一个带有方案的完整 URI，例如 'https://example.org/style.css'。attributes 字典用于 <link> 标签的属性。有关更多信息，请参阅 html_css_files。

版本 1.8 中新增。

epub_guide

类型:

Sequence[tuple[str, str, str]]

默认:

()

content.opf 的 guide 元素的元数据。这是一个包含可选 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

类型:

序列[str]

默认:

[]

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

epub_tocdepth

类型:

int

默认:

3

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

提示

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

epub_tocdup

类型:

bool

默认:

True

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

epub_tocscope

类型:

'default' | 'includehidden'

默认:

'default'

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

'default'

包含所有未隐藏的 ToC 条目

'includehidden'

包含所有 ToC 条目

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

'否'

不显示 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_写作_模式	'horizontal'	'vertical'
书写模式	horizontal-tb	vertical-rl
页面进程	从左到右	从右到左
iBook 的滚动主题支持	滚动轴是垂直的。	滚动轴是水平的。

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 文档在 ToC 树中引用的所有文档都将包含在 LaTeX 文件中。（如果您想为 LaTeX 构建使用默认主文档，请在此处提供您的 master_doc。）

targetname

输出目录中 LaTeX 文件的文件名。

标题

LaTeX 文档标题。可以为空以使用 startdoc 文档的标题。这作为 LaTeX 标记插入，因此反斜杠或与号等特殊字符如果按字面插入，则必须用适当的 LaTeX 命令表示。

作者

LaTeX 文档的作者。与 title 相同的 LaTeX 标记注意事项适用。使用 \\and 分隔多个作者，例如：'John \\and Sarah'（反斜杠必须经过 Python 转义才能到达 LaTeX）。

主题

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'

默认:

无

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

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

版本 1.4 中新增。

latex_appendices

类型:

序列[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'

默认:

'否'

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

'否'

不显示 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 条水平线（如果有标题，则为 3 条），使用 booktabs 包。

'borderless'

完全没有线条。

'colorrows'

表格行以交替的背景颜色渲染。自定义它们的界面是通过 专用键 的 sphinxsetup 配置设置。

重要

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

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

目前识别的类有 booktabs、borderless、standard、colorrows、nocolorrows。后两者可以与前三者中的任何一个组合。 standard 类生成带有水平线和垂直线的表格（在 Sphinx 6.0.0 之前是默认值）。

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

注意

• 在 LaTeX 中硬编码，即使通过列规范设置了列颜色（参见 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 类用于单个表格，无需额外包（因为 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，但只要某些索引术语使用语言脚本中的非 ASCII 字符，就建议对非英语文档使用 True。如果 latex_use_xindy 保留其默认值 False，尝试索引以非 ASCII 字符开头的术语将破坏构建。

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

版本 1.8 中新增。

latex_elements

类型:

dict[str, str]

默认:

{}

版本 0.5 中新增。

请参阅 latex_elements 的完整文档.

latex_docclass

类型:

dict[str, str]

默认:

{}

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

版本 1.0 新增。

版本 1.5 中有更改: 在日语文档（language 是 'ja'）中，默认情况下，'howto' 使用 'jreport'，'manual' 使用 'jsbook'。

latex_additional_files

类型:

序列[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

手册

用于编写手册的 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 文档在 ToC 树中引用的所有文档都将包含在手册页中。（如果您想为手册页构建使用默认主文档，请在此处提供您的 master_doc。）

name

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

description

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

authors

包含作者的字符串列表，或单个字符串。如果您不想自动在手册页中生成 AUTHORS 部分，则可以为空字符串或列表。

section

手册页部分。用于输出文件名以及手册页标题。

版本 1.0 新增。

man_show_urls

类型:

bool

默认:

False

在链接后添加 URL 地址。

版本 1.1 新增。

man_make_section_directory

类型:

bool

默认:

True

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

在版本 3.3 中新增。

版本 4.0 中有更改: 默认值现在为 False（以前为 True）。

版本 4.0.2 中有更改: 恢复默认值的更改。

Texinfo 输出选项

这些选项会影响 Texinfo 输出。

texinfo_documents

类型:

Sequence[tuple[str, str, str, str, str, str, str, bool]]

默认:

默认 Texinfo 文档

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

startdocname

指定 Texinfo 文件主文档的 文档名称 的字符串。startdoc 文档在 ToC 树中引用的所有文档都将包含在 Texinfo 文件中。（如果您想为 Texinfo 构建使用默认主文档，请在此处提供您的 master_doc。）

targetname

输出目录中 Texinfo 文件的文件名（无扩展名）。

标题

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

类型:

序列[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]

默认:

{}

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

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

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

'否'

不显示 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

默认:

'非导航'

qthelp 输出的 HTML 主题。

qthelp_theme_options

类型:

dict[str, Any]

默认:

{}

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

XML 输出选项

xml_pretty

类型:

bool

默认:

True

美化打印 XML。

版本 1.2 中新增。

链接检查构建器选项

过滤

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

linkcheck_allowed_redirects

类型:

dict[str, str]

一个字典，将源 URI 的模式映射到规范 URI 的模式。当以下情况发生时，linkcheck 构建器会将重定向链接视为“工作”：

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

• 重定向位置与规范 URI 模式匹配。

当 linkcheck 构建器发现不符合上述规则的重定向链接时，它会发出警告。这在使用 警告失败模式 时检测意外重定向可能很有用。

示例

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

版本 4.1 新增。

版本 9.0 中有更改: 现在可以将 linkcheck_allowed_redirects 设置为空字典，以便在 linkcheck 构建器遇到的所有重定向上发出警告。

linkcheck_anchors

类型:

bool

默认:

True

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

版本 1.2 中新增。

linkcheck_anchors_ignore

类型:

序列[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

类型:

序列[str]

默认:

()

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

版本 7.1 新增。

linkcheck_exclude_documents

类型:

序列[str]

默认:

()

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

示例

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

4.4 版本新增。

linkcheck_ignore

类型:

序列[str]

默认:

()

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

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

示例

linkcheck_ignore = [r'https://:\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 库理解的任何内容（有关详细信息，请参阅 请求身份验证）。

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_case_insensitive_urls

类型:

Set[str] | Sequence[str]

默认:

()

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

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

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

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

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

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

linkcheck_case_insensitive_urls = ['.*']

注意

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

在版本 9.0 中新增。

linkcheck_rate_limit_timeout

类型:

int

默认:

300

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

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

在版本 3.4 中新增。

linkcheck_report_timeouts_as_broken

类型:

bool

默认:

False

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

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

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

在声明URL损坏之前，linkcheck 构建器将尝试检查URL的次数。

版本 1.4 中新增。

linkcheck_timeout

类型:

int

默认:

30

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

版本 1.1 新增。

linkcheck_workers

类型:

int

默认:

5

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

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

类型:

序列[str]

默认:

()

解析器应额外接受作为属性的字符串序列。例如，当 #define 已用于属性以实现可移植性时，可以使用此功能。

示例

c_id_attributes = [
    'my_id_attribute',
]

3.0 版本新增。

7.4 版本更改: c_id_attributes 现在可以是元组。

c_maximum_signature_line_length

类型:

int | None

默认:

无

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

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

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

版本 7.1 新增。

c_paren_attributes

类型:

序列[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

类型:

序列[str]

默认:

()

解析器应额外接受作为属性的字符串序列。例如，当 #define 已用于属性以实现可移植性时，可以使用此功能。

示例

cpp_id_attributes = [
    'my_id_attribute',
]

版本 1.5 新增。

7.4 版本更改: cpp_id_attributes 现在可以是元组。

cpp_index_common_prefix

类型:

序列[str]

默认:

()

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

示例

cpp_index_common_prefix = [
    'awesome_lib::',
]

版本 1.5 新增。

cpp_maximum_signature_line_length

类型:

int | None

默认:

无

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

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

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

版本 7.1 新增。

cpp_paren_attributes

类型:

序列[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时，没有最大长度，整个签名将显示在单个逻辑行上。

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

版本 7.1 新增。

javascript_trailing_comma_in_multi_line_signatures

类型:

bool

默认:

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时，没有最大长度，整个签名将显示在单个逻辑行上。

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

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

8.2 版本新增。

python_use_unqualified_type_names

类型:

bool

默认:

False

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

4.0 版本新增。

注意

此功能处于实验阶段。

trim_doctest_flags

类型:

bool

默认:

True

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

版本 1.0 新增。

1.1 版本更改: 现在也移除 <BLANKLINE>。

扩展选项

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

示例配置文件

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

上一页

交叉引用

下一页

构建器