配置¶

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

可选文件 docutils.conf 可以添加到配置目录中进行调整 Docutils 配置，如果没有被Sphinx覆盖或设置的话。

需要注意的重要事项：

如果未另行记录，则值必须为字符串，其缺省值为空字符串。
术语“完全限定名称”（CLARN）指的是命名模块内可导入Python对象的字符串;例如，完全限定名称 "sphinx.builders.Builder" 意味着 Builder 阶级 sphinx.builders module.
文档名称使用 / 作为路径分隔符，并且不包含文件扩展名。

在允许使用全局风格模式的情况下，您可以使用标准的shell结构 (* , ?, [...], and [!...]) with the feature that none of these will match slashes (/). A double star `` **`` can be used to match any sequence of characters * 包括 * 斜线。

小技巧

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

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

配置命名空间的内容是pickle的（以便Sphinx可以在配置更改时发现），因此它可能不包含不可pickle的值--使用将它们从命名空间中删除 del 如果合适的话。模块会自动删除，因此不需要删除导入的模块。

项目标签¶

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

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

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

项目信息¶

project¶

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

有记录的项目名称。示例：

project = 'Thermidor'

author¶

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

该项目的作者。示例：

author = 'Joe Bloggs'

copyright¶

project_copyright¶

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

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

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

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

Added in version 3.5: 的 project_copyright alias.

version¶

类型:: str
默认:: ''

主要项目版本，用作 |version| default substitution .

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

如果您的项目没有在“完整”和“主要”版本之间做出有意义的区分，请同时设置 version 和 release 达到相同的价值。

release¶

类型:: str
默认:: ''

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

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

如果您的项目没有在“完整”和“主要”版本之间做出有意义的区分，请同时设置 version 和 release 达到相同的价值。

常规配置¶

needs_sphinx¶

类型:: str
默认:: ''

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

Added in version 1.0.

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

extensions¶

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

作为模块名称的字符串列表 Sphinx extensions .这些可以是与Sphinx捆绑的扩展（名为 sphinx.ext.* ）或自定义第一方或第三方扩展。

要使用第三方扩展，您必须确保已安装该扩展并将其包含在 extensions 列表，像这样：

extensions = [
    ...
    'numpydoc',
]

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

确保修改时使用绝对路径 sys.path .如果您的自定义扩展位于相对于 configuration directory ，使用 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' form.不必为所有扩展指定要求，仅为您想要检查的扩展指定要求。示例：

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

这需要扩展在 setup() 功能看到 SphinxAPI 了解详情。

Added in version 1.3.

manpages_url¶

类型:: str
默认:: ''

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

page: 手册页 (man )
section: 手册部分 (1 )
path: 指定的原始手册页面和部分 (man(1) )

它还支持将手册页指定为 man.1 。

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

Added in version 1.7.

today¶

today_fmt¶

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

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

的默认值 today 是 '' ，默认为 today_fmt 是 '%b %d, %Y' (or，如果启用翻译 language ，所选区域设置的等效格式）。

图形编号选项¶

numfig¶

类型:: bool
默认:: False

如果 True 、图形、表格和代码块如果有标题，就会自动编号。的 numref 角色已启用。到目前为止，只有HTML和LaTeX构建者遵守。

备注

无论是否启用此选项，LaTeX生成器都会始终分配编号。

Added in version 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',
}

Added in version 1.3.

numfig_secnum_depth¶

类型:: int
默认:: 1

如果设置为 0 、图形、表格和代码块从 1 .
如果 1 ，编号将是 x.1 , x.2 , ...与 x 代表段号。(If没有顶层部分，不会添加前置）。这自然仅在通过 :numbered: 选项 toctree 指令。
如果 2 ，编号将是 x.y.1, x.y.2, ... with x representing the section number and y the sub-section number. If located directly under a section, there will be no y. 前置，如果没有顶级部分，则不会添加前置。
遵循上述规则，可以使用任何其他正整数。

Added in version 1.3.

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

突出显示的选项¶

highlight_language¶

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

突出显示源代码的默认语言。默认值为 'default' ，如果突出显示为Python代码失败，则会抑制警告。

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

Added in version 0.5.

在 1.4 版本发生变更: 默认为现在 'default' .

highlight_options¶

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

将Pygents词典名称映射到其选项的词典。这些都是词典特定的;有关每个都理解的选项，请参阅 Pygments documentation .

示例：

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

Added in version 1.3.

在 3.5 版本发生变更: 允许为多个lexer配置突出显示选项。

pygments_style¶

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

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

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

HTTP请求的选项¶

tls_verify¶

类型:: bool
默认:: True

如果为True，Sphinx将验证服务器证书。

Added in version 1.5.

tls_cacerts¶

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

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

Added in version 1.5.

小技巧

Sphinx使用 requests 内部作为一个HTTP库。如果 tls_cacerts 未设置，则Sphinx退回到请求的默认行为。看到 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请求。

Added in version 2.3.

国际化的选择¶

这些选择影响狮身克斯的 Native Language Support .请参阅文档国际化有关详细信息

language¶

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

文档编写语言的代码。Sphinx自动生成的任何文本都将使用该语言。此外，Sphinx将尝试用从 locale_dirs .Sphinx将搜索由以下名称命名的特定语言图形 figure_language_filename (e.g.德国版 myfigure.png 将 myfigure.de.png 默认设置），并将其替换为原始图形。在LaTeX构建器中，将选择合适的语言作为 Babel 包.

Added in version 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 module.

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

备注

的 -v option to sphinx-build 检查 locale_dirs 设置正在按预期工作。如果找不到消息目录目录，则会发出调试消息。

Added in version 0.5.

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

gettext_allow_fuzzy_translations¶

类型:: bool
默认:: False

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

Added in version 4.3.

gettext_compact¶

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

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

与 gettext_compact = True ，该文件 markup/code.rst 最终进入 markup 文本域。此选项设置为 False ，是的 markup/code .此选项设置为 'sample' ，是的 sample .

Added in version 1.1.

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

gettext_uuid¶

类型:: bool
默认:: False

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

为每个 msgid 在 .pot 文件.
计算新msgid和之前保存的旧msgid之间的相似性。(This计算可能需要很长时间。）

小技巧

如果您想加速计算，可以使用第三方套件 (Levenshtein) 通过运行 pip install levenshtein .

Added in version 1.3.

gettext_location¶

类型:: bool
默认:: True

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

Added in version 1.3.

gettext_auto_build¶

类型:: bool
默认:: True

如果 True ，Sphinx建造了一个 .mo 每个翻译目录文件的文件。

Added in version 1.3.

gettext_additional_targets¶

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

使 gettext 某些元素类型的翻译。示例：

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

支持以下元素类型：

'index' --指数术语
'literal-block' --文字块 (:: 注释和 code-block 指令）
'doctest-block' --docest块
'raw' --原始内容
'image' -- image/figure uri

Added in version 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}'

Added in version 1.4.

在 1.5 版本发生变更: 增列 {path} 和 {basename} 代币。

在 3.2 版本发生变更: 增列 {docpath} 代币。

translation_progress_classes¶

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

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

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

Added in version 7.1.

标记选项¶

default_role¶

类型:: str
默认:: None

用作默认角色（即标记的文本）的reStructured文本角色（内置或Sphinx扩展）的名称 `like this .这可以设置为 :code-py:'py:obj'` 使 `filter '对Python函数“滤镜”的交叉引用。

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

Added in version 0.4.

keep_warnings¶

类型:: bool
默认:: False

将警告保留为渲染文档中的“系统消息”段落。当出现以下情况时，收件箱总是被写入标准错误流 sphinx-build 无论此设置如何，都将运行。

Added in version 0.5.

option_emphasise_placeholders¶

类型:: bool
默认:: False

启用后，强调中的占位符 option 指令。要显示字面大括号，请使用反斜线进行大小写 (\{ ).例如， option_emphasise_placeholders=True 和 .. option:: -foption={TYPE} 将呈现与 TYPE 强调。

Added in version 5.1.

primary_domain¶

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

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

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

primary_domain = 'cpp'

Added in version 1.0.

rst_epilog¶

类型:: str
默认:: ''

reStructuredtext字符串，将包含在读取的每个源文件的结尾。这是添加每个文件中都应该可用的替换的可能地方（另一个是 rst_prolog ).示例：

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

Added in version 0.6.

rst_prolog¶

类型:: str
默认:: ''

reStructuredtext字符串，将包含在读取的每个源文件的开头。这是添加每个文件中都应该可用的替换的可能地方（另一个是 rst_epilog ).示例：

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

Added in version 1.0.

show_authors¶

类型:: bool
默认:: False

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

trim_footnote_reference_space¶

类型:: bool
默认:: False

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

Added in version 0.6.

数学选项¶

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

math_eqref_format¶

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

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

示例： 'Eq.{number}' 被呈现为，例如， Eq.10 。

Added in version 1.7.

math_number_all¶

类型:: bool
默认:: False

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

math_number_all = True

Added in version 1.4.

math_numfig¶

类型:: bool
默认:: True

如果 True 时，显示的数学方程式会在页面上进行编号 numfig 已启用。的 numfig_secnum_depth 环境受到尊重。的 eq ，而不是 numref ，必须使用role来引用公式编号。

Added in version 1.7.

math_numsep¶

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

一个字符串，定义段号和方程号之间的分隔符，当 numfig 被启用并且 numfig_secnum_depth 是积极的。

例如： '-' 被渲染为 1.2-3 .

Added in version 7.4.

nitpicky模式的选项¶

nitpicky¶

类型:: bool
默认:: False

如果出现以下情况，则启用吹毛求疵模式 True .在吹毛求疵模式下，Sphinx会警告 all 找不到目标的引用。建议新项目使用这一点，因为它可以确保所有引用都指向有效目标。

您可以使用临时激活此模式 --nitpicky 命令行选项。看到 nitpick_ignore 寻求一种将缺失的引用标记为“已知缺失”的方法。

nitpicky = True

Added in version 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'),
}

Added in version 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.*') 将忽略所有以开头的Python实体的吹毛求疵警告 'foo' 并且具有 'bar.B' 在其中，例如 ('py:const', 'foo_package.bar.BAZ_VALUE') 或 ('py:class', 'food.bar.Barman') .

Added in version 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 )。

Added in version 7.1.

strip_signature_backslash¶

类型:: bool
默认:: False

启用反斜线剥离后，每次出现 \\ 域指令将更改为 \ ，即使是在字符串字面量中。这是3.0版本之前的行为，并将此变量设置为 True 将恢复这种行为。

Added in version 3.0.

toc_object_entries¶

类型:: bool
默认:: True

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

Added in version 5.2.

toc_object_entries_show_parents¶

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

确定域对象（函数、类、属性等）如何显示在其目录条目中。

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

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

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

Added in version 5.2.

源文件的选项¶

exclude_patterns¶

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

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

示例模式：

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

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

Added in version 1.0.

include_patterns¶

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

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

示例模式：

'**' --源目录和子目录中的所有文件，以递进方式
'library/xml' --只是 library/xml 目录
'library/xml*' --所有文件和目录，以 library/xml
'**/doc' --全部 doc 目录（如果文档与源文件共存，这可能很有用）

Added in version 5.1.

master_doc¶

root_doc¶

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

Sphinx基于 toctree 源文件中包含的指令。这设置包含母版文档的名称 toctree 指令，因此是整个树的根。示例：

master_doc = 'contents'

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

Added in version 4.0: 的 root_doc alias.

source_encoding¶

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

所有源文件的文件编码。建议的编码是 'utf-8-sig' .

Added in version 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选项¶

smartquotes¶

类型:: bool
默认:: True

如果 True ， Smart Quotes transform 将用于将引号和破折号转换为印刷正确的实体。

Added in version 1.6.6: 取代现已删除的 html_use_smartypants .默认情况下，它适用于所有构建者，除了 man 和 text （见 smartquotes_excludes .)

备注

A docutils.conf file located in the configuration directory (or a global ~/.docutils file) is obeyed unconditionally if it deactivates smart quotes via the corresponding Docutils option. 但如果它 activates 他们然后 smartquotes 会占上风

smartquotes_action¶

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

自定义智能报价转换。有关允许的代码，请参阅下文。默认 'qDe' 教育正常 q uote字符 " , ' ，嗯-嗯- D 灰烬 --- , -- ，而且 e lipses ... ..

'q': 转换引号
'b': 转换回勾引号 (:literal:`` ''仅限）
'B': 转换回勾引号 (` ''和 :literal:` 单身'）
'd': 转换破折号（转换 -- 到破折号和 --- 以破折号）
'D': 转换破折号（老派）（转换 -- 以破折号和 --- 至破折号）
'i': 转换破折号（倒置老派）（转换 -- 到破折号和 --- 以破折号）
'e': 转换椭圆 ...
'w': 转换 '"' 实体 '"'

Added in version 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' 进入并决定所有人。此外，a make text 以下 make html 需要以表格形式发放 make text SPHINXOPTS="-E" 强制重新解析源文件，因为缓存的文件已经被转换。另一方面，直接使用 sphinx-build 因为它会在每个构建器位置缓存（在其默认使用中）解析的源文件。

提示

例如，有效停用（或自定义）给定构建商的智能报价的替代方法 latex ，就是用 make 这样：

make latex SPHINXOPTS="-D smartquotes_action="

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

Added in version 1.6.6.

模板选项¶

template_bridge¶

类型:: str
默认:: ''

具有可调用（或简单的类）的全限定名称的字符串，返回的实例 TemplateBridge .然后使用此实例来呈现HTML文档，还可能呈现其他构建器（目前是更改构建器）的输出。(Note如果要使用HTML主题，模板桥必须具有主题感知性。）示例：

template_bridge = 'module.CustomTemplateBridge'

templates_path¶

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

包含额外模板（或覆盖内置/主题特定模板的模板）的路径列表。相对路径作为相对于 configuration directory .示例：

templates_path = ['.templates']

在 1.3 版本发生变更: 由于这些文件不是要构建的，因此在发现源文件时会自动排除它们。

警告控制选项¶

show_warning_types¶

类型:: bool
默认:: True

将每个警告的类型作为后缀添加到警告消息中。例如， WARNING: [...] [index] 或 WARNING: [...] [toc.circular] .此设置对于确定要在 suppress_warnings 名单

Added in version 7.3.0.

在 8.0.0 版本发生变更: 默认为现在 True .

suppress_warnings¶

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

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

Added in version 1.4.

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

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

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

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

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

Added in version 1.4: ref.citation , ref.doc , ref.keyword , ref.numref , ref.option , ref.ref ，而且 ref.term .

Added in version 1.4.2: app.add_directive , app.add_generic_role , app.add_node , app.add_role ，而且 app.add_source_parser .

Added in version 1.5: misc.highlighting_failure .

Added in version 1.5.1: epub.unknown_project_files .

Added in version 1.5.2: toc.secnum .

Added in version 1.6: ref.footnote , download.not_readable ，而且 image.not_readable .

Added in version 1.7: ref.python .

Added in version 2.0: autodoc.import_object .

Added in version 2.1: autosectionlabel.<document name> .

Added in version 3.1: toc.circular .

Added in version 3.3: epub.duplicated_toc_entry .

Added in version 4.3: toc.excluded 和 toc.not_readable .

Added in version 4.5: i18n.inconsistent_references .

Added in version 7.1: index .

Added in version 7.3: config.cache , intersphinx.external ，而且 toc.no_title .

Added in version 7.4: docutils 和 autosummary.import_cycle .

Added in version 8.0: misc.copy_overwrite .

Added in version 8.2: autodoc.mocked_object , duplicate_declaration.c , duplicate_declaration.cpp , i18n.babel , i18n.not_readable , i18n.not_writeable , ref.any , toc.duplicate_entry , toc.empty_glob ，而且 toc.not_included .

构建器选项¶

用于HTML输出的选项¶

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

html_theme¶

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

HTML输出的主题。看到 HTML theming section .

Added in version 0.6.

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

html_theme_options¶

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

影响所选主题外观和感觉的选项词典。这些都是特定主题的。理解的选项 builtin themes 描述 here .

Added in version 0.6.

html_theme_path¶

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

包含自定义主题的路径列表，可以是子目录，也可以是zip文件。相对路径作为相对于 configuration directory .

Added in version 0.6.

html_style¶

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

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

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

html_title¶

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

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

html_short_title¶

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

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

Added in version 0.4.

html_baseurl¶

类型:: str
默认:: ''

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

Added in version 1.8.

html_codeblock_linenos_style¶

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

代码块的行号样式。

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

Added in version 3.2.

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

自 4.0 版本弃用.

html_context¶

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

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

Added in version 0.5.

html_logo¶

类型:: str
默认:: ''

如果给出，这必须是图像文件的名称（相对于 configuration directory ）即文档的徽标，或者指向徽标图像文件的URL。它位于侧边栏的顶部;因此其宽度不应超过200像素。

Added in version 0.4.1: 图像文件将被复制到 _static 目录，但前提是该文件还不存在。

在 4.0 版本发生变更: 还接受URL。

html_favicon¶

类型:: str
默认:: ''

如果给出，这必须是图像文件的名称（相对于 configuration directory ）那就是 favicon 文档的，或者指向favicon图像文件的URL。浏览器将其用作选项卡、窗口和书签的图标。它应该是一个16 x 16像素的图标，采用PNG、JPEG、GIF或ICO文件格式。

示例：

html_favicon = 'static/favicon.png'

Added in version 0.4: 图像文件将被复制到 _static ，但前提是该文件尚未存在。

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

html_css_files¶

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

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

示例：

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

特殊属性 priority 可以将其设置为一个整数，以在较早或较晚的步骤中加载CSS文件。详情参考 Sphinx.add_css_file() .

Added in version 1.8.

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

html_js_files¶

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

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

示例：

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

作为一种特殊属性， priority 可以将其设置为一个整数，以在较早或较晚的步骤中加载JavaScript文件。详情参考 Sphinx.add_js_file() .

Added in version 1.8.

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

html_static_path¶

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

包含自定义静态文件（例如样式表或脚本文件）的路径列表。相对路径作为相对于 configuration directory .它们被复制到输出的 _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 .相对路径作为相对于 configuration directory .它们被复制到输出目录。它们将覆盖任何同名的现有文件。

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

Added in version 1.2.

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

html_last_updated_fmt¶

类型:: str
默认:: None

如果设置，则使用给定的 strftime() 格式.空字符串相当于 '%b %d, %Y' (or取决于区域设置的等效物）。

html_last_updated_use_utc¶

类型:: bool
默认:: False

使用GMT/UTC（+00：00）而不是系统的本地时区作为提供给 html_last_updated_fmt .当使用的格式包括时间时，这是最有用的。

html_permalinks¶

类型:: bool
默认:: True

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

Added in version 3.5.

html_permalinks_icon¶

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

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

Added in version 3.5.

html_sidebars¶

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

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

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

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

默认边栏（对于不匹配任何模式的文档）由主题本身定义。内置主题默认使用这些模板： '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 主题。

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

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

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

html_additional_pages¶

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

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

示例：

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

这将呈现模板 custom-download.html.jinja 与页面 download.html .

html_domain_indices¶

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

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

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

示例：

html_domain_indices = {
    'py-modindex',
}

Added in version 1.0.

在 7.4 版本发生变更: 允许并偏好套装类型。

html_use_index¶

类型:: bool
默认:: True

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

Added in version 0.4.

html_split_index¶

类型:: bool
默认:: False

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

Added in version 0.4.

html_copy_source¶

类型:: bool
默认:: True

如果为True，则reStructured文本源包含在HTML构建中，如下 _sources/docname .

html_show_sourcelink¶

类型:: bool
默认:: True

如果为真（和 html_copy_source 也是如此），指向reStructured文本源的链接将添加到侧边栏中。

Added in version 0.6.

html_sourcelink_suffix¶

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

要附加到源链接的后缀（请参阅 html_show_sourcelink ），除非文件已经有此后缀。

Added in version 1.5.

html_use_opensearch¶

类型:: str
默认:: ''

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

Added in version 0.2.

html_file_suffix¶

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

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

Added in version 0.4.

html_link_suffix¶

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

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

Added in version 0.6.

html_show_copyright¶

类型:: bool
默认:: True

如果属实，”©版权.”显示在HTML页脚中，值来自 copyright .

Added in version 1.0.

html_show_search_summary¶

类型:: bool
默认:: True

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

Added in version 4.5.

html_show_sphinx¶

类型:: bool
默认:: True

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

Added in version 0.4.

html_output_encoding¶

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

HTML输出文件的编码。此编码名称必须是有效的Python编码名称和有效的HTML charset 值

Added in version 1.0.

html_compact_lists¶

类型:: bool
默认:: True

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

Added in version 1.0.

html_secnumber_suffix¶

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

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

Added in version 1.0.

html_search_language¶

类型:: str
默认:: The value of 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 .

Added in version 1.1: 支持英语 (en ）和日语 (ja ).

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

html_search_options¶

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

包含搜索语言支持选项的词典。这些选项的含义取决于选择的语言。目前，只有日本和中国支持选项。

日本:

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

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

'sphinx.search.ja.DefaultSplitter': TinySegmenter算法，默认使用。
'sphinx.search.ja.MecabSplitter' :: MeCab绑定要使用此拆分器，需要“mecab”pPython绑定或动态链接库（对于Linux来说是“libmecab.so”，对于Windows来说是“libmecab.DLC”）。
'sphinx.search.ja.JanomeSplitter' :: Janome绑定。要使用此拆分器， Janome 是必需的.

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

选项 'mecab' :

dic_enc:: _`dic_enc option`是MeCab算法的编码。
迪克特:: _`dict option`是用于MeCab算法的字典。
利布:: _' lib选项'是用于通过查找MeCab库的库名称 ctypes 如果未安装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 option`是由指定的用户词典文件的编码 ``user_dic` 选择。默认值为‘UTF8’。

中国:

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

Added in version 1.1.

在 1.4 版本发生变更: 中允许任何自定义拆分器 type 背景为日本人。

html_search_scorer¶

类型:: str
默认:: ''

JavaScript文件的名称（相对于 configuration directory ）实现搜索结果评分器。如果为空，将使用默认值。

评分者必须实现以下接口，并且可以选择定义 score() 用于更细粒度的控制的功能。

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

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

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

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

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

Added in version 1.2.

html_scaled_image_link¶

类型:: bool
默认:: True

链接已使用缩放选项调整大小的图像（ scale , width ，或者 height ）转换为原始的全分辨率图像。这不会覆盖 target 选项 image 指令（如果存在）。

小技巧

要按每个图像禁用此功能，请添加 no-scaled-link 类到图像指令：

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

Added in version 1.3.

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

html_math_renderer¶

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

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

Added in version 1.8.

用于单个HTML输出的选项¶

这些选项会影响单个HTML输出。此生成器源自HTML生成器，因此HTML选项也适用于适当的情况。

singlehtml_sidebars¶

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

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

这与 html_sidebars ，但唯一允许的密钥是 'index' ，并且所有其他键都被忽略。

用于输出HTML帮助的选项¶

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

htmlhelp_basename¶

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

输出HTML帮助生成器的文件基名称。默认值为 project name 空间被删除， doc 追加。

htmlhelp_file_suffix¶

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

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

Added in version 2.0.

htmlhelp_link_suffix¶

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

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

Added in version 2.0.

Apple帮助输出选项¶

Added in version 1.3.

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

备注

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

您可以使用禁用这些工具 applehelp_disable_external_tools ，但在索引器运行 .lproj 捆绑包内的目录。

applehelp_bundle_name¶

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

Apple帮助书的基本手册。默认值为 project name 空间被删除。

applehelp_bundle_id¶

类型:: str
默认:: None

帮助书捆绑包的捆绑包ID。

警告

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

applehelp_bundle_version¶

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

bundle版本，作为字符串。

applehelp_dev_region¶

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

开发区域。按照苹果推荐的设置， 'en-us' .

applehelp_icon¶

类型:: str
默认:: None

帮助捆绑包图标文件的路径或 None 没有图标。根据Apple的文档，这应该是应用程序图标的16 x 16像素版本，背景透明，保存为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' .在运行时，帮助查看器将替换 'product' 的内容来 applehelp_kb_product , 'query' 用户在搜索框中输入的文本，并且 'lang' 使用用户的系统语言。

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

applehelp_remote_url¶

类型:: str
默认:: None

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

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

将此设置为 None 对于没有远程内容。

applehelp_index_anchors¶

类型:: bool
默认:: False

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

applehelp_min_term_length¶

类型:: str
默认:: None

控制帮助索引器的最小期限长度。如果 None ，使用默认长度。

applehelp_stopwords¶

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

语言规范（使用内置的停止词），或停止词plist的路径，或 None 如果您不想使用停止词。默认的停止词plist可以在 /usr/share/hiutil/Stopwords.plist 在撰写本文时，包含以下语言的停止词：

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

applehelp_locale¶

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

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

applehelp_title¶

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

指定帮助书标题。

applehelp_codesign_identity¶

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

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

引用的价值 CODE_SIGN_IDENTITY 环境变量，由Xcode为脚本构建阶段设置，或者 None 如果未设置该变量。

applehelp_codesign_flags¶

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

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

项的值返回到列表 OTHER_CODE_SIGN_FLAGS 环境变量，由Xcode为脚本构建阶段设置，如果未设置该变量，则为空列表。

applehelp_codesign_path¶

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

的路径 codesign 程序.

applehelp_indexer_path¶

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

的路径 hiutil 程序.

applehelp_disable_external_tools¶

类型:: bool
默认:: False

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

这主要适用于测试，或者您想要在非macOS平台上运行Sphinx构建版本，然后出于某种原因在Mac上完成最后步骤的情况。

EPUB输出选项¶

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

备注

这些选项中的某些选项的实际值并不重要，但它们是 Dublin Core metadata .

epub_basename¶

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

EPub文件的基本集。

epub_theme¶

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

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

epub_theme_options¶

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

影响所选主题外观和感觉的选项词典。这些都是特定主题的。理解的选项 builtin themes 描述 here .

Added in version 1.2.

epub_title¶

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

文档的标题。

在 2.0 版本发生变更: 则默认为 project 选项（以前 html_title ).

epub_description¶

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

文档的描述。

Added in version 1.4.

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

epub_author¶

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

该文件的作者。这被放入都柏林核心元数据中。

epub_contributor¶

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

在EPub出版物内容创建中发挥次要作用的个人、组织等的名称。

Added in version 1.4.

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

epub_language¶

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

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

epub_publisher¶

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

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

epub_copyright¶

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

文档的版权。看到 copyright 对于允许的格式。

epub_identifier¶

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

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

epub_scheme¶

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

的出版计划 epub_identifier .这被放入都柏林核心元数据中。对于已出版的书籍，该计划是 'ISBN' .如果您使用项目主页， 'URL' 似乎很合理。

epub_uid¶

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

文档的唯一标识符。这被放入都柏林核心元数据中。您可以使用 XML's Name format string.您不能使用连字符、句号、数字作为第一个字符。

epub_cover¶

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

封面信息。这是一个包含封面图像和html模板的文件名的二元组。渲染的html封面作为书脊中的第一个项目插入 content.opf .如果模板文件名为空，则不会创建html封面。如果tuple为空，则根本不会创建任何覆盖。

例子：

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

Added in version 1.1.

epub_css_files¶

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

CSS文件列表。条目必须是 filename 字符串或包含 filename 串和所述 attributes 字典的 filename 必须相对于 html_static_path ，或具有类似方案的完整URL 'https://example.org/style.css' .的 attributes 词典用于 <link> 标签的属性。详细信息请参见 html_css_files .

Added in version 1.8.

epub_guide¶

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

的指南元素的Meta数据 content.opf .这是一个包含 type ， uri 和 title 可选指南信息的。看到 the OPF documentation 有关详细信息如果可能， cover 和 toc 类型会自动插入。然而，如果默认条目不合适，则可以显式重写类型。

示例：

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

默认值为 () .

epub_pre_files¶

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

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

示例：

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

epub_post_files¶

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

应插入到Sphinx生成的文本后面的其他文件。它是包含文件名和标题的二元组列表。此选项可用于添加附录。如果标题为空，则不会添加任何条目 toc.ncx .

示例：

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

epub_exclude_files¶

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

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

epub_tocdepth¶

类型:: int
默认:: 3

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

小技巧

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

epub_tocdup¶

类型:: bool
默认:: True

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

epub_tocscope¶

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

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

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

Added in version 1.2.

epub_fix_images¶

类型:: bool
默认:: False

尝试修复某些EPub阅读器不支持的图像格式。目前，带有小颜色表的调色板图像正在升级。默认情况下，这是禁用的，因为自动转换可能会丢失信息。您需要Python图像库 (Pillow) 已安装以使用此选项。

Added in version 1.2.

epub_max_image_width¶

类型:: int
默认:: 0

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

Added in version 1.2.

epub_show_urls¶

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

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

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

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

Added in version 1.2.

epub_use_index¶

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

向EPub文档添加索引。

Added in version 1.2.

epub_writing_mode¶

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

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

`epub_writing_mode`	`'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以来，默认字体是NU FreeFont，它可以很好地覆盖拉丁文、西里尔文和希腊字形。

备注

Sphinx 2.0增加了对使用拉丁语言的文档中偶尔出现的西里尔字母和希腊字母或单词的支持， 'pdflatex' . 为了实现这一点， 'fontenc' 关键 latex_elements 必须适当使用。

备注

Contrarily to MathJaX math rendering in HTML output, LaTeX requires some extra configuration to support Unicode literals in math: the only comprehensive solution (as far as we know) is to use 'xelatex' or 'lualatex' and to add r'\usepackage{unicode-math}' (e.g. via the 'preamble' key of latex_elements). You may prefer r'\usepackage[math-style=literal]{unicode-math}' to keep a Unicode literal such as α (U+03B1) as-is in output, rather than being rendered as $\alpha$.

在 2.1.0 版本发生变更: 使用 'xelatex' (and LaTeX包 xeCJK ）默认为中文文档。

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

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

在 4.0 版本发生变更: 使用 'uplatex' 默认情况下，日语文档。

latex_documents¶

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

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

startdocname: 指定 document name LaTeX文件的主文档。引用的所有文件 startdoc ToC树中的文档将包含在LaTeX文件中。(If您想要使用LaTeX构建的默认主文档，请提供您的 master_doc 这里。）
targetname: 输出目录中LaTeX文件的文件名。
title: LaTeX文档标题。可以为空使用的标题 startdoc 文档.这是作为LaTeX标记插入的，所以如果要按字面意思插入，则必须使用适当的LaTeX命令来表示反斜杠或与号等特殊字符。
author: Author for the LaTeX document. The same LaTeX markup caveat as for title applies. Use \\and to separate multiple authors, as in: 'John \\and Sarah' (backslashes must be Python-escaped to reach LaTeX).
theme: LaTeX主题。看到 latex_theme .
toctree_only: 必须 True 或 False .如果属实， startdoc 文档本身不包含在输出中，仅包含它通过ToC树引用的文档。使用此选项，您可以将额外的内容放入显示在HTML中的主文档中，但不能将其放入LaTeX输出中。

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

Added in version 1.2: 在过去，包括您自己的Document类需要您在Document类名称前面加上字符串“spinx”。这再也没有必要了。

latex_logo¶

类型:: str
默认:: ''

如果给出，这必须是图像文件的名称（相对于 configuration directory ）这是文档的徽标。它位于标题页的顶部。

latex_toplevel_sectioning¶

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

此值确定最上面的切片单位。默认设置为 'section' 如果 latex_theme 是 'howto' ，而且 'chapter' 如果 'manual' . 在这两种情况下，替代方案是指定 'part' ，这意味着LaTeX文档将使用 \part 命令

In that case the numbering of sectioning units one level deep gets off-sync with HTML numbering, as by default LaTeX does not reset \chapter numbering (or \section for 'howto' theme) when encountering \part command.

Added in version 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',
}

Added in version 1.0.

在 7.4 版本发生变更: 允许并偏好套装类型。

latex_show_pagerefs¶

类型:: bool
默认:: False

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

Added in version 1.0.

latex_show_urls¶

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

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

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

Added in version 1.0.

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

latex_use_latex_multicolumn¶

类型:: bool
默认:: False

使用标准LaTeX \multicolumn 对于表格中合并的单元格。

False: Sphinx自己的宏用于合并网格表中的单元格。它们允许一般内容（文字块、列表、块引号等.）但如果 tabularcolumns 指令用于注入类型为 >{..} , <{..} , @{..} 作为色谱柱规格。
True: 使用LaTeX标准 \multicolumn ;这与水平合并单元格中的文字块不兼容，如果表是使用 tabulary .

Added in version 1.6.

latex_table_style¶

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

样式类（字符串）列表。目前支持：

'booktabs': 没有垂直线，只有2或3条水平线（如果有标题，则为后者），使用 booktabs 包.
'borderless': 没有任何线条。
'colorrows': 表格行使用交替的背景颜色渲染。自定义它们的界面是通过 dedicated keys 的这个 sphinxsetup 配置设置 .

重要

与 'colorrows' 党风 \rowcolors LaTeX命令变得无操作（该命令有局限性，并且从未正确支持Sphinx在LaTeX中生成的所有类型的表）。请更新您的项目以使用 latex table color configuration 而是钥匙。

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

目前公认的课程是 booktabs , borderless , standard , colorrows , nocolorrows .后两者可以与前三种中的任何一种组合。的 standard 类生成具有水平线和垂直线的表（这是迄今为止Sphinx的默认值）。

如果设置了行颜色，则单行多列合并单元格将遵循行颜色。另见 TableMergeColor{Header,Odd,Even} 在这个 sphinxsetup 配置设置科.

备注

It is hard-coded in LaTeX that a single cell will obey the row colour even if there is a column colour set via \columncolor from a column specification (see tabularcolumns). Sphinx provides \sphinxnorowcolor which can be used in a table column specification like this:
```
>{\columncolor{blue}\sphinxnorowcolor}
```
Sphinx还提供 \sphinxcolorblend 然而，这需要 xcolor 包.这是一个例子：
```
>{\sphinxcolorblend{!95!red}}
```
It means that in this column, the row colours will be slightly tinted by red; refer to xcolor documentation for more on the syntax of its \blendcolors command (a \blendcolors in place of \sphinxcolorblend would modify colours of the cell contents, not of the cell background colour panel...). You can find an example of usage in the 已弃用接口 section of this document in PDF format.

提示

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

提示

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

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

Added in version 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 然后）。
默认值为 True 为 'xelatex' 或 'lualatex' 作为 makeindex 创建 .ind 如果任何索引项以非ASCI字符开头，则文件包含对于UTF-8编码无效字节。与 'lualatex' 这就会破坏PDF构建。
默认值为 False 为 'pdflatex' ，但是 True 一旦某些索引术语使用语言脚本中的非ASC字符，建议非英语文档使用。如果出现以下情况，尝试对第一个字符为非ASC的术语进行索引将破坏构建 latex_use_xindy 默认存在 False .

Sphinx为 xindy 使用的基本分布 'pdflatex' 带有西里尔字母的引擎。与两 'pdflatex' 和Unicode引擎，西里尔文档可以正确处理拉丁名称的索引，即使是那些具有变音符号的名称。

Added in version 1.8.

latex_elements¶

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

Added in version 0.5.

See the full documentation for latex_elements .

latex_docclass¶

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

字典映射 'howto' 和 'manual' 到将用作两个Sphinx类基础的真实文档类的名称。默认设置是使用 'article' 为 'howto' 和 'report' 为 'manual' .

Added in version 1.0.

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

latex_additional_files¶

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

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

注意

Filenames with the .tex extension will be automatically handed over to the PDF build process triggered by sphinx-build -M latexpdf or by make latexpdf. If the file was added only to be \input{} from a modified preamble, you must add a further suffix such as .txt to the filename and adjust the \input{} macro accordingly.

Added in version 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 仅适用于此主题。

Added in version 3.0.

latex_theme_options¶

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

影响所选主题外观和感觉的选项词典。这些都是特定主题的。

Added in version 3.1.

latex_theme_path¶

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

包含自定义LaTeX主题作为子目录的路径列表。相对路径作为相对于 configuration directory .

Added in version 3.0.

用于文本输出的选项¶

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

text_add_secnumbers¶

类型:: bool
默认:: True

在文本输出中包括节号。

Added in version 1.7.

text_newlines¶

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

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

'unix': 使用Uniix风格的行结尾 (\n ).
'windows': 使用Windows风格的线结尾 (\r\n ).
'native': 使用文档构建平台的行结束风格。

Added in version 1.1.

text_secnumber_suffix¶

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

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

Added in version 1.7.

text_sectionchars¶

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

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

Added in version 1.1.

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

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

man_pages¶

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

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

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

Added in version 1.0.

man_show_urls¶

类型:: bool
默认:: False

链接后添加URL地址。

Added in version 1.1.

man_make_section_directory¶

类型:: bool
默认:: True

在生成手册页上创建一个节目录。

Added in version 3.3.

在 4.0 版本发生变更: 默认为现在 False （以前 True ).

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

用于纹理信息输出的选项¶

这些选项会影响纹理信息输出。

texinfo_documents¶

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

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

startdocname: 指定 document name Texinfo文件的主文档。引用的所有文件 startdoc ToC树中的文档将包含在Texinfo文件中。(If您想要使用Texinfo构建的默认主文档，请提供您的 master_doc 这里。）
targetname: 输出目录中的文本信息文件的文件名(无扩展名)。
title: Texinfo文档标题。可以为空使用的标题 startdoc 文档. 作为Texinfo标记插入，因此特殊字符，例如 @ 和 {} 需要被逸出才能按字面意思插入。
author: Texinfo文档的作者。作为Texinfo标记插入。使用 @* 将多个作者分开，例如： 'John@*Sarah' .
dir_entry: 将出现在顶层的名称 DIR 菜单文件。
description: 要在顶层显示的描述性文本 DIR 菜单文件。
category: 指定此条目将显示在顶级中的节 DIR 菜单文件。
toctree_only: 必须 True 或 False .如果属实， startdoc 文档本身不包含在输出中，仅包含它通过ToC树引用的文档。使用此选项，您可以在HTML中显示的主文档中放置额外的内容，但不显示Texinfo输出。

Added in version 1.1.

texinfo_appendices¶

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

作为所有手册附录的文件名称列表。

Added in version 1.1.

texinfo_cross_references¶

类型:: bool
默认:: True

在文档中生成内联引用。禁用内联引用可以使信息文件在独立阅读器中更具可读性 (info ).

Added in version 4.4.

texinfo_domain_indices¶

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

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

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

示例：

texinfo_domain_indices = {
    'py-modindex',
}

Added in version 1.1.

在 7.4 版本发生变更: 允许并偏好套装类型。

texinfo_elements¶

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

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

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

'paragraphindent'
默认用于重写每个段落第一行的空白数 2 .指定 0 没有凹痕。

'exampleindent'
默认为示例或文字块的行插入的空间数 4 .指定 0 没有凹痕。

'preamble'
在文件开头附近插入的纹理信息标记。

'copying'
插入在 @copying 块并显示在标题之后。默认值由标识项目的简单标题页组成。
由其他选项设置、因此不应被重写的键是 'author' , 'body' , 'date' , 'direntry' 'filename' , 'project' , 'release' ，而且 'title' .

Added in version 1.1.

texinfo_no_detailmenu¶

类型:: bool
默认:: False

不产生 @detailmenu 在“Top”节点的菜单中，包含文档中每个子节点的条目。

Added in version 1.2.

texinfo_show_urls¶

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

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

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

Added in version 1.1.

QtHelp输出选项¶

这些选项会影响qthelp的产出。此生成器源自HTML生成器，因此HTML选项也适用于适当的情况。

qthelp_basename¶

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

qthelp文件的基本参数。

qthelp_namespace¶

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

qthelp文件的命名空间。

qthelp_theme¶

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

qthelp输出的HTML主题。

qthelp_theme_options¶

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

影响所选主题外观和感觉的选项词典。这些都是特定主题的。理解的选项 builtin themes 描述 here .

可选择的可选择性¶

xml_pretty¶

类型:: bool
默认:: True

漂亮地打印该文档。

Added in version 1.2.

链接检查构建器的选项¶

过滤¶

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

linkcheck_allowed_redirects¶

类型:: dict[str, str]

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

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

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

示例：

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

Added in version 4.1.

在 8.3 版本发生变更: 设置 linkcheck_allowed_redirects 现在可以使用到空字典来警告 linkcheck 建造者。

linkcheck_anchors¶

类型:: bool
默认:: True

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

Added in version 1.2.

linkcheck_anchors_ignore¶

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

与 linkcheck 在检查链接中锚的有效性时，构建者应该跳过。例如，这允许跳过网站的JavaScript添加的锚。

小技巧

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

备注

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

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

Added in version 1.5.

linkcheck_anchors_ignore_for_url¶

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

与 linkcheck 构建器不应检查锚的有效性。这允许跳过每页的锚点检查，同时仍然检查页面本身的有效性。

Added in version 7.1.

linkcheck_exclude_documents¶

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

与其中 linkcheck 构建者不应检查链接的有效性。这可用于允许文档的遗留或历史部分中的链接衰减。

示例：

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

Added in version 4.4.

linkcheck_ignore¶

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

与uri匹配的正规表达式列表，在执行 linkcheck build.

服务器发出的匹配重定向 ignored URIs 不会被遵循。

示例：

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

Added in version 1.1.

HTTP请求¶

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

linkcheck_auth¶

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

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

的列表 (regex_pattern, auth_info) 其中项为：

regex_pattern: 与URI匹配的正则表达式。
auth_info: 用于该URL的身份验证信息。该值可以是 requests 图书馆（请参阅 requests authentication 详情）。

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

示例：

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

Added in version 2.3.

linkcheck_allow_unauthorized¶

类型:: bool
默认:: False

当Web服务器以HTT401（未经授权）响应进行响应时， linkcheck 建设者将该链接视为“断裂”。要改变该行为，请将此选项设置为 True .

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

Added in version 7.3.

linkcheck_rate_limit_timeout¶

类型:: int
默认:: 300

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

的 linkcheck 生成器始终尊重服务器何时重新尝试的指示（使用 Retry-After 标题）。否则， linkcheck 在尝试之前等待一分钟，并将尝试之间的等待时间不断增加一倍，直到成功或超过 linkcheck_rate_limit_timeout (in秒）。自定义超时应指定为秒数。

Added in version 3.4.

linkcheck_report_timeouts_as_broken¶

类型:: bool
默认:: False

如果 linkcheck_timeout 在等待超链接的响应时到期， linkcheck 构建者将将该链接报告为 timeout 在默认情况下将超时报告为 broken 相反，您可以设置 linkcheck_report_timeouts_as_broken 到 True .

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

Added in version 7.3.

linkcheck_request_headers¶

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

将URL（无路径）映射到HTTP请求标头的字典。

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

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

示例：

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

Added in version 3.1.

linkcheck_retries¶

类型:: int
默认:: 1

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

Added in version 1.4.

linkcheck_timeout¶

类型:: int
默认:: 30

持续时间（秒） linkcheck 生成器将在每次超链接请求后等待响应。

Added in version 1.1.

linkcheck_workers¶

类型:: int
默认:: 5

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

Added in version 1.1.

域名选项¶

针对C域的选项¶

c_extra_keywords¶

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

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

Added in version 4.0.3.

在 7.4 版本发生变更: c_extra_keywords 现在可以是一套了。

c_id_attributes¶

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

解析器应额外接受作为属性的字符串序列。例如，这可以用于以下情况 #define 已用于属性和可移植性。

示例：

c_id_attributes = [
    'my_id_attribute',
]

Added in version 3.0.

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

c_maximum_signature_line_length¶

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

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

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

这是一个特定于域的设置， maximum_signature_line_length .

Added in version 7.1.

c_paren_attributes¶

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

解析器应额外接受的字符串序列作为具有一个参数的属性。即如果 my_align_as 在列表中，那么 my_align_as(X) 被解析为所有字符串的属性 X 有平衡牙套的 (() , [] ，而且 {} ).例如，这可以用于以下情况 #define 已用于属性和可移植性。

示例：

c_paren_attributes = [
    'my_align_as',
]

Added in version 3.0.

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

C++域的选项¶

cpp_id_attributes¶

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

解析器应额外接受作为属性的字符串序列。例如，这可以用于以下情况 #define 已用于属性和可移植性。

示例：

cpp_id_attributes = [
    'my_id_attribute',
]

Added in version 1.5.

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

cpp_index_common_prefix¶

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

在全局索引中对C++对象进行排序时将被忽略的一系列前置符。

示例：

cpp_index_common_prefix = [
    'awesome_lib::',
]

Added in version 1.5.

cpp_maximum_signature_line_length¶

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

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

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

这是一个特定于域的设置， maximum_signature_line_length .

Added in version 7.1.

cpp_paren_attributes¶

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

解析器应额外接受的字符串序列作为具有一个参数的属性。即如果 my_align_as 在列表中，那么 my_align_as(X) 被解析为所有字符串的属性 X 有平衡牙套的 (() , [] ，而且 {} ).例如，这可以用于以下情况 #define 已用于属性和可移植性。

示例：

cpp_paren_attributes = [
    'my_align_as',
]

Added in version 1.5.

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

用于Java Script域的选项¶

javascript_maximum_signature_line_length¶

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

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

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

这是一个特定于域的设置， maximum_signature_line_length .

Added in version 7.1.

javascript_trailing_comma_in_multi_line_signatures¶

类型:: bool
默认:: True

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

Added in version 8.2.

用于Python域的选项¶

add_module_names¶

类型:: bool
默认:: True

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

modindex_common_prefix¶

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

Python模块索引排序时忽略的前缀列表（例如，如果值是 ['foo.'] 那么 foo.bar 呈列于 B ，而不是 F ).如果您的文档中包含一个单独的包，这将非常方便。

小心

目前仅适用于HTML构建器。

Added in version 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

Added in version 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)

Added in version 7.1.

python_trailing_comma_in_multi_line_signatures¶

类型:: bool
默认:: True

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

Added in version 8.2.

python_use_unqualified_type_names¶

类型:: bool
默认:: False

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

Added in version 4.0.

小心

该功能是实验性的。

trim_doctest_flags¶

类型:: bool
默认:: True

删除docTest标志（评论看起来像 # doctest: FLAG, ... ）在线的末端和 <BLANKLINE> 显示交互式Python会话（即doctests）的所有代码块的标记。查看扩展 doctest 了解包含文档测试的更多可能性。

Added in version 1.0.

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

延期选择权¶

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

示例配置文件¶

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

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

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

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

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

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