配置¶

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

可选的文件 docutils.conf 可以添加到配置目录中,以调整 Docutils 配置,前提是未被 Sphinx 另行覆盖或设置.

重要事项:

如果没有其他文档说明,值必须是字符串,其默认值为空字符串.
术语 “完全合格名称” (FQN) 指的是一个字符串,用于命名模块内可导入的 Python 对象;例如,完全合格名称 "sphinx.builders.Builder" 表示 sphinx.builders 模块中的 Builder 类.
文档名称使用 / 作为路径分隔符,并且不包含文件名扩展名.

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

小技巧

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

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

config命名空间的内容是被序列化的（以便Sphinx可以检测到配置更改）,因此它可能不包含不可序列化的值——如果合适,使用 del 将它们从命名空间中删除.模块会被自动移除,因此不需要删除导入的模块.

项目标签¶

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

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

要查询标签是否被设置,请使用 'tag' in tags .
要添加标签,请使用 tags.add('tag') .
要移除一个标签,请使用 tags.remove('tag') .

项目说明¶

project¶

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

项目的名称.示例:

project = 'Thermidor'

author¶

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

项目的作者.示例:

author = 'Joe Bloggs'

copyright¶

project_copyright¶

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

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

Added in version 3.5: project_copyright 别名.

version¶

类型:: str
默认:: ''

主要项目版本,用作 |version| 默认替换的替代.

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

如果你的项目没有明确区分 “完整” 和 “主要” 版本,请将 version 和 release 设置为相同的值.

release¶

类型:: str
默认:: ''

完整的项目版本,用作 |release| 默认替换的替代品,例如在 HTML 模板中.

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

如果你的项目没有明确区分 “完整” 和 “主要” 版本,请将 version 和 release 设置为相同的值.

一般配置¶

needs_sphinx¶

类型:: str
默认:: ''

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

Added in version 1.0.

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

extensions¶

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

包含字符串的列表,这些字符串是 Sphinx 扩展的模块名.这些可以是与 Sphinx 一起捆绑的扩展（命名为 sphinx.ext.* ）或自定义的第一方或第三方扩展.

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

extensions = [
    ...
    'numpydoc',
]

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

确保在修改 sys.path 时使用绝对路径.如果你的自定义扩展位于相对于配置目录的目录中,请像这样使用 os.path.abspath() :

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

extensions = [
   ...
   'extname',
]

上面所示的目录结构如下所示:

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

needs_extensions¶

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

如果设置了此值,则必须是一个字典,指定 extensions 中扩展的版本要求.版本字符串应采用 'major.minor' 形式.并不是所有扩展都必须指定版本要求,仅对您想要检查的扩展进行指定即可.例如:

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

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

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

Added in version 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生成器始终分配编号,无论此选项是否启用.

Added in version 1.3.

numfig_format¶

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

一个字典,将:code-py:’figure’ 、'table' 、'code-block' 和:code-py:’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 代表节编号.（如果没有顶级节,则不会添加前缀）.这自然仅适用于通过 toctree 指令的 :numbered: 选项激活节编号的情况.
如果 2 ,编号将为 x.y.1 , x.y.2 ,… 其中 x 代表章节编号,而 y 代表子章节编号.如果位于章节下方,则不会有 y. 前缀,如果没有顶级章节,则不会添加前缀.
可以使用任何其他正整数,遵循上述规则.

Added in version 1.3.

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

高亮显示的选项¶

highlight_language¶

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

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

值应该是一个有效的 Pygments 词法分析器名称,详情请参见显示代码示例 .

Added in version 0.5.

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

highlight_options¶

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

一个将Pygments词法分析器名称映射到其选项的字典.这些选项是特定于词法分析器的;有关每个词法分析器理解的选项,请参见 Pygments文档 .

示例:

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

Added in version 1.3.

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

pygments_style¶

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

用于Pygments高亮显示源代码的样式名称.如果未设置,则选择主题的默认样式或:code-py:’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库.如果未设置:confval:!tls_cacerts ,Sphinx将退回到requests的默认行为.有关详细信息,请参见:ref:requests:verification .

user_agent¶

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

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

Added in version 2.3.

国际化选项¶

这些选项会影响 Sphinx 的 本地语言支持.有关详细信息,请参见国际化文档.

language¶

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

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

Added in version 0.5.

在 1.4 版本发生变更: 支持图像替换

在 5.0 版本发生变更: 默认值现在是:code-py:’en’ （之前是:code-py:None ）.

Sphinx目前支持的语言有:

ar – Arabic
bg – Bulgarian
bn – Bengali
ca – Catalan
cak – Kaqchikel
cs – Czech
cy – Welsh
da – Danish
de – German
el – Greek
en – English (default)
eo – Esperanto
es – Spanish
et – Estonian
eu – Basque
fa – Iranian
fi – Finnish
fr – French
he – Hebrew
hi – Hindi
hi_IN – Hindi (India)
hr – Croatian
hu – Hungarian
id – Indonesian
it – Italian
ja – Japanese
ko – Korean
lt – Lithuanian
lv – Latvian
mk – Macedonian
nb_NO – Norwegian Bokmal
ne – Nepali
nl – Dutch
pl – Polish
pt – Portuguese
pt_BR – Brazilian Portuguese
pt_PT – European Portuguese
ro – Romanian
ru – Russian
si – Sinhala
sk – Slovak
sl – Slovenian
sq – Albanian
sr – Serbian
sr@latin – Serbian (Latin)
sr_RS – Serbian (Cyrillic)
sv – Swedish
ta – Tamil
te – Telugu
tr – Turkish
uk_UA – Ukrainian
ur – Urdu
vi – Vietnamese
zh_CN – Simplified Chinese
zh_TW – Traditional Chinese

locale_dirs¶

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

在搜索附加消息目录时查找的目录（参见 language ）,相对于源目录.此路径上的目录由 gettext 模块搜索.

内部消息是从 sphinx 的文本域获取的;因此,如果您将目录 ./locale 添加到此设置中,消息目录（通过 msgfmt 从 .po 格式编译而成）必须位于 ./locale/language/LC_MESSAGES/sphinx.mo .单个文档的文本域取决于 gettext_compact .

备注

The -v option to sphinx-build is useful to check the locale_dirs setting is working as expected. If the message catalog directory not found, debug messages are emitted.

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 ,文档的文本域是其文档名称（docname）,如果它是顶级项目文件,其他情况则为其基础目录.
如果 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 会在消息目录中生成用于版本跟踪的 UUID 信息.它的用途是:

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

小技巧

如果你想加速计算,可以通过运行 pip install levenshtein 使用第三方包(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' – 索引术语
:code-py :’literal-block’ – 字面块（ :: 注释和 code-block 指令）
'doctest-block' – doctest 块
'raw' – 原始内容
'image' – 图像/图形 URI

Added in version 1.3.

在 4.0 版本发生变更: 图像的替代文本默认是翻译的.

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

figure_language_filename¶

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

语言特定图像的文件名格式.可用的格式标记有:

{root}: the filename, including any path component, without the file extension. For example: images/filename.
{path}: the directory path component of the filename, with a trailing slash if non-empty. For example: images/.
{basename}: the filename without the directory path or file extension components. For example: filename.
{ext}: the file extension. For example: .png.
{language}: the translation language. For example: en.
{docpath}: the directory path component for the current document, with a trailing slash if non-empty. For example: dirname/.

默认情况下,图像指令 :code-rst :.. 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

控制是否添加类以指示翻译进度.此设置可能仅被文档翻译者使用,以便快速指示已翻译和未翻译的内容.

真: 将 translated 和 untranslated 类添加到所有可翻译内容的节点.
'翻译': 仅添加 translated 类.
'未翻译': 仅添加 untranslated 类.
假: 不要添加任何类来指示翻译进度.

Added in version 7.1.

选项对于标记¶

default_role¶

类型:: str
默认:: None

默认角色使用的 reStructuredText 角色名称（内置或 Sphinx 扩展）,即标记为```像这样```的文本.可以将其设置为 'py:obj' ,使得```filter```成为 Python 函数 “filter” 的交叉引用.

默认角色可以使用标准的reStructuredText default-role 指令在各个文档中进行设置.

Added in version 0.4.

keep_warnings¶

类型:: bool
默认:: False

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

Added in version 0.5.

option_emphasise_placeholders¶

类型:: bool
默认:: False

当启用时,在 :rst :dir:`option` 指令中强调占位符.要显示字面上的大括号,请使用反斜杠转义（ \{ ）.例如, option_emphasise_placeholders=True 和 .. option:: -foption={TYPE} 将以强调的方式呈现 TYPE .

Added in version 5.1.

primary_domain¶

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

默认域的名称.也可以设置为 None 来禁用默认域.默认值是 'py' ,表示 Python 域.

在其他域中的那些对象（无论域名是明确给出的,还是通过 default-domain 指令选择的）在命名时将会明确地在前面加上域名（例如,当默认域是 C 时,Python 函数将被命名为 “Python function”,而不仅仅是 “function”）.示例:

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 角色.

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 会对所有无法找到的引用发出警告.这个模式推荐用于新项目,因为它能确保所有引用都指向有效的目标.

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

nitpicky = True

Added in version 1.0.

nitpick_ignore¶

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

一组或列表,包含应在生成:confval:”nitpicky mode” <nitpicky> 时被忽略的:code-py:(warning_type, target) 元组.请注意, 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.*') 将忽略所有以 'foo' 开头并且包含 'bar.B' 的 Python 实体的细微警告,比如 ('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 域中看到的（例如:rst:dir: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 风格模式列表.它们与相对于源目录的源文件名进行匹配,所有平台上使用斜杠作为目录分隔符. 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 风格模式的列表,用于查找源文件.它们相对于源目录对源文件名进行匹配,使用斜杠作为所有平台上的目录分隔符.默认情况下,从源目录递归包含所有文件.:confval: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 别名.

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¶

类型:: bool
默认:: True

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

Added in version 1.6.6: 替代现在已移除的 html_use_smartypants .默认情况下,它适用于所有构建器,除了 man 和 text （参见 smartquotes_excludes ）.

备注

一个位于配置目录中的 docutils.conf 文件（或者是一个全局的 ~/.docutils 文件）如果通过相应的 Docutils 选项禁用智能引号,则会被无条件遵循.但是,如果它启用智能引号,则 smartquotes 的设置将占优.

smartquotes_action¶

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

自定义智能引号转换.请参见下面的允许代码.默认的 'qDe' 教育普通 q 引用字符 " , ' , em- 和 en- D 破折号 --- , -- ,以及 e 省略号 ... ..

'q': 转换引号
'b': 转换反引号引号 (:literal:```double’’`仅此而已)
'B': 将反引号引号转换为 (``双 `' 和 ``单’)
'd': 将短横线（将 -- 转换为长破折号,将 --- 转换为短破折号）
'D': 将破折号（老式）转换（将 -- 转换为 en-破折号,并将 --- 转换为 em-破折号）
'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' 条目,它决定了所有目标的行为.此外,执行 make html 后需要以 make text SPHINXOPTS="-E" 的形式发出 make text 命令,以强制重新解析源文件,因为缓存的文件已经被转换.另一方面,直接使用 sphinx-build 时不会出现此问题,因为它在每个构建器的位置缓存（默认情况下）已解析的源文件.

提示

一种有效地停用（或自定义）给定构建器智能引号的替代方法,例如 latex ,是通过以下方式使用 make :

make latex SPHINXOPTS="-D smartquotes_action="

这可以无问题地跟随某些 make html ,与之前的情况相对.

Added in version 1.6.6.

模板选项¶

template_bridge¶

类型:: str
默认:: ''

一个字符串,包含返回 TemplateBridge 实例的可调用（或简单的类）的完全限定名.这个实例用于渲染 HTML 文档,以及可能其他构建器的输出（当前为更改构建器）. （请注意,如果要使用 HTML 主题,则模板桥必须支持主题.）示例:

template_bridge = 'module.CustomTemplateBridge'

templates_path¶

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

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

templates_path = ['.templates']

在 1.3 版本发生变更: 因为这些文件不打算被构建,所以在发现源文件时会自动排除它们.

警告控制选项¶

show_warning_types¶

类型:: bool
默认:: True

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

Added in version 7.3.0.

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

suppress_warnings¶

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

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

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

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

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

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

您可以从这些类型中选择.您也可以仅提供第一个组件,以排除与其相关的所有警告.

Added in version 1.4.

在 1.5 版本发生变更: 新增 misc.highlighting_failure

在 1.5.1 版本发生变更: 添加了 epub.unknown_project_files

在 1.6 版本发生变更: 新增 ref.footnote

在 2.1 版本发生变更: 添加 autosectionlabel.<文档名称>

在 3.3.0 版本发生变更: 添加了 epub.duplicated_toc_entry

在 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 .

Added in version 7.3: 添加了 toc.no_title .

Added in version 8.0: 新增 misc.copy_overwrite .

构建器选项¶

HTML输出选项¶

这些选项会影响HTML输出.其他各种构建器都是基于HTML输出派生的,也会使用这些选项.

html_theme¶

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

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

Added in version 0.6.

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

html_theme_options¶

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

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

Added in version 0.6.

html_theme_path¶

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

包含自定义主题的路径列表,可以是子目录或压缩文件.相对路径视为相对于:term:配置目录 .

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.它用于通过 规范链接关系 指示文档的位置.

Added in version 1.8.

html_codeblock_linenos_style¶

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

代码块的行号样式.

'表格': 使用 <table> 标签显示行号
'内联': 使用 <span> 标签显示行号

Added in version 3.2.

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

自 4.0 版本弃用.

html_context¶

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

一个字典,用于将值传递到模板引擎的上下文中,适用于所有页面.单个值也可以使用:程序:sphinx-build 的:选项:–html-define <sphinx-build –html-define> 命令行选项放入此字典中.

Added in version 0.5.

html_logo¶

类型:: str
默认:: ''

如果提供,这必须是一个图像文件的名称（相对于配置目录的路径）,该图像是文档的logo,或者是指向图像文件的URL.它位于侧边栏的顶部;因此,其宽度不应超过200像素.

Added in version 0.4.1: 图像文件将被复制到 _static 目录,但只有在该目录中尚不存在该文件的情况下.

在 4.0 版本发生变更: 也接受一个网址.

html_favicon¶

类型:: str
默认:: ''

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

示例:

html_favicon = 'static/favicon.png'

Added in version 0.4: 图像文件将被复制到 _static ,但是只有在该文件尚不存在于此时.

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

html_css_files¶

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

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

示例:

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

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

Added in version 1.8.

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

html_js_files¶

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

一个JavaScript文件的列表.条目必须是*文件名*字符串或包含*文件名*字符串和*属性*字典的元组.*文件名*必须相对于:confval: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() .

Added in version 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 版本发生变更: The paths in html_static_path can now contain subdirectories.

在 1.0 版本发生变更: html_static_path 中的条目现在可以是单个文件.

在 1.8 版本发生变更: 在 html_static_path 下面的文件会被排除在源文件之外.

html_extra_path¶

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

包含与文档没有直接关系的额外文件的路径列表,例如 robots.txt 或 .htaccess .相对路径相对于配置目录进行处理.它们将被复制到输出目录,并覆盖任何同名的现有文件.

由于这些文件不用于构建,它们会自动从源文件中排除.

Added in version 1.2.

在 1.4 版本发生变更: extra目录中的点文件将被复制到输出目录.复制额外文件和目录时,它参考了 exclude_patterns ,并且如果路径与模式匹配,则忽略该路径.

html_last_updated_fmt¶

类型:: str
默认:: '%b %d, %Y'

如果设置,将使用给定的 strftime() 格式在页面底部插入一个 ‘最后更新时间:’ 的时间戳.空字符串等同于 '%b %d, %Y' （或与区域设置相关的等效项）.

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 风格的模式 ,在这种情况下,所有匹配的文档将获得指定的侧边栏.（当有多个 glob 风格模式匹配任何文档时,将发出警告.）

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

默认的侧边栏（对于不符合任何模式的文档）是由主题本身定义的.内置主题默认使用以下模板:'localtoc.html' ,:code-py:’relations.html’ ,:code-py:’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

如果为真,则生成特定于领域的索引,此外还有一般索引.例如,对于 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,reStructuredText 源文件将作为 _sources/docname 包含在 HTML 构建中.

html_show_sourcelink¶

类型:: bool
默认:: True

如果为真（并且 html_copy_source 也为真）,将会在侧边栏中添加 reStructuredText 源文件的链接.

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 …”,其值来自 copyright .

Added in version 1.0.

html_show_search_summary¶

类型:: bool
默认:: True

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

Added in version 4.5.

html_show_sphinx¶

类型:: bool
默认:: True

在 HTML 页脚中添加 “使用 Sphinx 创建”.

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

如果为真,一个包含单一段落的所有项的列表和/或一个包含所有项的子列表等…（递归定义）将不会为其任何项使用 <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 – Danish
nl – Dutch
en – English
fi – Finnish
fr – French
de – German
hu – Hungarian
it – Italian
ja – Japanese
no – Norwegian
pt – Portuguese
ro – Romanian
ru – Russian
es – Spanish
sv – Swedish
tr – Turkish
zh – Chinese

小技巧

加速构建速度

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

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

在 1.3 版本发生变更: 添加了额外的语言.

html_search_options¶

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

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

Japanese 日本语:

type – the type of the splitter to use.

其他选项取决于使用的分割器.

'sphinx.search.ja.DefaultSplitter': 默认使用TinySegmenter算法.
'sphinx.search.ja.MecabSplitter' :: MeCab绑定
'sphinx.search.ja.JanomeSplitter' :: Janome 绑定.要使用此分割器,需要 Janome .

自 1.6 版本弃用: ‘mecab’ 、 ‘janome’ 和 ‘default’ 已被弃用.为了保持兼容性, ‘mecab’ 、 ‘janome’ 和 ‘default’``也可以接受.

Options for 'mecab' :

dic_enc:: _ dic_enc 选项是 MeCab 算法的编码.
字典:: _ dict option 是用于 MeCab 算法的字典.
lib:: _ lib option 是通过 ctypes 查找 MeCab 库的库名称,前提是没有安装 Python 绑定.

例如:

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

选项 'janome' :

user_dic:: _ user_dic option 是 Janome 的用户字典文件路径.
user_dic_enc:: _ user_dic_enc 选项是由 user_dic 选项指定的用户字典文件的编码.默认是 ‘utf8’.

中文:

dict: The jieba dictionary path for using a custom dictionary.

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

Added in version 1.2.

html_scaled_image_link¶

类型:: bool
默认:: True

将已使用缩放选项（scale、width*或*height）调整大小的图像链接到其原始全分辨率图像.如果存在,此操作不会覆盖:dudir:image 指令中*target*选项给出的任何链接.

小技巧

要在每个图像的基础上禁用此功能,请将 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帮助生成器.默认值为去掉空格的 项目名称 ,并附加 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 Help 输出选项¶

Added in version 1.3.

这些选项影响Apple Help的输出.该构建器源自HTML构建器,因此HTML选项在适当的情况下也适用.

备注

Apple Help 输出仅在 Mac OS X 10.6 及更高版本上有效,因为它需要 hiutil 和 codesign 命令行工具,这两者均不是开源的.

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

applehelp_bundle_name¶

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

Apple Help Book 的基本名称.默认值是 project name ,去掉空格后.

applehelp_bundle_id¶

类型:: str
默认:: None

帮助书籍包的捆绑 ID.

警告

您*必须*设置此值以便生成 Apple Help.

applehelp_bundle_version¶

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

捆绑版本,作为一个字符串.

applehelp_dev_region¶

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

开发区域.默认为Apple推荐的设置,:code-py:’en-us’ .

applehelp_icon¶

类型:: str
默认:: None

帮助包图标文件的路径,或者使用 None 表示没有图标.根据苹果的文档,这应该是应用程序图标的 16x16 像素版本,带透明背景,保存为 PNG 文件.

applehelp_kb_product¶

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

用于 applehelp_kb_url 的产品标签.

applehelp_kb_url¶

类型:: str
默认:: None

您的知识库服务器的URL,例如 https://example.com/kbsearch.py?p='product'&q='query'&l='lang' .在运行时,帮助查看器将把 '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 网址;有关此主题的更多信息,请参阅Apple文档.

applehelp_min_term_length¶

类型:: str
默认:: None

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

applehelp_stopwords¶

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

要么是语言规范（使用内置的停用词）,要么是停用词plist的路径,或者是:code-py:None ,如果您不想使用停用词.默认的停用词plist可以在 /usr/share/hiutil/Stopwords.plist 找到,截至目前,它包含以下语言的停用词:

德语（ de ）
中文 ( zh )
西班牙语（ es )
法语（ fr )
匈牙利语（ hu ）
意大利语 ( it )
瑞典语（ sv ）

applehelp_locale¶

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

指定生成帮助的区域设置.用于确定帮助书的 Resources 中的 .lproj 目录的名称,并传递给帮助索引器.

applehelp_title¶

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

指定帮助书的标题.

applehelp_codesign_identity¶

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

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

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

applehelp_codesign_flags¶

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

在签署帮助书时,传递给 codesign 的附加参数的列表.

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

applehelp_codesign_path¶

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

指向 codesign 程序的路径.

applehelp_indexer_path¶

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

The path to the hiutil program.

applehelp_disable_external_tools¶

类型:: bool
默认:: False

无论其他设置如何,都不要运行索引器或代码签名工具.

这主要用于测试,或者在某些情况下,您希望在非macOS平台上运行Sphinx构建,然后出于某种原因在Mac上完成最后步骤.

EPUB输出选项¶

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

备注

某些选项的实际值并不重要,但它们是都柏林核心元数据所必需的.

epub_basename¶

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

EPUB文件的基本名称.

epub_theme¶

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

用于EPUB输出的HTML主题.由于默认主题并未针对小屏幕空间进行优化,因此通常不建议使用相同的主题用于HTML和EPUB输出.此操作默认为:code-py:’epub’ ,这是一个旨在节省视觉空间的主题.

epub_theme_options¶

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

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

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

文档的作者.此信息被放入Dublin Core元数据中.

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

文档的版权.

epub_identifier¶

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

文档的标识符.这被放置在都柏林核心元数据中.对于已出版的文档,这是ISBN号码,但您也可以使用其他方案,例如项目主页.

epub_scheme¶

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

该 epub_identifier 的出版方案.此信息将被放入都柏林核心元数据中.对于已出版的书籍,方案为 'ISBN' .如果使用项目主页, 'URL' 看起来是合理的.

epub_uid¶

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

文档的唯一标识符.该标识符放置在Dublin Core元数据中.您可以使用 XML名称格式字符串.首字符不能使用连字符、句点、数字.

epub_cover¶

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

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

示例:

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

Added in version 1.1.

epub_css_files¶

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

一个CSS文件列表.条目必须是一个*文件名*字符串或一个包含*文件名*字符串和*属性*字典的元组.*文件名*必须相对于:confval:html_static_path ,或是具有方案的完整URI,如:code-py:’https://example.org/style.css’ .*属性*字典用于 <link> 标签的属性.有关更多信息,请参见:confval:html_css_files .

Added in version 1.8.

epub_guide¶

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

Meta data for the guide element of content.opf. This is a sequence of tuples containing the type, the uri and the title of the optional guide information. See the OPF documentation for details. If possible, default entries for the cover and toc types are automatically inserted. However, the types can be explicitly overwritten if the default entries are not appropriate.

示例:

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生成的文本后应插入的附加文件.这是一个包含文件名和标题的元组列表.此选项可以用于添加附录.如果标题为空,则不会向:file:toc.ncx 添加条目.

示例:

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

epub_exclude_files¶

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

在构建目录中生成/复制的一系列文件,但不应包含在EPUB文件中.

epub_tocdepth¶

类型:: int
默认:: 3

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

小技巧

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

epub_tocdup¶

类型:: bool
默认:: True

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

epub_tocscope¶

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

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

'默认': 包含所有未隐藏的目录条目
'includehidden': 包括所有目录条目

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 的读者非常有用.该设置可以具有以下值:

'内联': 在括号中内联显示URLs.
‘脚注’: 在脚注中显示网址.
'不': Do not display URLs.

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

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`	‘水平’	‘vertical’
writing-mode	`horizontal-tb`	`vertical-rl`
页面进度	从左到右	从右到左
iBook的滚动主题支持	scroll-axis 是垂直的.	scroll-axis 是水平的.

LaTeX输出选项¶

这些选项会影响 LaTeX 的输出.

latex_engine¶

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

用于构建文档的 LaTeX 引擎.该设置可以具有以下值:

'pdflatex' – PDFLaTeX（默认）
'xelatex' – XeLaTeX
'lualatex' – LuaLaTeX
'platex' – pLaTeX
'uplatex' – upLaTeX（当 language 为 'ja' 时为默认选项）

小心

'pdflatex'‘s support for Unicode characters is limited. If your project uses Unicode characters, setting the engine to 'xelatex' or 'lualatex' and making sure to use an OpenType font with wide-enough glyph coverage is often easier than trying to make 'pdflatex' work with the extra Unicode characters. Since Sphinx 2.0, the default typeface is GNU FreeFont, which has good coverage of Latin, Cyrillic, and Greek glyphs.

备注

Sphinx 2.0 添加了对具有偶尔的西里尔字母或希腊字母或词的拉丁语言文档中 'pdflatex' 的支持.这不是自动的,请参阅 latex_elements 中 'fontenc' 键的讨论.

备注

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

在 2.1.0 版本发生变更: 默认使用 xelatex （和 LaTeX 包 xeCJK ）处理中文文档.

在 2.2.1 版本发生变更: 默认情况下对于希腊文档使用 xelatex .

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

在 4.0 版本发生变更: 默认使用 uplatex 处理日文文档.

latex_documents¶

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

此值决定了如何将文档树分组到 LaTeX 源文件中.它必须是一个元组列表 (startdocname, targetname, title, author, theme, toctree_only) ,其中各项为:

开始文档名称: 指定LaTeX文件主文档的:term:文档名称的字符串.所有在ToC树中由*startdoc*文档引用的文档将会被包含在LaTeX文件中.（如果您想在LaTeX构建中使用默认的主文档,请在此处提供您的:confval:master_doc .）
目标名称: 输出目录中 LaTeX 文件的文件名.
标题: LaTeX 文档标题.可以为空,以使用 startdoc 文档的标题.此内容作为 LaTeX 标记插入,因此特殊字符如反斜杠或和号必须用适当的 LaTeX 命令表示,以便以字面形式插入.
作者: LaTeX 文档的作者.与 title 相同的 LaTeX 标记注意事项适用.使用 \and 分隔多个作者,例如: 'John \and Sarah' （反斜杠必须被 Python 转义以使用 LaTeX）.
主题: LaTeX 主题.参见 latex_theme .
仅目录树: 必须为 True 或 False .如果为True,则 startdoc 文档本身不包含在输出中,仅包括通过目录树引用的文档.使用此选项,您可以在主文档中放置额外内容,这些内容在HTML中可见,但在LaTeX输出中不可见.

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

Added in version 1.2: 在过去,包括您自己的文档类需要将文档类名称前加上字符串 “sphinx”.现在不再需要这样做.

latex_logo¶

类型:: str
默认:: ''

如果提供,这必须是文档徽标的图像文件名称（相对于:term:配置目录的路径）.它位于标题页的顶部.

latex_toplevel_sectioning¶

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

该值确定最上层的分节单位.默认情况下,最上层的分节单位由文档类决定:如果文档类为 howto ,则使用 section ,否则使用 chapter .

请注意,如果 LaTeX 使用 part 命令,则一个层级深的章节单位的编号将与 HTML 编号不匹配,因为 LaTeX 持续编号 chapter （或 howto 的 section ）.

Added in version 1.4.

latex_appendices¶

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

将文档名称的列表附加为所有手册的附录.如果 latex_theme 设置为 'howto' ,则此项将被忽略.

latex_domain_indices¶

类型:: bool | Sequence[str]
默认:: 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 地址.这对于手册的印刷副本非常有用.该设置可以具有以下值:

'不': 不显示网址
‘脚注’: 在脚注中显示网址
'内联': 在括号中inline显示URL

Added in version 1.0.

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

latex_use_latex_multicolumn¶

类型:: bool
默认:: False

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

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

Added in version 1.6.

latex_table_style¶

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

样式类的列表（字符串）.目前支持:

'booktabs': 没有垂直线,只有2或3条水平线（如果有标题的话）,使用booktabs_包.
'无边框': 没有任何行.
'colorrows': 表格行呈现为交替背景颜色.定制它们的接口通过 dedicated keys 的 sphinxsetup 配置设置实现.

重要

使用 'colorrows' 样式时, rowcolors LaTeX 命令将变为无操作（该命令有局限性,并且从未正确支持 Sphinx 在 LaTeX 中生成的所有类型的表格）.请更新您的项目以使用 latex table color configuration 键.

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

单行多列合并单元格将遵循行颜色(如果已设置).有关更多信息,请参见 sphinxsetup 配置设置部分中的 TableMergeColor{Header,Odd,Even} .

备注

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

提示

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

提示

在一个没有全局使用 'booktabs' 的文档中,可以通过 booktabs 类样式化单个表格,但需要在 LaTeX 前言中添加 r'\usepackage{booktabs}' .

另一方面,可以对单独的表使用 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 来准备通用术语的索引.这意味着具有 UTF-8 字符的单词将根据 language 正确排序.

如果 latex_engine 为 'platex' （日文文档;这时 mendex 会替代 makeindex ）,则此选项会被忽略.
默认情况下,对于:code-py:’xelatex’ 或:code-py:’lualatex’ ,值为:code-py:True ,因为:program:makeindex 生成的 .ind 文件中包含无效字节,如果任何索引术语以非ASCII字符开头.而使用:code-py:’lualatex’ 时,这会导致PDF构建失败.
默认情况下,:code-py:’pdflatex’ 为 False ,但对于非英语文档,建议在某些索引术语使用非 ASCII 字符时将其设为 True .

Sphinx 为 xindy 基础发行版添加了一些专用支持,以便使用 'pdflatex' 引擎处理西里尔文脚本.使用 'pdflatex' 和 Unicode 引擎时,西里尔文档能够正确处理带有变音符号的拉丁姓名索引.

Added in version 1.8.

latex_elements¶

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

Added in version 0.5.

请查看 latex_elements 的完整文档 .

latex_docclass¶

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

一个字典,将 'howto' 和 'manual' 映射到实际文档类的名称,这些文档类将作为两个 Sphinx 类的基础.默认情况下, 'howto' 使用 'article' , 'manual' 使用 'report' .

Added in version 1.0.

在 1.5 版本发生变更: 在日语文档中（language 为 'ja' ）,默认使用 'jreport' 作为 'howto' ,而使用 'jsbook' 作为 'manual' .

latex_additional_files¶

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

一个与 :term :配置目录相关的文件名列表,在构建 LaTeX 输出时复制到构建目录.这对于复制 Sphinx 不会自动复制的文件很有用,例如,如果它们在 latex_elements 中添加的自定义 LaTeX 中被引用.源文件中引用的图像文件（例如,通过 .. image:: ）会自动复制.

您必须自己确保文件名不会与任何自动复制的文件发生冲突.

注意

具有 .tex 扩展名的文件将自动交给通过 sphinx-build -M latexpdf 或 make latexpdf 触发的 PDF 构建过程.如果该文件只是为从修改后的前言中 input{} 添加的,则必须在文件名中添加其他后缀,如 .txt ,并相应地调整 input{} 宏.

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 ）.:confval:latex_appendices 仅对该主题可用.

Added in version 3.0.

latex_theme_options¶

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

影响所选主题外观和感觉的选项字典.这些选项是特定于主题的.

Added in version 3.1.

latex_theme_path¶

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

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

Added in version 3.0.

文本输出选项¶

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

text_add_secnumbers¶

类型:: bool
默认:: True

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

Added in version 1.7.

text_newlines¶

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

确定文本输出中使用的换行符.

'unix': 使用Unix样式的行结束符（ \n ）.
'窗口': 使用Windows样式的行结束符（ \r\n ）.
'native': 使用文档构建平台的行结束样式.

Added in version 1.1.

text_secnumber_suffix¶

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

文本输出中段落编号的后缀.设置为:code-py:’ ‘ 以抑制段落编号末尾的点.

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) ,其中项目为:

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

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输出选项¶

这些选项影响Texinfo输出.

texinfo_documents¶

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

该值决定如何将文档树分组为Texinfo源文件.它必须是一个元组列表 (startdocname, targetname, title, author, dir_entry, description, category, toctree_only) ,其中各项包含:

开始文档名称: 指定Texinfo文件主文档的:term:文档名称的字符串.所有由*startdoc*文档在ToC树中引用的文档将包含在Texinfo文件中.(如果您想在Texinfo构建中使用默认的主文档,请在此处提供您的:confval:master_doc .)
目标名称: 输出目录中Texinfo文件的文件名（不带扩展名）.
标题: Texinfo 文档标题.可以为空以使用 startdoc 文档的标题.作为 Texinfo 标记插入,因此像 @ 和 {} 这样的特殊字符需要转义才能字面插入.
作者: Texinfo 文档的作者.作为 Texinfo 标记插入.使用 @* 来分隔多个作者,例如: 'John@*Sarah' .
目录项: 将在顶级 DIR 菜单文件中显示的名称.
描述: 将在顶层 DIR 菜单文件中显示的描述性文本.
类别: 指定此条目将出现在顶级 DIR 菜单文件中的章节.
仅目录树: 必须是 True 或 False .如果为 True,则 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

如果为真,则生成特定于领域的索引,此外还有一般索引.例如,对于 Python 领域,这是全局模块索引.

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

示例:

texinfo_domain_indices = {
    'py-modindex',
}

Added in version 1.1.

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

texinfo_elements¶

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

一个字典,包含覆盖 Sphinx 通常放入生成的 .texi 文件中的 Texinfo 代码段.

您可能想要重写的键包括:

‘段落缩进’
每个段落首行缩进的空格数量,默认 2 .指定 0 表示不缩进.

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

‘preamble’
在文件开头附近插入的Texinfo标记.

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

Added in version 1.1.

texinfo_no_detailmenu¶

类型:: bool
默认:: False

在”Top”节点的菜单中,不要生成一个包含文档中每个子节点条目的 @detailmenu .

Added in version 1.2.

texinfo_show_urls¶

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

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

‘脚注’: 在脚注中显示网址.
'不': Do not display URLs.
'内联': 在括号中内联显示URLs.

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

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

XML输出选项¶

xml_pretty¶

类型:: bool
默认:: True

漂亮打印XML.

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.

linkcheck_anchors¶

类型:: bool
默认:: True

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

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*构建器不应检查其锚点有效性的URL.这允许在每个页面的基础上跳过锚点检查,同时仍然检查页面本身的有效性.

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]
默认:: ()

一个正则表达式的列表,这些表达式匹配在进行 linkcheck 构建时不应检查的 URI.

示例:

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

Added in version 1.1.

HTTP 请求¶

这些选项控制 linkcheck 构建器如何进行HTTP请求,包括如何处理重定向和认证,以及使用的工作线程数.

linkcheck_auth¶

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

在进行 linkcheck 构建时传递认证信息.

一个 (regex_pattern, auth_info) 元组的列表,其中项目为:

正则表达式模式: 匹配URI的正则表达式.
身份验证信息: 用于该URI的认证信息.该值可以是 requests 库所能理解的任何内容（详细信息请参见 requests authentication ）.

linkcheck 构建器将使用在 linkcheck_auth 列表中找到的第一个匹配的 auth_info 值,因此列表中靠前的值具有更高的优先级.

示例:

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

Added in version 2.3.

linkcheck_allow_unauthorized¶

类型:: bool
默认:: False

当一个web服务器以HTTP 401（未经授权）响应时,*linkcheck*生成器的当前默认行为是将该链接视为”损坏”.要更改该行为,请将此选项设置为:code-py:True .

在 8.0 版本发生变更: 此选项的默认值已更改为 False ,这意味着对检查过的超链接返回的 HTTP 401 响应默认被视为”损坏”.

Added in version 7.3.

linkcheck_rate_limit_timeout¶

类型:: int
默认:: 300

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

*linkcheck*构建器始终遵循服务器的重试指示（使用 Retry-After 头）.否则, linkcheck 会在重试之前等待一分钟,并在每次尝试之间将等待时间加倍,直到成功或超过:confval:!linkcheck_rate_limit_timeout （以秒为单位）.自定义超时应以秒数给出.

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 ,这意味着在检查超链接时发生的超时将使用新的 ‘timeout’ 状态代码进行报告.

Added in version 7.3.

linkcheck_request_headers¶

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

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

关键是一个URL基础字符串,如:'https://www.sphinx-doc.org/' .要为其他主机指定头部,可以使用:code-py:”*” .只有当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为损坏之前,将尝试检查该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 现在可以是一个元组.

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 现在可以是一个元组.

C++域的选项¶

cpp_id_attributes¶

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

一系列解析器应该额外接受的字符串作为属性.例如,当使用 #define 作为属性时,可以用于可移植性.

示例:

cpp_id_attributes = [
    'my_id_attribute',
]

Added in version 1.5.

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

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 在列表中,则:code-cpp:my_align_as(X) 被解析为所有具有平衡括号(() , [] , 和 {} )的字符串 X 的属性.例如,当:code-cpp:#define 被用于属性时,可以使用此功能,以便于移植.

示例:

cpp_paren_attributes = [
    'my_align_as',
]

Added in version 1.5.

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

Javascript 域的选项¶

javascript_maximum_signature_line_length¶

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

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

当 None 时,没有最大长度,整个签名将在一行逻辑上显示.

这是一个特定领域的设置,覆盖了 maximum_signature_line_length .

Added in version 7.1.

Python 域的选项¶

add_module_names¶

类型:: bool
默认:: True

一个布尔值,用于决定是否将模块名称前置于所有对象名称之前（对于定义了某种 “模块” 的对象类型）,例如 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 时,:py:data:~typing.Literal 类型显示为标准 Python 语法,即:

serve_food(item: Literal["egg", "spam", "lobster thermidor"]) -> None

当 True 时,:py:data:~typing.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_use_unqualified_type_names¶

类型:: bool
默认:: False

如果可以解析,则抑制 Python 参考的模块名称.

Added in version 4.0.

小心

这个功能是实验性的.

trim_doctest_flags¶

类型:: bool
默认:: True

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

Added in version 1.0.

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

扩展选项¶

扩展通常有自己的配置选项.Sphinx 的官方扩展的选项在每个扩展页面中有说明.

示例配置文件¶

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

配置¶

项目标签¶

项目说明¶

一般配置¶

图像编号选项¶

高亮显示的选项¶

HTTP请求的选项¶

国际化选项¶

选项对于标记¶

选项 适用于数学¶

nitpicky模式的选项¶

对象签名选项¶

源文件的选项¶

智能引号选项¶

模板选项¶

警告控制选项¶

构建器选项¶

HTML输出选项¶

单一HTML输出的选项¶

HTML帮助输出选项¶

Apple Help 输出选项¶

EPUB输出选项¶

LaTeX输出选项¶

文本输出选项¶

手册页输出选项¶

Texinfo输出选项¶

QtHelp输出选项¶

XML输出选项¶

链接检查构建器的选项¶

过滤¶

HTTP 请求¶

域选项¶

C域的选项¶

C++域的选项¶

Javascript 域的选项¶

Python 域的选项¶

示例¶

扩展选项¶

示例配置文件¶

选项适用于数学¶