配置¶

术语“配置目录”必须包含一个名为conf.py的文件。该文件(包含Python代码)称为“构建配置文件”，并包含定制Sphinx输入和输出行为所需的(几乎)所有配置。

如果没有被Sphinx覆盖或设置, 可以在配置目录中添加一个可选文件件docutils.conf 来调整 Docutils 配置。

The configuration file is executed as Python code at build time (using importlib.import_module(), and with the current directory set to its containing directory), and therefore can execute arbitrarily complex code. Sphinx then reads simple names from the file’s namespace as its configuration.

重点注意：

如果没有另外记录, 则值必须是字符串, 并且它们的默认值为空字符串。
术语“全限定名”指的是一个字符串，该字符串对模块内的可导入Python对象进行命名：例如，FQN“sphinx.builders.Builder”表示构建器中的“sphinx.builders”模块。
请记住, 文档名称使用“/”作为路径分隔符, 并且不包含文件扩展名。
因为 conf.py 作为Python文件读取，通常的规则适用于编码和Unicode支持。
配置名称空间的内容被pickle(以便Sphinx能够在配置更改时发现)，因此它可能不包含不可pickle的值——如果合适的话，使用“del”从名称空间中删除它们。模块会自动删除，所以您不需要在使用后“del”您的导入。
配置文件中有一个名为“tags”的特殊对象。它可用于查询和更改标记(请参阅引用基于标签的内容)。使用 “tags.has(‘tag’)”来查询，“tags.add(‘tag’)” 和“tags.remove(‘tag’)”来改变。只有通过 -t 命令行选项或“tags.add(‘tag’)”设置的标签可以使用 “tags.has(‘tag’)”进行查询。请注意, 当前生成器标记在 “conf.py”中不可用, 因为它是在初始化生成器之后创建的。

项目信息¶

project¶: 记录的项目名称。

author¶: 该文件的作者姓名。默认值为“unknown”。

copyright¶: “2008，Author Name”风格的版权声明。

在 7.1 版本发生变更: The value may now be a sequence of copyright statements in the above form, which will be displayed each to their own line.

project_copyright¶: An alias of copyright.

Added in version 3.5.

version¶: 主要项目版本，用作“7.4.0+/ccdd47d”的替代品。例如，对于Python文档，这可能类似于“2.6”。

release¶

主要项目版本，用作“7.4.0+/ccdd47d”的替代品。例如，对于Python文档，这可能类似于“2.6.0rc1”。

如果您不需要在 version 和 :confval:`release`之间提供分隔，只需将它们设置为相同的值即可。

一般配置¶

extensions¶

模块名称为:doc:extensions <extensions/index>`的字符串列表。这些可以是Sphinx附带的扩展(名为 ``sphinx.ext.*`)，也可以是自定义的扩展。

请注意，如果扩展名位于另一个目录中, 则可以在conf文件中扩展 sys.path ，但请确保使用绝对路径。如果您的扩展路径是相对于:term:配置目录 , 请这样使用 os.path.abspath() ：

import sys, os

sys.path.append(os.path.abspath('sphinxext'))

extensions = ['extname']

这样, 你可以从子目录“sphinxext”加载一个名为“extname”的扩展名。

配置文件本身可以是扩展名：你只需要提供一个:func:`setup`函数。

source_suffix¶

源文件的文件扩展名。Sphinx将具有此后缀的文件视为源。该值可以是将文件扩展名映射到文件类型的字典。例如：

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

默认情况下, Sphinx仅支持“restructuredtext”文件类型。您可以使用源解析器扩展添加新文件类型。请阅读扩展文档以了解扩展程序支持的文件类型。

这个值也可以是文件扩展名的列表:然后Sphinx会认为它们都映射到“’restructuredtext’”文件类型。

默认是“{‘.rst’: ‘restructuredtext’}”。

备注

文件扩展名必须以点开头 (如“.rst”)。

在 1.3 版本发生变更: 文件扩展名必须以点开头 (如“.rst”)。

在 1.8 版本发生变更: 支持文件类型映射

source_encoding¶: 所有reST源文件的编码。推荐的编码和默认值是 “‘utf-8-sig’” 。

Added in version 0.5: 如果给出, 则不同源的解析器类字典就足够了。键是后缀, 值可以是类或字符串, 给出解析器类的完全限定名称。解析器类可以是 “docutils.parsers.Parser”或:class:sphinx.parsers.Parser。具有不在字典中的后缀的文件将使用默认的 reStructuredText 解析器进行解析。

source_parsers¶

如果给出, 则不同源的解析器类字典就足够了。键是后缀, 值可以是类或字符串, 给出解析器类的完全限定名称。解析器类可以是 “docutils.parsers.Parser”或:class:sphinx.parsers.Parser。具有不在字典中的后缀的文件将使用默认的 reStructuredText 解析器进行解析。

例如：

source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}

备注

请参考:doc:`/usage/markdown`以获得关于在Sphinx中使用markdown的更多信息。

Added in version 1.3.

自 1.8 版本弃用: 现在, Sphinx 提供了一个API :meth:`Sphinx.add_source_parser`来注册一个源解析器。请改用它。

master_doc¶: Same as root_doc.

在 4.0 版本发生变更: Renamed master_doc to root_doc.

root_doc¶: The document name of the “root” document, that is, the document that contains the root toctree directive. Default is 'index'.

在 2.0 版本发生变更: 默认值从“’索引’”更改为“’内容’”。

在 4.0 版本发生变更: Renamed root_doc from master_doc.

exclude_patterns¶

A list of glob-style patterns [1] that should be excluded when looking for source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms.

示例模式：

'library/xml.rst' – ignores the library/xml.rst file
“‘library/xml’” – 忽略“library/xml”目录
“‘library/xml*’” – 忽略以“library/xml”开头的所有文件和目录
“‘**/.svn’”–忽略所有“.svn”目录

在:confval:html_static_path 和 html_extra_path`中查找静态文件时也会查询 :confval:`exclude_patterns 。

Added in version 1.0.

include_patterns¶

A list of glob-style patterns [1] that are used to find source files. They are matched against the source file names relative to the source directory, using slashes as directory separators on all platforms. The default is **, meaning that all files are recursively included from the source directory. exclude_patterns has priority over include_patterns.

示例模式：

'**' – all files in the source directory and subdirectories, recursively
'library/xml' – just the library/xml directory
'library/xml*' – all files and directories starting with library/xml
'**/doc' – all doc directories (this might be useful if documentation is co-located with source files)

Added in version 5.1.

templates_path¶: 包含额外模板的路径列表(覆盖内置/主题特定模板的模板)。相对路径被视为相对于配置目录。

在 1.3 版本发生变更: 由于这些文件不是要构建的, 因此它们会自动添加到:confval:`exclude_patterns`中。

template_bridge¶: 一个字符串，其中包含一个可调用的(或简称为类)的完全限定名，它返回一个实例 TemplateBridge。然后，此实例用于呈现 HTML 文档，可能还有其他构建器的输出(当前是更改构建器)。 (请注意，如果要使用 HTML 主题，则必须使模板桥可以识别主题。)

rst_epilog¶

一串 reStructuredText，它将包含在每个读取的源文件的末尾。这是一个可以添加应该在每个文件中可用的替换的地方(另一个是:confval:rst_prolog)。例如：

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

Added in version 0.6.

rst_prolog¶

一串 reStructuredText，它将包含在每个读取的源文件的末尾。这是一个可以添加应该在每个文件中可用的替换的地方(另一个是:confval:rst_prolog)。例如：

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

Added in version 1.0.

primary_domain¶: The name of the default domain. Can also be None to disable a default domain. The default is 'py'. Those objects in other domains (whether the domain name is given explicitly, or selected by a default-domain directive) will have the domain name explicitly prepended when named (e.g., when the default domain is C, Python functions will be named “Python function”, not just “function”).

Added in version 1.0.

default_role¶

用作默认角色的 reST 角色(内置或 Sphinx 扩展)的名称，即标记为“‘这样’”的文本，可以设置为“‘py:obj’”，使“‘filter’”`成为 Python 函数“filter”的交叉引用。默认值是“None”，它不会重新分配默认角色。

The default role can always be set within individual documents using the standard reST default-role directive.

Added in version 0.4.

keep_warnings¶

如果正确，在构建的文档中将警告保持为 “系统信息”段落。无论此设置如何，在运行“sphinx-build”时，都会将警告写入标准错误流。

默认为“False”，0.5之前的行为是始终保持它们。

Added in version 0.5.

show_warning_types¶: If True, the type of each warning is added as a suffix to the warning message, e.g., WARNING: [...] [index] or WARNING: [...] [toc.circular]. The default is False.

Added in version 7.3.0.

suppress_warnings¶

用于禁止任意警告消息的警告类型列表。

Sphinx core supports following warning types:

app.add_node
app.add_directive
app.add_role
app.add_generic_role
app.add_source_parser
config.cache
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.highlighting_failure
toc.circular
toc.excluded
toc.not_readable
toc.secnum

Extensions can also define their own warning types. Those defined by the first-party sphinx.ext extensions are:

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

You can choose from these types. You can also give only the first component to exclude all warnings attached to it.

Added in version 1.4.

在 1.5 版本发生变更: 添加“misc.highlighting_failure”

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

在 1.6 版本发生变更: 添加“ref.footnote”

在 2.1 版本发生变更: Added autosectionlabel.<document name>

在 3.3.0 版本发生变更: Added epub.duplicated_toc_entry

在 4.3 版本发生变更: Added toc.excluded and toc.not_readable

Added in version 4.5: Added i18n.inconsistent_references

Added in version 7.1: Added index warning type.

Added in version 7.3: Added config.cache warning type.

needs_sphinx¶: 如果设置为“major.minor”版本字符串，如“‘1.1’”，Sphinx 会将其与版本进行比较, 如果它太旧则拒绝构建。

Added in version 1.0.

在 1.4 版本发生变更: 也接受微版本字符串

needs_extensions¶

该值可以是指定扩展名的版本要求的字典:confval:extensions，例如： “needs_extensions = {‘sphinxcontrib.something’: ‘1.5’}”。版本字符串应采用 ``major.minor``形式。不必为所有扩展指定要求, 仅适用于您要检查的扩展。

这要求扩展指定其版本给Sphinx（参见:ref:开发扩展 , 了解如何做到这一点）。

Added in version 1.3.

manpages_url¶

A URL to cross-reference manpage roles. If this is defined to https://manpages.debian.org/{path}, the :manpage:`man(1)` role will link to <https://manpages.debian.org/man(1)>. The patterns available are:

“page”- 手册页 (“man”)
“section” - 手册部分 (“1”)
“path”- 原始的手册页和指定的部分(“man(1)”)

这也支持指定为“man.1”的联机帮助页。

备注

这目前只影响 HTML 编写者，但将来可以扩展。

Added in version 1.7.

nitpicky¶: 如果为 true，Sphinx 将警告无法找到目标的 all 引用。默认为“False”。您可以使用：选项临时激活此模式 :-n <sphinx-build -n> 命令行开关。

Added in version 1.0.

nitpick_ignore¶: A set or list of (type, target) tuples (by default empty) that should be ignored when generating warnings in “nitpicky mode”. Note that type should include the domain name if present. Example entries would be ('py:func', 'int') or ('envvar', 'LD_LIBRARY_PATH').

Added in version 1.1.

在 6.2 版本发生变更: Changed allowable container types to a set, list, or tuple

nitpick_ignore_regex¶

An extended version of nitpick_ignore, which instead interprets the type and target strings as regular expressions. Note, that the regular expression must match the whole string (as if the ^ and $ markers were inserted).

For example, (r'py:.*', r'foo.*bar\.B.*') will ignore nitpicky warnings for all python entities that start with 'foo' and have 'bar.B' in them, such as ('py:const', 'foo_package.bar.BAZ_VALUE') or ('py:class', 'food.bar.Barman').

Added in version 4.1.

在 6.2 版本发生变更: Changed allowable container types to a set, list, or tuple

numfig¶: 如果为true, 则数字，表格和代码块如果有标题则会自动编号。numref 角色已启用。到目前为止，只有 HTML 和 LaTeX 构建者才能使用Obeyed。默认为“False”。

备注

无论是否启用此选项, LaTeX构建器始终会分配数字。

Added in version 1.3.

numfig_format¶

一个字典将“‘figure’”，“‘table’”，“‘code-block’”和“‘section’”映射到用于图号格式的字符串。作为一个特殊字符，“%s”将被替换为图号。

Default is to use 'Fig. %s' for 'figure', 'Table %s' for 'table', 'Listing %s' for 'code-block' and 'Section %s' for 'section'.

Added in version 1.3.

numfig_secnum_depth¶

如果设置为“0”，则数字，表格和代码块从“1”开始连续编号。
如果“1”(默认)数字将是“x.1”。“x.2”，… 与“x”的节号(顶级切片;没有“x”如果没有部分)。只有当通过 toctree 指令的“:numbered:”选项激活了段号时，这才自然适用。
“2”表示数字将是“x.y.1”，“x.y.2”，…如果位于子区域(但仍然是 x.1 ，x.2 ，… 如果直接位于一个部分和 1 ，2 ， … 如果不在任何顶级部分。)
等等…

Added in version 1.3.

在 1.7 版本发生变更: LaTeX构建器遵循此设置(如果 :confval:`numfig`设置为 “True”)。

smartquotes¶

如果是真的, 最初基于‘SmartyPants’__ (仅限英语)并且目前适用于多种语言的‘Docutils Smart Quotes transform’__将用于将引号和短划线转换为印刷正确的实体。默认值：“True”。

Added in version 1.6.6: 它取代了:confval:html_use_smartypants。它默认适用于除“man”和“text”之外的所有构建器(参见 smartquotes_excludes。)

如果通过相应的`Docutils option`__*停止* 智能引号, 则无条件地遵守位于配置目录(或全局 ~/.docutils 文件)中的 `docutils.conf`__文件。但如果它激活它们，那么 :confval:`smartquotes`确实占上风。

smartquotes_action¶: 此字符串自定义智能引号转换。有关详细信息，请参阅 `Docutils repository`__中的smartquote .py文件。默认的“‘qDe’”输出正常的引号“”，’，em-和破折号—，–和省略号…

Added in version 1.6.6.

smartquotes_excludes¶

这是一个“dict”，其默认值为：

{'languages': ['ja'], 'builders': ['man', 'text']}

每个条目都给出了一个足够的条件来忽略:confval:smartquotes 设置并停用Smart Quotes变换。接受的键如上所述 “builders”或“languages”。值是列表。

备注

目前，在使用多个目标调用:program:make`时，第一个目标名称是惟一针对“构建器”条目进行测试的目标名称，它将决定所有目标。另外，”make html”后面的”make text”需要以”make text O=”-E””的形式发布，以强制重新解析源文件，因为缓存的文件已经进行了转换。另一方面，直接使用:program:`sphinx-build 不会出现这个问题，因为它会在每个构建器位置缓存(在默认情况下)已解析的源文件。

提示

另一种有效地禁用（或定制）给定生成器的智能报价的方法，例如“latex”，是使用“make”:

make latex O="-D smartquotes_action="

This can follow some make html with no problem, in contrast to the situation from the prior note.

Added in version 1.6.6.

user_agent¶: Sphinx的用户代理。它用于HTTP访问的报头(例如linkcheck、intersphinx等)。默认是“”Sphinx/ X.Y.Z请求/ X.Y.python / X.Y.Z””。

Added in version 2.3.

tls_verify¶: 如果为“true”，Sphinx将验证服务器认证。

Added in version 1.5.

tls_cacerts¶: CA的证书文件的路径或包含证书的目录的路径。这也允许字典映射主机名到证书文件的路径。证书用于验证服务器认证。

Added in version 1.5.

小技巧

Sphinx在内部使用requests_作为HTTP库。因此，如果没有设置“tls_cacerts”， Sphinx引用指向“REQUESTS_CA_BUNDLE”环境变量的目录上的认证文件。

today¶

today_fmt¶

这些值决定了如何格式化当前日期，用作“2024 年 05 月 09 日”的替换。

如果将 today 设置为非空值，则使用它。
否则，使用:func:time.strftime`格式化当前时间，格式为 :confval:`today_fmt。

The default is now today and a today_fmt of '%b %d, %Y' (or, if translation is enabled with language, an equivalent format for the selected locale).

highlight_language¶

The default language to highlight source code in. The default is 'default'. It is similar to 'python3'; it is mostly a superset of 'python' but it fallbacks to 'none' without warning if failed. 'python3' and other languages will emit warning if failed.

The value should be a valid Pygments lexer name, see 显示代码示例 for more details.

Added in version 0.5.

在 1.4 版本发生变更: The default is now 'default'. If you prefer Python 2 only highlighting, you can set it back to 'python'.

highlight_options¶

A dictionary that maps language names to options for the lexer modules of Pygments. These are lexer-specific; for the options understood by each, see the Pygments documentation.

例如：

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

A single dictionary of options are also allowed. Then it is recognized as options to the lexer specified by highlight_language:

# configuration for the ``highlight_language``
highlight_options = {'stripall': True}

Added in version 1.3.

在 3.5 版本发生变更: Allow to configure highlight options for multiple languages

pygments_style¶: 用于 Pygments 突出显示源代码的样式名称。如果未设置，则为HTML输出选择主题的默认样式或“‘sphinx’”。

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

maximum_signature_line_length¶

If a signature’s length in characters exceeds the number set, each parameter within the signature will be displayed on an individual logical line.

When None (the default), there is no maximum length and the entire signature will be displayed on a single logical line.

A ‘logical line’ is similar to a hard line break—builders or themes may choose to ‘soft wrap’ a single logical line, and this setting does not affect that behaviour.

Domains may provide options to suppress any hard wrapping on an individual object directive, such as seen in the C, C++, and Python domains (e.g. py:function:single-line-parameter-list).

Added in version 7.1.

add_function_parentheses¶: 一个布尔值, 决定是否将括号附加到函数和方法角色文本(例如：func:input 的内容)以表示该名称是可调用的。默认为“True”。

add_module_names¶: 一个布尔值，用来决定是否将模块名前置到所有:term:对象名(对于定义了某种“模块”的对象类型)，例如:rst:dir:`py:function`指令。默认是“Ture”。

toc_object_entries¶: Create table of contents entries for domain objects (e.g. functions, classes, attributes, etc.). Default is True.

toc_object_entries_show_parents¶

A string that determines how domain objects (e.g. functions, classes, attributes, etc.) are displayed in their table of contents entry.

Use domain to allow the domain to determine the appropriate number of parents to show. For example, the Python domain would show Class.method() and function(), leaving out the module. level of parents. This is the default setting.

Use hide to only show the name of the element without any parents (i.e. method()).

Use all to show the fully-qualified name for the object (i.e. module.Class.method()), displaying all parents.

Added in version 5.2.

show_authors¶: 一个布尔值，决定:rst:dir:`codeauthor`和 :rst:dir:`sectionauthor`指令在构建的文件中产生任何输出。

modindex_common_prefix¶: 为了对 Python 模块索引进行排序而忽略的前缀列表(例如，如果将其设置为“[‘foo.’]”, 那么“foo.bar”将显示在“B”下，而不是“F”)。如果您记录包含单个包的项目，这可能很方便。仅适用于当前的HTML构建器。默认是 “[]”。

Added in version 0.6.

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

Added in version 0.6.

trim_doctest_flags¶: 如果为true，则删除doctest标志(在行的末尾看起来像 “# doctest: FLAG, …”的注释)和“<BLANKLINE>”标记，以显示交互式Python会话的所有代码块(即doctests) 。默认为“True”。有关包含 doctests 的更多可能性，请参阅扩展名:mod:~sphinx.ext.doctest。

Added in version 1.0.

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

strip_signature_backslash¶: 默认是“False”。当启用反斜杠剥离时，在域指令中出现的“\”将被更改为“ ”，即使在字符串文本中也是如此。这是3.0版本之前的行为，将这个变量设置为“True”将恢复该行为。

Added in version 3.0.

option_emphasise_placeholders¶: Default is False. When enabled, emphasise placeholders in option directives. To display literal braces, escape with a backslash (\{). For example, option_emphasise_placeholders=True and .. option:: -foption={TYPE} would render with TYPE emphasised.

Added in version 5.1.

国际化选项¶

这些选项会影响Sphinx的*母语支持*。有关详细信息，请参阅以下文档国际化。

language¶

The code for the language the docs are written in. Any text automatically generated by Sphinx will be in that language. Also, Sphinx will try to substitute individual paragraphs from your documents with the translation sets obtained from locale_dirs. Sphinx will search language-specific figures named by figure_language_filename (e.g. the German version of myfigure.png will be myfigure.de.png by default setting) and substitute them for original figures. In the LaTeX builder, a suitable language will be selected as an option for the Babel package. Default is 'en'.

Added in version 0.5.

在 1.4 版本发生变更: 支持数字替换

在 5.0 版本发生变更.

目前Sphinx支持的语言是：

“ar”– 阿拉伯语
“bg”– 保加利亚语
“bn” – 孟加拉语
“ca” – 加泰罗尼亚语
“cak”– 喀克其奎语
“cs” – 捷克语
“cy”– 威尔士语
“da” – 丹麦语
“de” – 德语
“el”– 希腊语
en – English (default)
“eo”– 世界语
“es” – 西班牙语
“et” – 爱沙尼亚语
“eu” – 巴斯克语
“fa” – 伊朗语
“fi” – 芬兰语
“fr” – 法语
“he” – 希伯来语
“hi”– 北印度语
“hi_IN”– 北印度语（印度）
“hr” – 克罗地亚语
“hu” – 匈牙利语
“id” – 印度尼西亚语
“id” – 印度尼西亚语
“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¶

Added in version 0.5.

相对于源目录, 在其中搜索其他消息目录(请参阅:confval:language)的目录。此路径上的目录由标准:mod:gettext 模块搜索。

内部消息是从“sphinx”的文本域中获取的；因此, 如果将目录。./locale`添加到此设置, 则消息目录(使用 :program:`msgfmt`编译为“.po”格式)必须位于:file:./locale/{language}/LC_MESSAGES/sphinx.mo`。单个文档的文本域取决于:confval:gettext_compact。

默认是“[‘locales’]”。

备注

The -v option for sphinx-build command is useful to check the locale_dirs config works as expected. It emits debug messages if message catalog directory not found.

在 1.5 版本发生变更: 使用“locales”目录作为默认值。

gettext_allow_fuzzy_translations¶: If true, “fuzzy” messages in the message catalogs are used for translation. The default is False.

Added in version 4.3.

gettext_compact¶

Added in version 1.1.

如果为true，则文档的文本域是其 docname，如果它是顶级项目文件，则为其基本目录。

如果设置为字符串，所有文档的文本域都是这个字符串，使得所有文档都使用单个文本域。

默认情况下，文档“标记/代码.rst”最终出现在 “标记”文本域中。将此选项设置为“False”，它是“标记/代码”。

在 3.3 版本发生变更: 字符串值现在被接受。

gettext_uuid¶

如果为true，则 Sphinx 会在消息目录中生成用于版本跟踪的 uuid 信息。用于：

在.pot文件中为每个 msgids 添加 uid 行。
计算新 msgids 和以前保存的旧 msgids 之间的相似性。这种计算需要很长时间。

如果您想加速计算, 你可以使用 :command:`pip install python-levenshtein`来使用C编写的“python-levenshtein”第三方包。

默认为“False”。

Added in version 1.3.

gettext_location¶

如果为true，则Sphinx为消息目录中的消息生成位置信息。默认是 True。

默认值为真。

Added in version 1.3.

gettext_auto_build¶

如果为true，则Sphinx为每个翻译目录文件构建mo文件。

默认值为真。

Added in version 1.3.

gettext_additional_targets¶

指定名称以启用gettext提取和转换另外申请i18n。您可以指定以下名称：

索引:: 索引条款
文字块:: 文字块（“::”注释和“代码块”指令）。
doctest块:: doctest块
原始:: 原始内容
图片:: 图像/图的uri

例如：“gettext_additional_targets = [‘literal-block’, ‘image’]”。

默认是“[]”。

Added in version 1.3.

在 4.0 版本发生变更: 默认情况下，图像的alt文本被翻译。

figure_language_filename¶

语言特定数字的文件名格式。默认值为“{root}.{language}{ext}”。它将从“.. image:: dirname/filename.png”扩展为“dirname/filename.en.png”。可用的格式标记是：

“{root}”- 文件名，包括任何路径组件，没有文件扩展名，例如“dirname/filename”
“{path}”- 文件名的目录路径组件，如果非空，则带有斜杠，例如“dirname/”
“{docpath}” - 当前文档的目录路径组件，如果非空，尾部有一个斜杠。
“{basename}”- 没有目录路径或文件扩展名组件的文件名，例如“filename”
“{ext}”- 文件扩展名，例如 .png
“{language}”- 翻译语言，例如“en”。

例如, 将其设置为“{path}{language}/{basename}{ext}”将扩展为“dirname/en/filename.png”。

Added in version 1.4.

在 1.5 版本发生变更: 添加了“{path}”和“{basename}”标记。

在 3.2 版本发生变更: 添加“{docpath}”标记。

translation_progress_classes¶

Control which, if any, classes are added to indicate translation progress. This setting would likely only be used by translators of documentation, in order to quickly indicate translated and untranslated content.

True: add translated and untranslated classes to all nodes with translatable content.
translated: only add the translated class.
untranslated: only add the untranslated class.
False: do not add any classes to indicate translation progress.

默认为“False”。

Added in version 7.1.

数学选项¶

这些选项会影响数学符号。

math_number_all¶: 如果要对所有显示的数学进行编号，请将此选项设置为“True”。默认值为“False”。

math_eqref_format¶

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

例: “’Eq.{number}’ ”被渲染为, 例如，”Eq.10”。

math_numfig¶: 如果为“True”，则当启用：confval:numfig`时，显示的数学公式将跨页编号。遵循：confval:`numfig_secnum_depth`设置。这个：rst:角色：`eq，不是：rst:角色：numref，role必须用于引用公式编号。默认值为“True”。

Added in version 1.7.

HTML输出选项¶

这些选项会影响 HTML 以及 HTML 帮助输出, 以及使用 Sphinx 的 HTMLWriter 类的其他构建器。

html_theme¶: HTML输出应该使用的“主题”。见 doc:“主题</usage/theming>”。默认值是“‘alabaster’”。

Added in version 0.6.

html_theme_options¶: 影响所选主题外观的选项字典。这些是针对主题的。有关内置主题所理解的选项, 请参阅 :ref:`this section<builtin-themes> `。

Added in version 0.6.

html_theme_path¶: 包含自定义主题的路径列表，可以是子目录，也可以是zip文件。相对路径被视为相对于配置目录。

Added in version 0.6.

html_style¶: 用于HTML页面的样式表。该名称的文件必须存在于Sphinx的:file:static/ 路径中, 或者存在于:confval:`html_static_path`中给出的自定义路径之一。默认值是所选主题给出的样式表。如果您只想添加或覆盖与主题样式表相比的一些内容，请使用CSS“@import”导入主题的样式表。

html_title¶: 用Sphinx自己的模板生成的HTML文档的“标题”。它被附加到各个页面的标签“<title>”中，并在导航栏中作为最顶部的元素使用。它默认为:samp:’{<project>} v{<revision>} documentation’。

html_short_title¶: HTML文档的更短“标题”。它用于页眉和HTML帮助文档中的链接。如果未给出，则默认为:confval:`html_title`的值。

Added in version 0.4.

html_baseurl¶: The base URL which points to the root of the HTML documentation. It is used to indicate the location of document using The Canonical Link Relation. Default: ''.

Added in version 1.8.

html_codeblock_linenos_style¶

代码块的行号样式。

'table' – display line numbers using <table> tag
'inline' – display line numbers using <span> tag (default)

Added in version 3.2.

在 4.0 版本发生变更: It defaults to 'inline'.

自 4.0 版本弃用.

html_context¶: 要传递到所有页面的模板引擎上下文的值字典。单个值也可以使用 :option:`-A<sphinx-build -A> `的命令行选项放入这个字典中。

Added in version 0.5.

html_logo¶: If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the docs, or URL that points an image file for the logo. It is placed at the top of the sidebar; its width should therefore not exceed 200 pixels. Default: None.

Added in version 0.4.1: 图像文件将被复制到输出HTML的“_static”目录中，但前提是该文件尚不存在。

在 4.0 版本发生变更: Also accepts the URL for the logo file.

html_favicon¶: If given, this must be the name of an image file (path relative to the configuration directory) that is the favicon of the docs, or URL that points an image file for the favicon. Modern browsers use this as the icon for tabs, windows and bookmarks. It should be a Windows-style icon file (.ico), which is 16x16 or 32x32 pixels large. Default: None.

Added in version 0.4: 图像文件将被复制到输出HTML的“_static”目录中，但前提是该文件尚不存在。

在 4.0 版本发生变更: Also accepts the URL for the favicon.

html_css_files¶

A list of CSS files. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like https://example.org/style.css. The attributes is used for attributes of <link> tag. It defaults to an empty list.

例如：

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

As a special attribute, priority can be set as an integer to load the CSS file at an earlier or lazier step. For more information, refer Sphinx.add_css_file().

Added in version 1.8.

在 3.5 版本发生变更: Support priority attribute

html_js_files¶

A list of JavaScript filename. The entry must be a filename string or a tuple containing the filename string and the attributes dictionary. The filename must be relative to the html_static_path, or a full URI with scheme like https://example.org/script.js. The attributes is used for attributes of <script> tag. It defaults to an empty list.

例如：

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

As a special attribute, priority can be set as an integer to load the JavaScript file at an earlier or lazier step. For more information, refer Sphinx.add_js_file().

Added in version 1.8.

在 3.5 版本发生变更: Support priority attribute

html_static_path¶

包含自定义静态文件(例如样式表或脚本文件)的路径列表。相对路径被视为相对于配置目录。它们被复制到主题的静态文件之后的输出的:file:_static 目录中，因此名为 default.css 的文件将覆盖主题的:file:default.css. Default.css。

由于这些文件不打算被构建，它们将自动从源文件中被排除。

备注

出于安全原因，”tml_static_path下的dotfiles将不会被复制。如果您有意复制它们，请将每个filepath添加到此设置:

html_static_path = ['_static', '_static/.htaccess']

另一种方法，你也可以使用 html_extra_path 。它允许在目录下复制dotfiles。

在 0.4 版本发生变更: 以下路径 html_static_path 现在可以包含子目录。

在 1.0 版本发生变更: 以下条目 html_static_path 现在可以单目录。

在 1.8 版本发生变更: 从源文件中排除：confval:`html_static_path`下的文件。

html_extra_path¶

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

由于这些文件不打算被构建，它们将自动从源文件中被排除。

Added in version 1.2.

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

html_last_updated_fmt¶: If this is not None, a ‘Last updated on:’ timestamp is inserted at every page bottom, using the given strftime() format. The empty string is equivalent to '%b %d, %Y' (or a locale-dependent equivalent).

html_use_smartypants¶: 如果为true, 则引号和短划线将转换为印刷正确的实体。默认值：“True”。

自 1.6 版本弃用: 要禁用智能引号, 请使用:confval:smartquotes。

html_permalinks¶: Add link anchors for each heading and description environment. Default: True.

Added in version 3.5.

html_permalinks_icon¶: Text for link anchors for each heading and description environment. HTML entities and Unicode are allowed. Default: a paragraph sign; ¶

Added in version 3.5.

html_sidebars¶

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

键可以包含glob样式的模式 [1], 在这种情况下, 所有匹配的文档都将获得指定的侧边栏。 (当多个glob样式模式与任何文档匹配时会发出警告。)

值可以是列表或单个字符串。

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

默认侧边栏(适用于与任何模式不匹配的文档)由主题本身定义。内置主题默认使用这些模板：“[‘localtoc.html’, ‘relations.html’, ‘sourcelink.html’, ‘searchbox.html’]。
如果值是单个字符串, 则它指定要在“‘sourcelink.html’”和“‘searchbox.html’”条目之间添加的自定义侧边栏。这是为了与1.0之前的 Sphinx 版本兼容。

自 1.7 版本弃用: “html_侧边栏”的单个字符串值将在2.0中被删除

可呈现的内置侧边栏模板是：

localtoc.html –当前文档的细粒度目录
globaltoc.html– 折叠整个文档集的粗粒度目录
relations.html– 两个指向上一个和下一个文档的链接
sourcelink.html– 指向当前文档源的链接, 如果在 :confval:`html_show_sourcelink`中启用
searchbox.html – “快速搜索框”

例如：

html_sidebars = {
   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
   'using/windows': ['windowssidebar.html', 'searchbox.html'],
}

这将呈现自定义模板“windowssidebar.html”和给定文档侧边栏内的快速搜索框, 并呈现所有其他页面的默认侧边栏(除了本地TOC被全局TOC替换)。

Added in version 1.0: 能够使用通配键并指定多个侧边栏。

请注意, 如果所选主题不具有侧边栏, 则此值仅无效, 例如内置**scrolls**和**haiku**。

html_additional_pages¶

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

例如：

html_additional_pages = {
    'download': 'customdownload.html',
}

这将把模板 customdownload.html 渲染为页面“download.html”。

html_domain_indices¶

如果为true, 则除了常规索引外, 还会生成特定于域的索引。对于例如Python域, 这是全局模块索引。默认为 “True”。

此值可以是bool或应生成的索引名称列表。要查找特定索引的索引名称, 请查看HTML文件名。例如, Python 模块索引的名称为“‘py-modindex’”。

Added in version 1.0.

html_use_index¶: 如果为 true, 则为HTML文档添加索引。默认为“True”。

Added in version 0.4.

html_split_index¶: 如果为 true, 则索引生成两次:一次作为包含所有条目的单个页面, 一次作为每个起始字母的一个页面。默认为 False 。

Added in version 0.4.

html_copy_source¶: 如果为true, 则rest源包含在HTML构建中:file:_sources/{name}。默认为“True”。

html_show_sourcelink¶: 如果为true(并且:confval:`html_copy_source`也为 true ), 则指向reST源的链接将添加到侧栏。默认为 “True”。

Added in version 0.6.

html_sourcelink_suffix¶: 附加到源链接的后缀(参见:confval:html_show_sourcelink), 除非它们已经有这个后缀。默认是“‘.txt’”。

Added in version 1.5.

html_use_opensearch¶: If nonempty, an OpenSearch description file will be output, and all pages will contain a <link> tag referring to it. Since OpenSearch doesn’t support relative URLs for its search page location, the value of this option must be the base URL from which these documents are served (without trailing slash), e.g. "https://docs.python.org". The default is ''.

html_file_suffix¶: This is the file name suffix for generated HTML files, if set to a str value. If left to the default None, the suffix will be ".html".

Added in version 0.4.

html_link_suffix¶: 生成HTML文件链接的后缀。默认值为:confval:html_file_suffix 设置为;它可以设置不同(例如, 支持不同的Web服务器设置)。

Added in version 0.6.

html_show_copyright¶: 如果为true， "(C)版权…" 显示在HTML页脚。默认是 “True”。

Added in version 1.0.

html_show_search_summary¶: If true, the text around the keyword is shown as summary of each search result. Default is True.

Added in version 4.5.

html_show_sphinx¶: 如果为true,"使用Sphinx创建"显示在HTML页脚中。默认是“True”。

Added in version 0.4.

html_output_encoding¶: HTML输出文件的编码。默认为“’utf-8’”。请注意, 此编码名称必须都是有效的Python编码名称和有效的HTML “charset”值。

Added in version 1.0.

html_compact_lists¶: 如果为true, 则列表中包含单个段落和/或子列表的所有项目等等…(递归定义)将不会对其任何项目使用“<p>”元素。这是标准的docutils行为。默认值：“True”。

Added in version 1.0.

html_secnumber_suffix¶: 章节编号的后缀。默认值：“". "”。设置为“" "”以抑制最后点上的节号。

Added in version 1.0.

html_search_language¶

用于生成HTML全文搜索索引的语言。默认使用:confval:`语言`选择的全局语言。如果不支持该语言，则使用“"en"”选择英语语言。

支持这些语言:

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

加快生成速度

每种语言(日语除外)都提供自己的词干算法。 Sphinx默认使用Python实现。您可以使用C实现来加速构建索引文件。

`PorterStemmer <https://pypi.org/project/PorterStemmer/`_(“en”)
PyStemmer (all languages)

Added in version 1.1: 支持“en”和“ja”。

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

html_search_options¶

带有搜索语言支持选项的字典, 默认为空。这些选项的含义取决于所选语言。

英语支持没有选择。

日本的支持有这些选择：

类型:

type is dotted module path string to specify Splitter implementation which should be derived from sphinx.search.ja.BaseSplitter. If not specified or None is specified, 'sphinx.search.ja.DefaultSplitter' will be used.

您可以从以下模块中进行选择:

‘sphinx.search.ja.DefaultSplitter’:: TinySegmenter algorithm. 这是默认分割器。
‘sphinx.search.ja.MecabSplitter’:: 要使用这个拆分器, 需要 ‘mecab’ python绑定或动态链接库( ‘libmecab.so’ 用于linux, ‘libmecab.dll’ 用于windows)。
‘sphinx.search.ja.JanomeSplitter’:: Janome绑定。要使用这个分离器, 需要`Janome <https://pypi.org/project/Janome/>`_。

自 1.6 版本弃用: “’mecab’”, “’janome’”和 “’default’” 已弃用. 为了保持兼容性, “’mecab’”, “’janome’”和 “’default’”也可以接受。

其他选项值取决于您选择的拆分器值。

“’mecab’”的选项:

dic_enc:: dic_enc option 是MeCab算法的编码。
字典:: dict option 是用于MeCab算法的字典。
lib:: lib option 是用于在未安装Python绑定的情况下通过ctypes查找MeCab库的库名。

例如：

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

“’janome’”的选项:

user_dic:: user_dic option 是Janome的用户词典文件路径。
user_dic_enc:: user_dic_enc option 是“user_dic”选项指定的用户词典文件的编码。默认为 ‘utf8’。

Added in version 1.1.

在 1.4 版本发生变更: 重新组织日语的 html_search_options , 并且`type`_ settings 可以使用任何自定义拆分器。

中文的支持有这些选择:

“dict”– 如果想使用自定义词典, “jieba”字典路径。

html_search_scorer¶

实现搜索结果记分器的JavaScript文件的名称(相对于配置目录)。如果为空, 则使用默认值。

The scorer must implement the following interface, and may optionally define the score() function for more granular control.

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¶

If true, image itself links to the original image if it doesn’t have ‘target’ option or scale related options: ‘scale’, ‘width’, ‘height’. The default is True.

Document authors can disable this feature manually with giving no-scaled-link class to the image:

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

Added in version 1.3.

在 3.0 版本发生变更: 禁用有“no-scaled-link”类的图像。

html_math_renderer¶: HTML输出的math_renderer扩展名的名称。默认值是“’mathjax’”。

Added in version 1.8.

html_experimental_html5_writer¶: 输出由HTML5 writer处理。默认是“False”。

Added in version 1.6.

自 2.0 版本弃用.

html4_writer¶: 输出由HTML4 writer处理。默认是“False”。

单个HTML输出的选项¶

singlehtml_sidebars¶: Custom sidebar templates, must be a dictionary that maps document names to template names. And it only allows a key named 'index'. All other keys are ignored. For more information, refer to html_sidebars. By default, it is same as html_sidebars.

HTML帮助输出选项¶

htmlhelp_basename¶: HTML帮助生成器的输出文件基名。默认是“’pydoc’”。

htmlhelp_file_suffix¶: 这是生成的HTML帮助的文件名后缀。默认值是“".html"”。

Added in version 2.0.

htmlhelp_link_suffix¶: 生成到HTML文件的链接的后缀。默认是“”.html””。

Added in version 2.0.

Apple帮助输出选项¶

Added in version 1.3.

这些选项会影响Apple帮助输出。此构建器派生自HTML构建器, 因此HTML选项也适用于适用的位置。

备注

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

您可以使用以下命令禁用这些工具 applehelp_disable_external_tools, 但在索引器在bundle中的“.lproj”文件夹上运行之前, 结果将不是有效的帮助手册。

applehelp_bundle_name¶: Apple帮助手册的基本名称。默认为:confval:project 名称。

applehelp_bundle_id¶: 帮助手册包的软件包ID。

警告

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

applehelp_dev_region¶: 默认为“’en-us’”, 这是Apple的推荐设置。

applehelp_bundle_version¶: 捆绑版本(作为字符串)。默认为“’1’”。

applehelp_icon¶: 帮助包图标文件，或“None”表示无图标。根据苹果的文档，这应该是一个16×16像素的透明背景的应用程序图标，保存为PNG文件。

applehelp_kb_product¶: 用于的产品标签 applehelp_kb_url 。默认为 '<project>-<release>'。

applehelp_kb_url¶

知识库服务器的URL, 例如 “https://example.com/kbsearch.py?p=’product’&q=’query’&l=’lang’”。帮助查看器将在运行时使用:confval:`applehelp_kb_product内容替换值 “’product’”, “’query’”和 “’lang’”, 用户输入的文本搜索框和用户的系统语言。

没有远程搜索, 默认为 “None”。

applehelp_remote_url¶

您可以在此位置放置帮助手册的“Resources”文件夹的副本, 帮助查看器将尝试使用它来获取更新的内容。

例如如果你把它设置为“https://example.com/help/Foo/”并且帮助查看器 index.html 副本, 它会看到“https://example.com/help/Foo/en.lproj/index.html”。

没有远程搜索, 默认为“None”。

applehelp_index_anchors¶: 如果是“True”, 请告诉帮助索引器在生成的HTML中索引锚点。这对于在代码中使用“AHLookupAnchor”函数或 “openHelpAnchor:inBook:”方法跳转到特定主题非常有用。它还允许您使用“help:anchor”网址；有关此主题的更多信息, 请参阅Apple文档。

applehelp_min_term_length¶: 控制帮助索引器的最小术语长度。默认为“None”, 这意味着将使用默认值。

applehelp_stopwords¶

要么是语言规范(使用内置的停用词), 要么是停用词plist的路径, 要么是“None”, 如果你不想使用停用词。默认的停用词plist可以在 “/usr/share/hiutil/Stopwords.plist”找到, 并在编写时包含以下语言的停用词：

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

Defaults to language, or if that is not set, to 'en'.

applehelp_locale¶

指定要为其生成帮助的语言环境。这用于确定Help Book的 “Resources”中的“.lproj”文件夹的名称, 并传递给帮助索引器。

Defaults to language, or if that is not set, to 'en'.

applehelp_title¶: 指定帮助手册标题。默认为 '<project> Help'。

applehelp_codesign_identity¶

指定用于代码签名的标识, 如果不执行代码签名, 则指定 “None”。

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

applehelp_codesign_flags¶

签署帮助手册时要传递给:program:codesign 的附加参数的*list*。

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

applehelp_indexer_path¶: The path to the hiutil program. Defaults to '/usr/bin/hiutil'.

applehelp_codesign_path¶: program:codesign 程序的路径。默认为 “’/usr/bin/codesign’”。

applehelp_disable_external_tools¶

如果为 True , 则无论指定了什么其他设置, 构建器都不会运行索引器或代码签名工具。

这主要用于测试, 或者您希望在非Mac OS X平台上运行Sphinx构建, 然后出于某种原因在OS X上完成最终步骤。

默认为“False”。

epub输出的选项¶

These options influence the epub output. As this builder derives from the HTML builder, the HTML options also apply where appropriate. The actual values for some of the options is not really important, they just have to be entered into the Dublin Core metadata.

epub_basename¶: epub文件的基本名称。它默认为:confval:project 名称。

epub_theme¶: epub输出的HTML主题。由于默认主题未针对小屏幕空间进行优化, 因此使用相同的主题进行HTML和epub输出通常并不明智。这默认为 ‘epub’ , 这是一个旨在节省视觉空间的主题。

epub_theme_options¶: 影响所选主题外观的选项字典。这些是针对主题的。有关内置主题所理解的选项, 请参阅 :ref:`this section<builtin-themes> `。

Added in version 1.2.

epub_title¶: 文件的标题。它默认为 html_title`选项, 但可以为epub创建独立设置。它默认为:confval:`project 选项。

在 2.0 版本发生变更: 它默认为“project”选项。

epub_description¶: 该文件的作者姓名。默认值为“unknown”。

Added in version 1.4.

在 1.5 版本发生变更: 从“epub3_description”重命名

epub_author¶: 该文件的作者。这是在都柏林核心元数据中。它默认为 author 选项。

epub_contributor¶: 在创建EPUB出版物内容中起次要作用的个人, 组织等的名称。默认值为“’unknown’”。

Added in version 1.4.

在 1.5 版本发生变更: 从“epub3_contributor”重命名

epub_language¶: 文件的语言。这是在都柏林核心元数据中。如果未设置, 则默认为 language 选项或“’en’”。

epub_publisher¶: 该文件的出版商。这是在都柏林核心元数据中。您可以使用任何合理的字符串, 例如项目主页。默认为 author 选项。

epub_copyright¶: 该文件的版权。它默认为confval:copyright 选项, 但可以为epub创建独立设置。

epub_identifier¶: 文档的标识符。这是在都柏林核心元数据中。对于已发布的文档, 这是ISBN号, 但您也可以使用替代方案, 例如项目主页。默认值为“’unknown’”。

epub_scheme¶: 发布方案 confval:epub_identifier。这是在都柏林核心元数据中。对于已出版的书籍, 该计划是“’ISBN’”。如果您使用项目主页,“’URL’”似乎是合理的。默认值为 “’unknown’”。

epub_uid¶: 文档的唯一标识符。这是在都柏林核心元数据中。您可以使用 XML的名称格式<https://www.w3.org/TR/REC-xml/#NT-NameStartChar>`_string。您不能将连字符, 句点, 数字用作第一个字符。默认值为“’unknown’”。

epub_cover¶

封面信息。这是一个包含封面图像和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¶: CSS文件列表。该条目必须是 filename 字符串或包含 filename 字符串和*attributes* 字典的元组。有关更多信息, 请参阅:confval:html_css_files 。

Added in version 1.8.

epub_guide¶

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 at https://idpf.org/epub 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. Example:

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

默认值为“()”。

epub_pre_files¶

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

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

默认值为“[]”。

epub_post_files¶: 在Sphinx生成的文本之后应插入的其他文件。它是包含文件名和标题的元组列表。此选项可用于添加附录。如果标题为空, 则不会向:file:`toc.ncx`添加任何条目。默认值为“[]”。

epub_exclude_files¶: 在构建目录中生成/复制但不应包含在epub文件中的文件列表。默认值为“[]”。

epub_tocdepth¶: 文件中目录的深度 toc.ncx。它应该是大于零的整数。默认值为3。注意:深层嵌套的目录可能难以导航。

epub_tocdup¶: 此标志确定是否在其嵌套的 toc列表的开头再次插入 toc 条目。这样可以更轻松地导航到章节的顶部, 但可能会让人感到困惑, 因为它会在一个列表中混合不同深度的条目。默认值为“True”。

epub_tocscope¶

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

“’default’” - 包括所有未隐藏的toc条目(默认)
“’includehidden’” - 包括所有toc条目

Added in version 1.2.

epub_fix_images¶: 此标志确定sphinx是否应尝试修复某些epub阅读器不支持的图像格式。目前, 具有小颜色表的调色板图像被升级。您需要安装Pillow才能使用此选项。默认值为“False”, 因为自动转换可能会丢失信息。

Added in version 1.2.

epub_max_image_width¶: 此选项指定图像的最大宽度。如果将其设置为大于零的值, 则相应地缩放宽度大于给定值的图像。如果为零, 则不执行缩放。默认值为“0”。您需要安装Python Image Library(Pillow)才能使用此选项。

Added in version 1.2.

epub_show_urls¶

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

“’inline’” - 在括号中显示内联网址(默认)
“’footnote’” - 在脚注中显示网址
“‘不’” - 不显示网址

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

Added in version 1.2.

epub_use_index¶: 如果为true, 则为epub文档添加索引。它默认为 html_use_index 选项, 但可以为epub创建独立设置。

Added in version 1.2.

epub_writing_mode¶

它指定了书写方向。它可以接受“’horizontal’” (默认)和 “’vertical’”

“epub_writing_mode”	“’horizontal’”	`'vertical'`
writing-mode [2]	`horizontal-tb`	`vertical-rl`
page progression	left to right	right to left
iBook’s 滚动主题支持	scroll-axis 是垂直的。	scroll-axis 是水平的。

LaTeX输出的选项¶

这些选项会影响LaTeX输出。

latex_engine¶

用于生成文档的LaTeX引擎。该设置可以具有以下值:

'pdflatex' – PDFLaTeX (default)
'xelatex' – XeLaTeX
'lualatex' – LuaLaTeX
'platex' – pLaTeX
'uplatex' – upLaTeX (default if language is 'ja')

“’pdflatex’”对Unicode字符的支持是有限的。

备注

2.0增加了对拉丁语言文档中偶尔出现的西里尔字母或希腊字母或单词的pdflatex支持。这不是自动的，请参见:confval:latex_elements“’fontenc’”键的讨论。

如果您的项目使用Unicode字符，将引擎设置为“’xelatex’”或“’lualatex’”，并确保使用OpenType字体具有足够宽的字型覆盖通常比尝试让“’pdflatex’”处理额外的Unicode字符更容易。自从Sphinx 2.0以来，默认的是GNU FreeFont，它很好地涵盖了拉丁语、西里尔语和希腊语。

在 2.1.0 版本发生变更: 中文文件默认使用“xelatex”(和LaTeX包“xeCJK”)。

在 2.2.1 版本发生变更: 希腊文档默认使用“xelatex”。

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

在 4.0 版本发生变更: uplatex becomes the default setting of Japanese documents.

与:ref:MathJaX数学呈现的 HTML输出 1，LaTeX 需要一些额外的配置支持Unicode文本 数学：只有全面解决方案(据我们所知)是使用的“’xelatex’”或“’lualatex’”和*添加“r’usepackage {unicode-math}”(例如通过:confval:“latex_elements”“序言”键)。您可能更喜欢“r’usepackage[math-style=literal]{unicode-math}’”以保持输出中的Unicode文字，例如输出中的“ulu”(U+03B1)，而不是呈现为:math: ‘ alpha ‘。

latex_documents¶

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

startdocname: String that specifies the document name of the LaTeX file’s master document. All documents referenced by the startdoc document in TOC trees will be included in the LaTeX file. (If you want to use the default root document for your LaTeX build, provide your root_doc here.)
targetname: 输出目录中LaTeX文件的文件名。
title: LaTeX文档标题。可以为空以使用*startdoc*文档的标题。这是作为LaTeX标记插入的, 因此如果要按字面插入, 必须使用正确的LaTeX命令来表示反斜杠或符号等特殊字符。
author: LaTeX文档的作者。相同的LaTeX标记警告标题适用。使用“\\and”来分隔多个作者, 例如：“’John \\and Sarah”(反斜杠必须由Python转义才能到达LaTeX)。
theme: LaTeX主题。参见:confval:latex_theme。
toctree_only: 必须是 True 或 False 。如果为true, 则 startdoc 文档本身不包含在输出中, 只包含通过TOC树引用的文档。使用此选项, 您可以在主文档中添加额外的内容, 这些内容显示在HTML中, 而不是LaTeX输出中。

Added in version 1.2: 过去，包含自己的文档类需要在文档类名前加上字符串“sphinx”。现在这已经没有必要了。

Added in version 0.3: 第6项“toctree only”。包含5个条目的元组仍然被接受。

latex_logo¶: 如果给定，则必须是图像文件的名称(相对于 configuration directory 的)，即文档的徽标。它位于侧边栏的顶部;因此它的宽度不应超过200像素。默认值：“None”。

latex_toplevel_sectioning¶

该值确定最顶部的切片单元。它应该从 “’part’”, “’chapter’”或”’section’”中选择。默认为 “None”。最上面的分区单元由documentclass切换:如果documentclass是“howto”则使用“section”, 否则将使用“chapter”。

请注意, 如果LaTeX使用“part”命令, 那么一层深的切片单元的编号与HTML编号不同步, 因为LaTeX编号连续 “\chapter”(或 “section”为”howto”。)

Added in version 1.4.

latex_appendices¶: 要作为所有手册的附录附加的文档名称列表。

latex_domain_indices¶

如果为true, 则除了常规索引外, 还会生成特定于域的索引。对于例如Python域, 这是全局模块索引。默认为 “True”。

此值可以是bool或应生成的索引名称列表，如:confval:html_domain_indices。

Added in version 1.0.

latex_show_pagerefs¶: 如果为true, 则在内部引用后添加页面引用。这对手册的打印副本非常有用。默认为“False”。

Added in version 1.0.

latex_show_urls¶

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

“’不’” - 不显示网址(默认)
“’footnote’” - 在脚注中显示网址
“’inline’” - 在括号中内嵌显示网址

Added in version 1.0.

在 1.1 版本发生变更: 这个值现在是一个字符串;以前它是一个布尔值, 并且真值选择了”’inline’”显示。为了向后兼容, 仍然接受”True”。

latex_use_latex_multicolumn¶

默认是“False”: 这意味着Sphinx自己的宏用于网格表中的合并单元格。它们允许一般内容(文字块, 列表, 块引用, ……)但如果使用 tabularcolumns 指令来注入类型“ >{..}” , “<{..}” , “@ {..}”作为列规范的LaTeX标记, 则可能会出现问题。

设置为“True”表示使用LaTeX的标准“multicolumn”;这与水平合并单元格中的文字块不兼容, 如果使用“tabulary”呈现表, 则在此类单元格中也有多个段落。

Added in version 1.6.

latex_table_style¶

A list of styling classes (strings). Currently supported:

'booktabs': no vertical lines, and only 2 or 3 horizontal lines (the latter if there is a header), using the booktabs package.
'borderless': no lines whatsoever.
'colorrows': the table rows are rendered with alternating background colours. The interface to customize them is via dedicated keys of “sphinxsetup”配置设置.

重要

With the 'colorrows' style, the \rowcolors LaTeX command becomes a no-op (this command has limitations and has never correctly supported all types of tables Sphinx produces in LaTeX). Please update your project to use instead the latex table color configuration keys.

Default: ['booktabs', 'colorrows']

Added in version 5.3.0.

在 6.0.0 版本发生变更: Modify default from [] to ['booktabs', 'colorrows'].

Each table can override the global style via :class: option, or .. rst-class:: for no-directive tables (cf. 表格). Currently recognized classes are booktabs, borderless, standard, colorrows, nocolorrows. The latter two can be combined with any of the first three. The standard class produces tables with both horizontal and vertical lines (as has been the default so far with Sphinx).

A single-row multi-column merged cell will obey the row colour, if it is set. See also TableMergeColor{Header,Odd,Even} in the “sphinxsetup”配置设置 section.

备注

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 like this:
```
>{\columncolor{blue}\sphinxnorowcolor}
```
in a table column specification.
Sphinx also provides \sphinxcolorblend which however requires the xcolor package. Here is an example:
```
>{\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.

提示

If you want to use a special colour for the contents of the cells of a given column use >{\noindent\color{<color>}}, possibly in addition to the above.
Multi-row merged cells, whether single column or multi-column currently ignore any set column, row, or cell colour.
It is possible for a simple cell to set a custom colour via the raw directive and the \cellcolor LaTeX command used anywhere in the cell contents. This currently is without effect in a merged cell, whatever its kind.

提示

In a document not using 'booktabs' globally, it is possible to style an individual table via the booktabs class, but it will be necessary to add r'\usepackage{booktabs}' to the LaTeX preamble.

On the other hand one can use colorrows class for individual tables with no extra package (as Sphinx since 5.3.0 always loads colortbl).

latex_use_xindy¶

如果“True”，从Sphinx创建的LaTeX文件构建的PDF将使用 xindy (doc__) 而不是 makeindex 来准备通用术语的索引(使用 index )。这意味着:confval:`language`中的UTF-8字符将被正确排序。

如果:confval:latex_engine 是“’platex’”(日语文档；mendex 替换 :program:`makeindex`则)。
默认是“True”“’xelatex’”或“’lualatex’” makeindex，如果任何索引术语以非ascii字符开始，创建“.ind”。在UTF-8编码中包含无效字节的文件。“’lualatex’”这样就破坏了PDF的构建。
对于“’pdflatex’”，默认为“False”，但是对于非英语文档，只要一些索引术语使用语言脚本中的非ascii字符，建议使用“True”。

Sphinx在:program:xindy 基本发行版中增加了对使用带有西里尔字母脚本的“’pdflatex’”引擎的专门支持。无论使用“’pdflatex’”还是Unicode引擎，西里尔字母文档都能正确地处理拉丁名称的索引，甚至使用变音符号。

Added in version 1.8.

latex_elements¶: Added in version 0.5.

其:ref:documentation <latex_elements_confval> 已移至:doc:/latex。

latex_docclass¶: 将“’howto’”和“’manual’”映射到将用作两个Sphinx类基础的实际文档类的名称的字典。默认是使用“’本文’”“’howto’”和“’报告’”“’手动’”。

Added in version 1.0.

在 1.5 版本发生变更: 在日语文档中:confval:language 是“’ja’”)，默认情况下“’jreport’”用于“’howto’”，“’jsbook’”用于“’manual’”。

latex_additional_files¶

相对于配置目录的文件名列表，在生成LaTeX输出时要复制到生成目录。这对于复制Sphinx不会自动复制的文件非常有用，例如，如果它们在添加到“latex_elements”中的定制乳胶中被引用。在源文件（例如通过“.. 图像::”）中引用的图像文件会自动复制。

您必须确保您自己的文件名不会与那些自动复制的文件发生冲突。

注意

Filenames with extension .tex will automatically be 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 accordingly the \input{} command added to the LaTeX document preamble.

Added in version 0.6.

在 1.2 版本发生变更: 这将覆盖Sphinx提供的文件，比如“Sphinx .sty”。

latex_theme¶

LaTeX输出应该使用的“主题”。它是LaTeX输出的设置集合(例如，文档类、最高切片单元等等)。

作为一个内置 LaTeX主题，“手册”和“如何”是捆绑在一起的。

manual: 用于编写手册的LaTeX主题。它导入“报告”文档类(日本文档使用“jsbook”)。
howto: 用于写文章的LaTeX主题。它导入“文章”文档类(日本文档使用“jreport”’)。latex_appendices 仅用于此主题。

默认是“’manual’”。

Added in version 3.0.

latex_theme_options¶: 影响所选主题外观的选项字典。

Added in version 3.1.

latex_theme_path¶: 包含自定义主题的路径列表，可以是子目录。相对路径被视为相对于配置目录。

Added in version 3.0.

文本输出选项¶

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

text_newlines¶

确定在文本输出中使用哪个行尾字符。

“’unix’”：使用Unix风格的行结尾(“n”)
“’windows’”：使用Windows风格的行结尾(“rn”)
“’native’”：使用生成文档的平台的行结束样式

默认值：“’unix’”。

Added in version 1.1.

text_sectionchars¶

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

默认是“’*=-~”+`’”。

Added in version 1.1.

text_add_secnumbers¶: 一个布尔值, 用于决定文本输出中是否包含节号。默认为“True”。

Added in version 1.7.

text_secnumber_suffix¶: 文本输出中的章节编号后缀。默认值：“". "”。设置为“" "”以抑制最后点上的节号。

Added in version 1.7.

手动页面输出选项¶

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

man_pages¶

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

startdocname: String that specifies the document name of the manual page’s master document. All documents referenced by the startdoc document in TOC trees will be included in the manual file. (If you want to use the default root document for your manual pages build, use your root_doc here.)
name: 手册页的名称。这应该是一个没有空格或特殊字符的短字符串。它用于确定文件名以及手册页的名称(在NAME部分中)。
description: Description of the manual page. This is used in the NAME section. Can be an empty string if you do not want to automatically generate the NAME section.
authors: 包含作者或单个字符串的字符串列表。如果您不想在手册页中自动生成AUTHORS部分，则可以是空字符串或列表。
section: 手册页部分。用于输出文件名以及手册页头。

Added in version 1.0.

man_show_urls¶: 如果为true, 请在链接后添加URL地址。默认为“False”。

Added in version 1.1.

man_make_section_directory¶: If true, make a section directory on build man page. Default is True.

Added in version 3.3.

在 4.0 版本发生变更: The default is changed to False from True.

在 4.0.2 版本发生变更: The default is changed to True from False again.

Texinfo输出的选项¶

这些选项会影响Texinfo输出。

texinfo_documents¶

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

startdocname: String that specifies the document name of the the Texinfo file’s master document. All documents referenced by the startdoc document in TOC trees will be included in the Texinfo file. (If you want to use the default master document for your Texinfo build, provide your root_doc here.)
targetname: 输出目录中Texinfo文件的文件名（无扩展名）。
title: Texinfo文档标题。可以为空以使用*startdoc*文档的标题。作为Texinfo标记插入, 所以需要转义像“@” 和 “{}”这样的特殊字符。
author: Texinfo文档的作者。插入为Texinfo标记。使用“@*”来分隔多个作者, 如：“’John@*Sarah’”。
dir_entry: 将出现在顶级“DIR”菜单文件中的名称。
description: 描述性文本出现在顶级“DIR”菜单文件中。
category: 指定此条目将出现在顶级“DIR”菜单文件中的部分。
toctree_only: 必须是 True 或 False 。如果为true, 则 startdoc 文档本身不包含在输出中, 只包含通过TOC树引用的文档。使用此选项, 您可以在主文档中添加额外的内容, 这些内容显示在HTML中, 而不是Texinfo输出中。

Added in version 1.1.

texinfo_appendices¶: 要作为所有手册的附录附加的文档名称列表。

Added in version 1.1.

texinfo_domain_indices¶

如果为true, 则除了常规索引外, 还会生成特定于域的索引。对于例如Python域, 这是全局模块索引。默认为 “True”。

此值可以是bool或应生成的索引名称列表，如:confval:html_domain_indices。

Added in version 1.1.

texinfo_show_urls¶

控制如何显示URL地址。

“’footnote’”—在脚注中显示网址(默认)
“‘不’” - 不显示网址
“’inline’” - 在括号中内嵌显示网址

Added in version 1.1.

texinfo_no_detailmenu¶: 如果为真，不要在包含文档中每个子节点条目的“顶部”节点的菜单中生成“@detailmenu”。默认是“假”。

Added in version 1.2.

texinfo_elements¶

包含覆盖那些Sphinx的Texinfo片段的字典通常会放入生成的“.texi”文件中。

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

'paragraphindent'
每个段落的第一行缩进的空格数, 默认为“2”。指定“0”以表示没有缩进。

'exampleindent'
为示例或文字块缩进行的空格数, 默认为“4”。指定“0” 以表示没有缩进。

“序言”
Texinfo标记插入文件的开头附近。

'copying'
Texinfo标记插入“@copying”块并显示在标题之后。默认值包含标识项目的简单标题页。
由其他选项设置且因此不应重写的键包括：

'author' 'body' 'date' 'direntry' 'filename' 'project' 'release' 'title'

Added in version 1.1.

texinfo_cross_references¶: If false, do not generate inline references in a document. That makes an info file more readable with stand-alone reader (info). Default is True.

Added in version 4.4.

QtHelp输出的选项¶

这些选项会影响qthelp输出。由于此生成器派生自HTML生成器，因此HTML选项也适用。

qthelp_basename¶: qthelp文件的基本名称。它默认为:confval:`project`名称。

qthelp_namespace¶: qthelp文件的命名空间。它默认为“org.sphinx.<project_name>.<project_version>”。

qthelp_theme¶: qthelp输出的HTML主题。这默认为“’nonav’”。

qthelp_theme_options¶: 影响所选主题外观的选项字典。这些是针对主题的。有关内置主题所理解的选项, 请参阅 :ref:`this section<builtin-themes> `。

linkcheck生成器的选项¶

linkcheck_ignore¶

一个正则表达式列表, 它匹配在执行“linkcheck” 生成时不应检查的URI。例:

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

Added in version 1.1.

linkcheck_allowed_redirects¶

A dictionary that maps a pattern of the source URI to a pattern of the canonical URI. The linkcheck builder treats the redirected link as “working” when:

the link in the document matches the source URI pattern, and
the redirect location matches the canonical URI pattern.

举例如下：

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/.*'
}

If set, linkcheck builder will emit a warning when disallowed redirection found. It’s useful to detect unexpected redirects under the warn-is-error mode.

Added in version 4.1.

linkcheck_request_headers¶

将baseurls映射到HTTP请求标题的字典。

The key is a URL base string like "https://www.sphinx-doc.org/". To specify headers for other hosts, "*" can be used. It matches all hosts only when the URL does not match other settings.

该值是一个将标题名称映射到其值的字典。

举例如下：

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¶: linkcheck生成器在声明URL之前尝试检查URL的次数。默认为1次尝试。

Added in version 1.4.

linkcheck_timeout¶: The duration, in seconds, that the linkcheck builder will wait for a response after each hyperlink request. Defaults to 30 seconds.

Added in version 1.1.

linkcheck_workers¶: 检查链接时要使用的工作线程数。默认值为5个线程。

Added in version 1.1.

linkcheck_anchors¶: 如果为true, 请检查链接中“#anchor”的有效性。由于这需要下载整个文档, 因此启用时会相当慢。默认为 “True”。

Added in version 1.2.

linkcheck_anchors_ignore¶

在检查链接中锚的有效性时，Sphinx应该跳过与锚匹配的正则表达式列表。这允许跳过网站JavaScript为控制动态页面或触发内部REST请求而添加的锚。默认是“[“^!”]”。

小技巧

Use linkcheck_anchors_ignore_for_url to check a URL, but skip verifying that the anchors exist.

备注

如果你想忽略一个特定页面的锚点或匹配特定模式的页面的锚点(但仍然检查没有锚点的相同页面)，使用:confval:linkcheck_ignore 代替，例如:

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

Added in version 1.5.

linkcheck_anchors_ignore_for_url¶: A list or tuple of regular expressions matching URLs for which Sphinx should not check the validity of anchors. This allows skipping anchor checks on a per-page basis while still checking the validity of the page itself. Default is an empty tuple ().

Added in version 7.1.

linkcheck_auth¶

在进行``linkcheck`` 构建时提供身份验证信息。

一个“(regex_pattern, auth_info) ”元组的列表，其中的项是：

regex_pattern: 匹配URI的正则表达式。
auth_info: Authentication information to use for that URI. The value can be anything that is understood by the requests library (see requests Authentication for details).

“linkcheck”生成器将使用在:confval:linkcheck_auth’列表中找到的第一个匹配的“auth_info”值，因此列表中较早的值具有更高的优先级。

例如：

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

Added in version 2.3.

linkcheck_rate_limit_timeout¶

The linkcheck builder may issue a large number of requests to the same site over a short period of time. This setting controls the builder behavior when servers indicate that requests are rate-limited.

If a server indicates when to retry (using the Retry-After header), linkcheck always follows the server indication.

Otherwise, linkcheck waits for a minute before to retry and keeps doubling the wait time between attempts until it succeeds or exceeds the linkcheck_rate_limit_timeout. By default, the timeout is 300 seconds and custom timeouts should be given in seconds.

Added in version 3.4.

linkcheck_exclude_documents¶

A list of regular expressions that match documents in which Sphinx should not check the validity of links. This can be used for permitting link decay in legacy or historical sections of the documentation.

例如：

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

Added in version 4.4.

linkcheck_allow_unauthorized¶

When a webserver responds with an HTTP 401 (unauthorized) response, the current default behaviour of Sphinx is to treat the link as “working”. To change that behaviour, set this option to False.

The default value for this option will be changed in Sphinx 8.0; from that version onwards, HTTP 401 responses to checked hyperlinks will be treated as “broken” by default.

Added in version 7.3.

linkcheck_report_timeouts_as_broken¶

When an HTTP response is not received from a webserver before the configured linkcheck_timeout expires, the current default behaviour of Sphinx is to treat the link as ‘broken’. To report timeouts using a distinct report code of timeout, set linkcheck_report_timeouts_as_broken to False.

From Sphinx 8.0 onwards, timeouts that occur while checking hyperlinks will be reported using the new ‘timeout’ status code.

Added in version 7.3.

XML生成器的选项¶

xml_pretty¶: 如果为true, 则打印XML。默认为“True”。

Added in version 1.2.

脚注

C域选项¶

c_id_attributes¶: 解析器另外应该接受的字符串列表作为属性。例如, 当属性为“#define”以便于移植时，可以使用它。

Added in version 3.0.

c_paren_attributes¶: 解析器另外应该接受的字符串列表, 作为具有一个参数的属性。也就是说, 如果“my_align_as”在列表中, 则“my_align_as(X)”被解析为所有字符串 X 的属性, 它们具有平衡括号(“()” , “[]”和 “{}” )。例如, 当属性为 “#define”以便于移植时, 可以使用它。

Added in version 3.0.

c_extra_keywords¶: A list of identifiers to be recognized as keywords by the C parser. It defaults to ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local'].

Added in version 4.0.3.

c_maximum_signature_line_length¶: If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

Added in version 7.1.

C++ 域选项¶

cpp_index_common_prefix¶: 在全局索引中排序 C++ 对象时，将忽略的前缀列表。例如“[‘awesome_lib::’]”。

Added in version 1.5.

cpp_id_attributes¶: 解析器另外应该接受的字符串列表作为属性。例如, 当属性为“#define”以便于移植时，可以使用它。

Added in version 1.5.

cpp_paren_attributes¶: 解析器另外应该接受的字符串列表, 作为具有一个参数的属性。也就是说, 如果“my_align_as”在列表中, 则“my_align_as(X)”被解析为所有字符串 X 的属性, 它们具有平衡括号(“()” , “[]”和 “{}” )。例如, 当属性为 “#define”以便于移植时, 可以使用它。

Added in version 1.5.

cpp_maximum_signature_line_length¶: If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

Added in version 7.1.

Options for the Python domain¶

python_display_short_literal_types¶

This value controls how Literal types are displayed. The setting is a boolean, default False.

实际案例¶

The examples below use the following py:function directive:

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

When False, Literal types display as per standard Python syntax, i.e.:

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

When True, Literal types display with a short, PEP 604-inspired syntax, i.e.:

serve_food(item: "egg" | "spam" | "lobster thermidor") -> None

Added in version 6.2.

python_use_unqualified_type_names¶: If true, suppress the module name of the python reference if it can be resolved. The default is False.

Added in version 4.0.

备注

This configuration is still in experimental

python_maximum_signature_line_length¶

If a signature’s length in characters exceeds the number set, each argument or type parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

For the Python domain, the signature length depends on whether the type parameters or the list of arguments are being formatted. For the former, the signature length ignores the length of the arguments list; for the latter, the signature length ignores the length of the type parameters list.

For instance, with python_maximum_signature_line_length = 20, only the list of type parameters will be wrapped while the arguments list will be rendered on a single line

.. py:function:: add[T: VERY_LONG_SUPER_TYPE, U: VERY_LONG_SUPER_TYPE](a: T, b: U)

Added in version 7.1.

Options for the Javascript domain¶

javascript_maximum_signature_line_length¶: If a signature’s length in characters exceeds the number set, each parameter will be displayed on an individual logical line. This is a domain-specific setting, overriding maximum_signature_line_length.

Added in version 7.1.

配置文件示例¶

# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is executed through importlib.import_module with 
# the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

# -- General configuration ------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'

# The encoding of source files.
#
# source_encoding = 'utf-8-sig'

# The master toctree document.
root_doc = 'index'

# General information about the project.
project = 'test'
copyright = '2016, test'
author = 'test'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = 'test'
# The full version, including alpha/beta/rc tags.
release = 'test'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None

# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#
# today = ''
#
# Else, today_fmt is used as the format for a strftime call.
#
# today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# These patterns also affect html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The reST default role (used for this markup: `text`) to use for all
# documents.
#
# default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.
#
# add_function_parentheses = True

# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#
# add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#
# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []

# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False


# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Theme options are theme-specific and customize the look and feel of a theme
# further.  For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []

# The name for this set of Sphinx documents.
# "<project> v<release> documentation" by default.
#
# html_title = 'test vtest'

# A shorter title for the navigation bar.  Default is the same as html_title.
#
# html_short_title = None

# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#
# html_logo = None

# The name of an image file (relative to this directory) to use as a favicon of
# the docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#
# html_extra_path = []

# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
#
# html_last_updated_fmt = None

# Custom sidebar templates, maps document names to template names.
#
# html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to
# template names.
#
# html_additional_pages = {}

# If false, no module index is generated.
#
# html_domain_indices = True

# If false, no index is generated.
#
# html_use_index = True

# If true, the index is split into individual pages for each letter.
#
# html_split_index = False

# If true, links to the reST sources are added to the pages.
#
# html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#
# html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#
# html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it.  The value of this option must be the
# base URL from which the finished HTML is served.
#
# html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None

# Language to be used for generating the HTML full-text search index.
# Sphinx supports the following languages:
#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh'
#
# html_search_language = 'en'

# A dictionary with options for the search language support, empty by default.
# 'ja' uses this config value.
# 'zh' user can custom change `jieba` dictionary path.
#
# html_search_options = {'type': 'default'}

# The name of a javascript file (relative to the configuration directory) that
# implements a search results scorer. If empty, the default will be used.
#
# html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'testdoc'

# -- Options for LaTeX output ---------------------------------------------

latex_elements = {
    # The paper size ('letterpaper' or 'a4paper').
    #
    # 'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').
    #
    # 'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.
    #
    # 'preamble': '',

    # Latex figure (float) alignment
    #
    # 'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
#  author, documentclass [howto, manual, or own class]).
latex_documents = [
    (root_doc, 'test.tex', 'test Documentation',
     'test', 'manual'),
]

# The name of an image file (relative to this directory) to place at the top of
# the title page.
#
# latex_logo = None

# If true, show page references after internal links.
#
# latex_show_pagerefs = False

# If true, show URL addresses after external links.
#
# latex_show_urls = False

# Documents to append as an appendix to all manuals.
#
# latex_appendices = []

# If false, no module index is generated.
#
# latex_domain_indices = True


# -- Options for manual page output ---------------------------------------

# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
    (root_doc, 'test', 'test Documentation',
     [author], 1)
]

# If true, show URL addresses after external links.
#
# man_show_urls = False


# -- Options for Texinfo output -------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
#  dir menu entry, description, category)
texinfo_documents = [
    (root_doc, 'test', 'test Documentation',
     author, 'test', 'One line description of project.',
     'Miscellaneous'),
]

# Documents to append as an appendix to all manuals.
#
# texinfo_appendices = []

# If false, no module index is generated.
#
# texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.
#
# texinfo_show_urls = 'footnote'

# If true, do not generate a @detailmenu in the "Top" node's menu.
#
# texinfo_no_detailmenu = False

# If false, do not generate in manual @ref nodes.
#
# texinfo_cross_references = False

# -- A random example -----------------------------------------------------

import sys, os
sys.path.insert(0, os.path.abspath('.'))
exclude_patterns = ['zzz']

numfig = True
#language = 'ja'

extensions.append('sphinx.ext.todo')
extensions.append('sphinx.ext.autodoc')
#extensions.append('sphinx.ext.autosummary')
extensions.append('sphinx.ext.intersphinx')
extensions.append('sphinx.ext.mathjax')
extensions.append('sphinx.ext.viewcode')
extensions.append('sphinx.ext.graphviz')


autosummary_generate = True
html_theme = 'default'
#source_suffix = ['.rst', '.txt']

Sphinx

On this page

Site navigation

配置¶

项目信息¶

一般配置¶

国际化选项¶

数学选项¶

HTML输出选项¶

单个HTML输出的选项¶

HTML帮助输出选项¶

Apple帮助输出选项¶

epub输出的选项¶

LaTeX输出的选项¶

文本输出选项¶

手动页面输出选项¶

Texinfo输出的选项¶

QtHelp输出的选项¶

linkcheck生成器的选项¶

XML生成器的选项¶

C域选项¶

C++ 域选项¶

Options for the Python domain¶

实际案例¶

Options for the Javascript domain¶

配置文件示例¶