配置¶

配置目录必须包含名为 conf.py 的文件。这个文件（包含Python代码）被称为“构建配置文件”，其中包含几乎所有需要定制的 Sphinx 输入和输出行为的配置。

可选的文件 docutils.conf 可以添加到配置目录中以调整 Docutils 配置，如果未被其他方式覆盖或由 Sphinx 设置。

需要注意的重要事项：

如无其他说明，值必须为字符串，且默认为空字符串。
术语“完全限定名称”（Fully-Qualified Name，简称 FQN）指的是一个字符串，用于命名模块内可导入的 Python 对象；例如，完全限定名称 "sphinx.builders.Builder" 表示 sphinx.builders 模块中的 Builder 类。
文档名称使用 / 作为路径分隔符，并且不包含文件扩展名。

在允许使用通配符模式的地方，您可以使用标准的 shell 结构（*、?、[...] 和 [!...] ），但需要注意的是这些通配符不会匹配斜杠（/）。双星号 ** 可用于匹配包括斜杠在内的任意字符序列。

Tip

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

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

配置命名空间的内容会被序列化（以便 Sphinx 能够检测配置何时发生变化），因此它不能包含不可序列化的值——如果适用，请使用 del 将它们从命名空间中删除。模块会自动被移除，因此无需删除已导入的模块。

项目标签¶

配置文件中有名为 tags 的特殊对象，它公开了项目标签。标签可以通过 --tag 命令行选项或 tags.add('tag') 来定义。请注意，构建器的名称和格式标签在 conf.py 中不可用。

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

要查询某个标签是否已设置，请使用 'tag' in tags。
要添加标签，请使用 tags.add('tag')。
要移除标签，请使用 tags.remove('tag')。

项目信息¶

project¶

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

记录项目的名称。例如：

project = 'Thermidor'

author¶

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

项目的作者。例如：

author = 'Joe Bloggs'

copyright¶

project_copyright¶

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

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

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

Added in version 3.5: The project_copyright alias.

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.

Changed in version 1.4: 允许使用 'major.minor.micro' 版本字符串。

extensions¶

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

字符串列表，表示 Sphinx 插件的模块名称。这些插件可以是与 Sphinx 捆绑的插件（命名为 sphinx.ext.*），也可以是自定义的第一方或第三方插件。

要使用第三方插件，您必须确保它已安装，并将其包含在 extensions 列表中，如下所示：

extensions = [
    ...
    'numpydoc',
]

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

在修改 sys.path 时，请确保使用绝对路径。如果您的自定义插件位于相对于配置目录的目录中，请使用 pathlib.Path.resolve()，如下所示：

import sys
from pathlib import Path

sys.path.append(str(Path('sphinxext').resolve()))

extensions = [
   ...
   'extname',
]

上述目录结构将如下所示：

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

needs_extensions¶

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

如果设置，此值必须是字典，用于指定 extensions 中插件的版本要求。版本字符串应采用 'major.minor' 形式。不需要为所有插件指定要求，只需为您想要检查的插件指定。例如：

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

这要求插件在其 setup() 函数中声明其版本。有关更多详细信息，请参阅 Sphinx API。

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: The manual section (1)
path: The original manual page and section specified (man(1))

This also supports manpages specified as 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 构建器支持此功能。

Note

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

Added in version 1.3.

numfig_format¶

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

字典，用于将 'figure'、'table'、'code-block' 和 'section' 映射到用于图表编号格式的字符串。标记 %s 将被替换为图表编号。

默认值：

numfig_format = {
    'code-block': 'Listing %s',
    'figure': 'Fig. %s',
    'section': 'Section',
    'table': 'Table %s',
}

Added in version 1.3.

numfig_secnum_depth¶

类型:: int
默认值:: 1

如果设置为 0，图表、表格和代码块将从 1 开始连续编号。
如果设置为 1，编号将为 x.1、x.2，...，其中 x 表示章节编号。（如果没有顶级章节，则不会添加前缀）。此功能仅在通过 toctree 指令的 :numbered: 选项启用章节编号时适用。
如果设置为 2，编号将为 x.y.1、x.y.2，...，其中 x 表示章节编号，y 表示子章节编号。如果直接位于章节下，则不会有 y. 前缀；如果没有顶级章节，则不会添加前缀。
任何其他正整数也可以使用，遵循上述规则。

Added in version 1.3.

Changed in version 1.7: 如果 numfig 设置为 True，则 LaTeX 构建器会遵循此设置。

代码高亮的选项¶

highlight_language¶

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

用于高亮源代码的默认语言。默认值为 'default'，如果作为 Python 代码高亮失败，此设置会抑制警告。

该值应为有效的 Pygments 词法分析器名称，详见 Showing code examples 获取更多信息。

Added in version 0.5.

Changed in version 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.

Changed in version 3.5: 允许为多个词法分析器配置高亮选项。

pygments_style¶

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

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

Changed in version 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.

Tip

Sphinx 内部使用 requests 作为 HTTP 库。如果未设置 tls_cacerts，Sphinx 将回退到 requests 的默认行为。详见 SSL Cert Verification 获取更多信息。

user_agent¶

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

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

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.

Changed in version 1.4: 支持图片替换

Changed in version 5.0: 默认值现在为 'en' （之前为 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 -- 简体中文
zh_TW -- 繁体中文

locale_dirs¶

类型:: list[str]
默认值:: ['locales']

用于搜索额外消息目录(message catalogs)的目录（参见 language），相对于源目录。此路径上的目录由 gettext 模块搜索。

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

Note

sphinx-build 的 -v 选项 对于检查 locale_dirs 设置是否按预期工作非常有用。如果未找到消息目录，则会发出调试信息。

Added in version 0.5.

Changed in version 1.5: 使用 locales 目录作为默认值

gettext_allow_fuzzy_translations¶

类型:: bool
默认值:: False

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

Added in version 4.3.

gettext_compact¶

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

如果为 True，文档的文本域是其文档名称（如果它是顶级项目文件），否则是其最基础的目录。
如果为 False，文档的文本域是其完整的文档名称。
如果设置为字符串，则每个文档的文本域都将设置为该字符串，使所有文档使用单一文本域。

当 gettext_compact = True 时，文档 markup/code.rst 的文本域为 markup。当此选项设置为 False 时，文本域为 markup/code。当此选项设置为 'sample' 时，文本域为 sample。

Added in version 1.1.

Changed in version 3.3: 允许字符串值。

gettext_uuid¶

类型:: bool
默认值:: False

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

为 .pot 文件中的每个 msgid 添加 UUID 行。
计算新 msgids 与之前保存的旧 msgids 之间的相似度。（此计算可能耗时较长。）

Tip

如果你想加速计算，可以通过运行 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' -- index terms
'literal-block' -- literal blocks (:: annotation and code-block directive)
'doctest-block' -- doctest block
'raw' -- raw content
'image' -- image/figure uri

Added in version 1.3.

Changed in version 4.0: 默认情况下，图片的替代文本会被翻译。

Changed in version 7.4: 允许并优先使用集合类型。

figure_language_filename¶

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

语言特定图片的文件名格式。可用的格式标记包括：

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

默认情况下，使用 images/filename.png 的图片指令 .. image:: 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.

Changed in version 1.5: 添加了 {path} 和 {basename} 标记。

Changed in version 3.2: 添加了 {docpath} 标记。

translation_progress_classes¶

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

控制是否添加类以指示翻译进度。此设置可能仅由文档翻译人员使用，以便快速指示已翻译和未翻译的内容。

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

Added in version 7.1.

标记选项¶

default_role¶

类型:: str
默认值:: None

The name of a reStructuredText role (builtin or Sphinx extension) to use as the default role, that is, for text marked up `like this`. This can be set to 'py:obj' to make `filter` a cross-reference to the Python function "filter".

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

Added in version 0.4.

keep_warnings¶

类型:: bool
默认值:: False

Keep warnings as "system message" paragraphs in the rendered documents. Warnings are always written to the standard error stream when sphinx-build is run, regardless of this setting.

Added in version 0.5.

option_emphasise_placeholders¶

类型:: bool
默认值:: 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.

primary_domain¶

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

The name of the default domain. Can also be None to disable a default domain. The default is 'py', for the Python domain.

Those objects in other domain (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"). Example:

primary_domain = 'cpp'

Added in version 1.0.

rst_epilog¶

类型:: str
默认值:: ''

A string of reStructuredText that will be included at the end of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_prolog). Example:

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

Added in version 0.6.

rst_prolog¶

类型:: str
默认值:: ''

A string of reStructuredText that will be included at the beginning of every source file that is read. This is a possible place to add substitutions that should be available in every file (another being rst_epilog). Example:

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

Added in version 1.0.

show_authors¶

类型:: bool
默认值:: False

A boolean that decides whether codeauthor and sectionauthor directives produce any output in the built files.

trim_footnote_reference_space¶

类型:: bool
默认值:: False

Trim spaces before footnote references that are necessary for the reStructuredText parser to recognise the footnote, but do not look too nice in the output.

Added in version 0.6.

Options for Maths¶

These options control maths markup and notation.

math_eqref_format¶

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

A string used for formatting the labels of references to equations. The {number} place-holder stands for the equation number.

Example: 'Eq.{number}' gets rendered as, for example, Eq.10.

Added in version 1.7.

math_number_all¶

类型:: bool
默认值:: False

Force all displayed equations to be numbered. Example:

math_number_all = True

Added in version 1.4.

math_numfig¶

类型:: bool
默认值:: True

If True, displayed math equations are numbered across pages when numfig is enabled. The numfig_secnum_depth setting is respected. The eq, not numref, role must be used to reference equation numbers.

Added in version 1.7.

math_numsep¶

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

A string that defines the separator between section numbers and the equation number when numfig is enabled and numfig_secnum_depth is positive.

Example: '-' gets rendered as 1.2-3.

Added in version 7.4.

Options for the nitpicky mode¶

nitpicky¶

类型:: bool
默认值:: False

Enables nitpicky mode if True. In nitpicky mode, Sphinx will warn about all references where the target cannot be found. This is recommended for new projects as it ensures that all references are to valid targets.

You can activate this mode temporarily using the --nitpicky command-line option. See nitpick_ignore for a way to mark missing references as "known missing".

nitpicky = True

Added in version 1.0.

nitpick_ignore¶

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

A set or list of (warning_type, target) tuples that should be ignored when generating warnings in "nitpicky mode". Note that warning_type should include the domain name if present. Example:

nitpick_ignore = {
    ('py:func', 'int'),
    ('envvar', 'LD_LIBRARY_PATH'),
}

Added in version 1.1.

Changed in version 6.2: Changed allowable container types to a set, list, or tuple

nitpick_ignore_regex¶

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

An extended version of nitpick_ignore, which instead interprets the warning_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.

Changed in version 6.2: Changed allowable container types to a set, list, or tuple

Options for object signatures¶

add_function_parentheses¶

类型:: bool
默认值:: True

A boolean that decides whether parentheses are appended to function and method role text (e.g. the content of :func:`input`) to signify that the name is callable.

maximum_signature_line_length¶

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

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

strip_signature_backslash¶

类型:: bool
默认值:: False

When backslash stripping is enabled then every occurrence of \\ in a domain directive will be changed to \, even within string literals. This was the behaviour before version 3.0, and setting this variable to True will reinstate that behaviour.

Added in version 3.0.

toc_object_entries¶

类型:: bool
默认值:: True

Create table of contents entries for domain objects (e.g. functions, classes, attributes, etc.).

Added in version 5.2.

toc_object_entries_show_parents¶

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

A string that determines how domain objects (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.

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.

Options for source files¶

exclude_patterns¶

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

A list of glob-style patterns 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. exclude_patterns has priority over include_patterns.

Example patterns:

'library/xml.rst' -- ignores the library/xml.rst file
'library/xml' -- ignores the library/xml directory
'library/xml*' -- ignores all files and directories starting with library/xml
'**/.git' -- ignores all .git directories
'Thumbs.db' -- ignores all Thumbs.db files

exclude_patterns is also consulted when looking for static files in html_static_path and html_extra_path.

Added in version 1.0.

include_patterns¶

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

A list of glob-style patterns 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. By default, all files are recursively included from the source directory. exclude_patterns has priority over include_patterns.

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

master_doc¶

root_doc¶

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

Sphinx builds a tree of documents based on the toctree directives contained within the source files. This sets the name of the document containing the master toctree directive, and hence the root of the entire tree. Example:

master_doc = 'contents'

Changed in version 2.0: Default is 'index' (previously 'contents').

Added in version 4.0: The root_doc alias.

source_encoding¶

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

The file encoding of all source files. The recommended encoding is 'utf-8-sig'.

Added in version 0.5.

source_suffix¶

类型:: dict[str, str] | Sequence[str] | str
默认值:: {'.rst': 'restructuredtext'}

A dictionary mapping the file extensions (suffixes) of source files to their file types. Sphinx considers all files files with suffixes in source_suffix to be source files. Example:

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

By default, Sphinx only supports the 'restructuredtext' file type. Further file types can be added with extensions that register different source file parsers, such as MyST-Parser. Refer to the extension's documentation to see which file types it supports.

If the value is a string or sequence of strings, Sphinx will consider that they are all 'restructuredtext' files.

Note

File extensions must begin with a dot ('.').

Changed in version 1.3: Support a list of file extensions.

Changed in version 1.8: Change to a map of file extensions to file types.

Options for smart quotes¶

smartquotes¶

类型:: bool
默认值:: True

If True, the Smart Quotes transform will be used to convert quotation marks and dashes to typographically correct entities.

Added in version 1.6.6: Replaces the now-removed html_use_smartypants. It applies by default to all builders except man and text (see smartquotes_excludes.)

Note

A docutils.conf file located in the configuration directory (or a global ~/.docutils file) is obeyed unconditionally if it deactivates smart quotes via the corresponding Docutils option. But if it activates them, then smartquotes does prevail.

smartquotes_action¶

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

Customise the Smart Quotes transform. See below for the permitted codes. The default 'qDe' educates normal quote characters ", ', em- and en-Dashes ---, --, and ellipses .....

'q': Convert quotation marks
'b': Convert backtick quotation marks (``double'' only)
'B': Convert backtick quotation marks (``double'' and `single')
'd': Convert dashes (convert -- to em-dashes and --- to en-dashes)
'D': Convert dashes (old school) (convert -- to en-dashes and --- to em-dashes)
'i': Convert dashes (inverted old school) (convert -- to em-dashes and --- to en-dashes)
'e': Convert ellipses ...
'w': Convert '"' entities to '"'

Added in version 1.6.6.

smartquotes_excludes¶

类型:: dict[str, list[str]]
默认值:: {'languages': ['ja'], 'builders': ['man', 'text']}

Control when the Smart Quotes transform is disabled. Permitted keys are 'builders' and 'languages', and The values are lists of strings.

Each entry gives a sufficient condition to ignore the smartquotes setting and deactivate the Smart Quotes transform. Example:

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

Note

Currently, in case of invocation of make with multiple targets, the first target name is the only one which is tested against the 'builders' entry and it decides for all. Also, a make text following make html needs to be issued in the form make text SPHINXOPTS="-E" to force re-parsing of source files, as the cached ones are already transformed. On the other hand the issue does not arise with direct usage of sphinx-build as it caches (in its default usage) the parsed source files in per builder locations.

Hint

An alternative way to effectively deactivate (or customise) the smart quotes for a given builder, for example latex, is to use make this way:

make latex SPHINXOPTS="-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.

Options for templating¶

template_bridge¶

类型:: str
默认值:: ''

A string with the fully-qualified name of a callable (or simply a class) that returns an instance of TemplateBridge. This instance is then used to render HTML documents, and possibly the output of other builders (currently the changes builder). (Note that the template bridge must be made theme-aware if HTML themes are to be used.) Example:

template_bridge = 'module.CustomTemplateBridge'

templates_path¶

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

A list of paths that contain extra templates (or templates that overwrite builtin/theme-specific templates). Relative paths are taken as relative to the configuration directory. Example:

templates_path = ['.templates']

Changed in version 1.3: As these files are not meant to be built, they are automatically excluded when discovering source files.

Options for warning control¶

show_warning_types¶

类型:: bool
默认值:: True

Add the type of each warning as a suffix to the warning message. For example, WARNING: [...] [index] or WARNING: [...] [toc.circular]. This setting can be useful for determining which warnings types to include in a suppress_warnings list.

Added in version 7.3.0.

Changed in version 8.0.0: The default is now True.

suppress_warnings¶

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

A list of warning codes to suppress arbitrary warning messages.

By default, Sphinx supports the following warning codes:

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

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
autosummary.import_cycle
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.

Changed in version 1.5: Added misc.highlighting_failure

Changed in version 1.5.1: Added epub.unknown_project_files

Changed in version 1.6: Added ref.footnote

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

Changed in version 3.3.0: Added epub.duplicated_toc_entry

Changed in version 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.

Added in version 7.3: Added config.cache.

Added in version 7.3: Added toc.no_title.

Added in version 8.0: Added misc.copy_overwrite.

Builder options¶

Options for HTML output¶

These options influence HTML output. Various other builders are derived from the HTML output, and also make use of these options.

html_theme¶

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

The theme for HTML output. See the HTML theming section.

Added in version 0.6.

Changed in version 1.3: The default theme is now 'alabaster'.

html_theme_options¶

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

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. The options understood by the builtin themes are described here.

Added in version 0.6.

html_theme_path¶

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

A list of paths that contain custom themes, either as subdirectories or as zip files. Relative paths are taken as relative to the configuration directory.

Added in version 0.6.

html_style¶

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

Stylesheets to use for HTML pages. The stylesheet given by the selected theme is used by default A file of that name must exist either in Sphinx's static/ path or in one of the custom paths given in html_static_path. If you only want to add or override a few things from the theme, use CSS @import to import the theme's stylesheet.

Changed in version 5.1: The value can be a iterable of strings.

html_title¶

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

The "title" for HTML documentation generated with Sphinx's own templates. This is appended to the <title> tag of individual pages, and used in the navigation bar as the "topmost" element.

html_short_title¶

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

A shorter "title" for HTML documentation. This is used for links in the header and in the HTML Help documentation.

Added in version 0.4.

html_baseurl¶

类型:: str
默认值:: ''

基本 URL 指向 HTML 文档的根目录。它用于指示使用 规范链接关系 的文档位置。

Added in version 1.8.

html_codeblock_linenos_style¶

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

The style of line numbers for code-blocks.

'table': Display line numbers using <table> tag
'inline': Display line numbers using <span> tag

Added in version 3.2.

Changed in version 4.0: It defaults to 'inline'.

Deprecated since version 4.0.

html_context¶

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

A dictionary of values to pass into the template engine's context for all pages. Single values can also be put in this dictionary using sphinx-build's --html-define command-line option.

Added in version 0.5.

html_logo¶

类型:: str
默认值:: ''

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

Added in version 0.4.1: 该图像文件将被复制到 _static 目录中，但仅当该文件尚未存在于该目录时才会执行复制操作。

Changed in version 4.0: 同时支持使用 URL 链接。

html_favicon¶

类型:: str
默认值:: ''

如果提供，这必须是图像文件的名称（路径相对于配置目录），该文件是文档的 favicon，或者是指向网站图标图像文件的 URL。浏览器会将其用作标签页、窗口和书签的图标。它应为 16x16 像素的图标，文件格式为 PNG、SVG、GIF 或 ICO。

示例

html_favicon = 'static/favicon.png'

Added in version 0.4: 该图像文件将被复制到 _static 目录中，但仅当该文件尚未存在于该目录时才会执行复制操作。

Changed in version 4.0: 同时支持使用网站图标的URL链接。

html_css_files¶

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

CSS 文件的列表。条目必须是 文件名 字符串，或者包含 文件名 字符串和属性字典的元组。文件名 必须相对于 html_static_path，或者是带有协议（如 'https://example.org/style.css'）的完整URI。属性字典用于 <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.

Changed in version 3.5: 支持 priority 属性

html_js_files¶

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

JavaScript 文件的列表。条目必须是 文件名 字符串，或者包含 文件名 字符串和属性字典的元组。文件名 必须相对于 html_static_path，或者是带有协议（如 'https://example.org/script.js'）的完整URI。属性字典用于 <script> 标签的属性。

示例

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 later step. For more information, refer to Sphinx.add_js_file().

Added in version 1.8.

Changed in version 3.5: 支持 priority 属性

html_static_path¶

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

A list of paths that contain custom static files (such as style sheets or script files). Relative paths are taken as relative to the configuration directory. They are copied to the output's _static directory after the theme's static files, so a file named default.css will overwrite the theme's default.css.

As these files are not meant to be built, they are automatically excluded from source files.

Note

For security reasons, dotfiles under html_static_path will not be copied. If you would like to copy them intentionally, explicitly add each file to this setting:

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

An alternative approach is to use html_extra_path, which allows copying dotfiles under the directories.

Changed in version 0.4: The paths in html_static_path can now contain subdirectories.

Changed in version 1.0: The entries in html_static_path can now be single files.

Changed in version 1.8: The files under html_static_path are excluded from source files.

html_extra_path¶

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

A list of paths that contain extra files not directly related to the documentation, such as robots.txt or .htaccess. Relative paths are taken as relative to the configuration directory. They are copied to the output directory. They will overwrite any existing file of the same name.

As these files are not meant to be built, they are automatically excluded from source files.

Added in version 1.2.

Changed in version 1.4: The dotfiles in the extra directory will be copied to the output directory. And it refers exclude_patterns on copying extra files and directories, and ignores if path matches to patterns.

html_last_updated_fmt¶

类型:: str
默认值:: None

If set, a 'Last updated on:' timestamp is inserted into the page footer using the given strftime() format. The empty string is equivalent to '%b %d, %Y' (or a locale-dependent equivalent).

html_last_updated_use_utc¶

类型:: bool
默认值:: False

Use GMT/UTC (+00:00) instead of the system's local time zone for the time supplied to html_last_updated_fmt. This is most useful when the format used includes the time.

html_permalinks¶

类型:: bool
默认值:: True

Add link anchors for each heading and description environment.

Added in version 3.5.

html_permalinks_icon¶

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

Text for link anchors for each heading and description environment. HTML entities and Unicode are allowed.

Added in version 3.5.

html_sidebars¶

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

A dictionary defining custom sidebar templates, mapping document names to template names.

The keys can contain glob-style patterns, in which case all matching documents will get the specified sidebars. (A warning is emitted when a more than one glob-style pattern matches for any document.)

Each value must be a list of strings which specifies the complete list of sidebar templates to include. If all or some of the default sidebars are to be included, they must be put into this list as well.

The default sidebars (for documents that don't match any pattern) are defined by theme itself. The builtin themes use these templates by default: 'localtoc.html', 'relations.html', 'sourcelink.html', and 'searchbox.html'.

The bundled first-party sidebar templates that can be rendered are:

localtoc.html -- a fine-grained table of contents of the current document
globaltoc.html -- a coarse-grained table of contents for the whole documentation set, collapsed
relations.html -- two links to the previous and next documents
sourcelink.html -- a link to the source of the current document, if enabled in html_show_sourcelink
searchbox.html -- the "quick search" box

示例

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

This will render the custom template windows-sidebar.html and the quick search box within the sidebar of the given document, and render the default sidebars for all other pages (except that the local TOC is replaced by the global TOC).

Note that this value only has no effect if the chosen theme does not possess a sidebar, like the builtin scrolls and haiku themes.

Added in version 1.0: The ability to use globbing keys and to specify multiple sidebars.

Deprecated since version 1.7: A single string value for html_sidebars will be removed.

Changed in version 2.0: html_sidebars must be a list of strings, and no longer accepts a single string value.

html_additional_pages¶

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

Additional templates that should be rendered to HTML pages, must be a dictionary that maps document names to template names.

示例

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

This will render the template custom-download.html.jinja as the page download.html.

html_domain_indices¶

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

If True, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index.

This value can be a Boolean or a list of index names that should be generated. To find out the index name for a specific index, look at the HTML file name. For example, the Python module index has the name 'py-modindex'.

示例

html_domain_indices = {
    'py-modindex',
}

Added in version 1.0.

Changed in version 7.4: 允许并优先使用集合类型。

html_use_index¶

类型:: bool
默认值:: True

Controls if an index is added to the HTML documents.

Added in version 0.4.

html_split_index¶

类型:: bool
默认值:: False

Generates two versions of the index: once as a single page with all the entries, and once as one page per starting letter.

Added in version 0.4.

html_copy_source¶

类型:: bool
默认值:: True

If True, the reStructuredText sources are included in the HTML build as _sources/docname.

html_show_sourcelink¶

类型:: bool
默认值:: True

If True (and html_copy_source is true as well), links to the reStructuredText sources will be added to the sidebar.

Added in version 0.6.

html_sourcelink_suffix¶

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

The suffix to append to source links (see html_show_sourcelink), unless files they have this suffix already.

Added in version 1.5.

html_use_opensearch¶

类型:: str
默认值:: ''

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

Added in version 0.2.

html_file_suffix¶

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

The file name suffix (file extension) for generated HTML files.

Added in version 0.4.

html_link_suffix¶

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

The suffix for generated links to HTML files. Intended to support more esoteric server setups.

Added in version 0.6.

html_show_copyright¶

类型:: bool
默认值:: True

If True, "© Copyright ..." is shown in the HTML footer, with the value or values from copyright.

Added in version 1.0.

html_show_search_summary¶

类型:: bool
默认值:: True

Show a summary of the search result, i.e., the text around the keyword.

Added in version 4.5.

html_show_sphinx¶

类型:: bool
默认值:: True

Add "Created using Sphinx" to the HTML footer.

Added in version 0.4.

html_output_encoding¶

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

Encoding of HTML output files. This encoding name must both be a valid Python encoding name and a valid HTML charset value.

Added in version 1.0.

html_compact_lists¶

类型:: bool
默认值:: True

If True, a list all whose items consist of a single paragraph and/or a sub-list all whose items etc... (recursive definition) will not use the <p> element for any of its items. This is standard docutils behaviour. Default: True.

Added in version 1.0.

html_secnumber_suffix¶

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

Suffix for section numbers in HTML output. Set to ' ' to suppress the final dot on section numbers.

Added in version 1.0.

html_search_language¶

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

Language to be used for generating the HTML full-text search index. This defaults to the global language selected with language. English ('en') is used as a fall-back option if there is no support for this language.

Support exists for the following languages:

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

Tip

Accelerating build speed

Each language (except Japanese) provides its own stemming algorithm. Sphinx uses a Python implementation by default. If you want to accelerate building the index file, you can use a third-party package (PyStemmer) by running pip install PyStemmer.

Added in version 1.1: Support English (en) and Japanese (ja).

Changed in version 1.3: Added additional languages.

html_search_options¶

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

A dictionary with options for the search language support. The meaning of these options depends on the language selected. Currently, only Japanese and Chinese support options.

Japanese:

type -- the type of the splitter to use.

The other options depend on the splitter used.

'sphinx.search.ja.DefaultSplitter': The TinySegmenter algorithm, used by default.
'sphinx.search.ja.MecabSplitter':: The MeCab binding To use this splitter, the 'mecab' python binding or dynamic link library ('libmecab.so' for Linux, 'libmecab.dll' for Windows) is required.
'sphinx.search.ja.JanomeSplitter':: The Janome binding. To use this splitter, Janome is required.

Deprecated since version 1.6: 'mecab', 'janome' and 'default' is deprecated. To keep compatibility, 'mecab', 'janome' and 'default' are also acceptable.

Options for 'mecab':

dic_enc:: dic_enc option is the encoding for the MeCab algorithm.
dict:: dict option is the dictionary to use for the MeCab algorithm.
lib:: lib option is the library name for finding the MeCab library via ctypes if the Python binding is not installed.

For example:

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

Options for 'janome':

user_dic:: user_dic option is the user dictionary file path for Janome.
user_dic_enc:: user_dic_enc option is the encoding for the user dictionary file specified by user_dic option. Default is 'utf8'.

Chinese:

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

Added in version 1.1.

Changed in version 1.4: Allow any custom splitter in the type setting for Japanese.

html_search_scorer¶

类型:: str
默认值:: ''

The name of a JavaScript file (relative to the configuration directory) that implements a search results scorer. If empty, the default will be used.

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¶

类型:: bool
默认值:: True

Link images that have been resized with a scale option (scale, width, or height) to their original full-resolution image. This will not overwrite any link given by the target option on the the image directive, if present.

Tip

To disable this feature on a per-image basis, add the no-scaled-link class to the image directive:

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

Added in version 1.3.

Changed in version 3.0: Images with the no-scaled-link class will not be linked.

html_math_renderer¶

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

The maths renderer to use for HTML output. The bundled renders are mathjax and imgmath. You must also load the relevant extension in extensions.

Added in version 1.8.

Options for Single HTML output¶

These options influence Single HTML output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

singlehtml_sidebars¶

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

A dictionary defining custom sidebar templates, mapping document names to template names.

This has the same effect as html_sidebars, but the only permitted key is 'index', and all other keys are ignored.

Options for HTML help output¶

These options influence HTML help output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

htmlhelp_basename¶

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

Output file base name for HTML help builder. The default is the project name with spaces removed and doc appended.

htmlhelp_file_suffix¶

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

This is the file name suffix for generated HTML help files.

Added in version 2.0.

htmlhelp_link_suffix¶

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

Suffix for generated links to HTML files.

Added in version 2.0.

Options for Apple Help output¶

Added in version 1.3.

These options influence Apple Help output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

Note

Apple Help output will only work on Mac OS X 10.6 and higher, as it requires the hiutil and codesign command-line tools, neither of which are Open Source.

You can disable the use of these tools using applehelp_disable_external_tools, but the result will not be a valid help book until the indexer is run over the .lproj directories within the bundle.

applehelp_bundle_name¶

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

The basename for the Apple Help Book. The default is the project name with spaces removed.

applehelp_bundle_id¶

类型:: str
默认值:: None

The bundle ID for the help book bundle.

Warning

You must set this value in order to generate Apple Help.

applehelp_bundle_version¶

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

The bundle version, as a string.

applehelp_dev_region¶

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

The development region. Defaults to Apple’s recommended setting, 'en-us'.

applehelp_icon¶

类型:: str
默认值:: None

Path to the help bundle icon file or None for no icon. According to Apple's documentation, this should be a 16-by-16 pixel version of the application's icon with a transparent background, saved as a PNG file.

applehelp_kb_product¶

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

The product tag for use with applehelp_kb_url.

applehelp_kb_url¶

类型:: str
默认值:: None

The URL for your knowledgebase server, e.g. https://example.com/kbsearch.py?p='product'&q='query'&l='lang'. At runtime, Help Viewer will replace 'product' with the contents of applehelp_kb_product, 'query' with the text entered by the user in the search box, and 'lang' with the user's system language.

Set this to to None to disable remote search.

applehelp_remote_url¶

类型:: str
默认值:: None

The URL for remote content. You can place a copy of your Help Book's Resources directory at this location and Help Viewer will attempt to use it to fetch updated content.

For example, if you set it to https://example.com/help/Foo/ and Help Viewer wants a copy of index.html for an English speaking customer, it will look at https://example.com/help/Foo/en.lproj/index.html.

Set this to to None for no remote content.

applehelp_index_anchors¶

类型:: bool
默认值:: False

Tell the help indexer to index anchors in the generated HTML. This can be useful for jumping to a particular topic using the AHLookupAnchor function or the openHelpAnchor:inBook: method in your code. It also allows you to use help:anchor URLs; see the Apple documentation for more information on this topic.

applehelp_min_term_length¶

类型:: str
默认值:: None

Controls the minimum term length for the help indexer. If None, use the default length.

applehelp_stopwords¶

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

Either a language specification (to use the built-in stopwords), or the path to a stopwords plist, or None if you do not want to use stopwords. The default stopwords plist can be found at /usr/share/hiutil/Stopwords.plist and contains, at time of writing, stopwords for the following languages:

German (de)
English (en)
Spanish (es)
French (fr)
Hungarian (hu)
Italian (it)
Swedish (sv)

applehelp_locale¶

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

Specifies the locale to generate help for. This is used to determine the name of the .lproj directory inside the Help Book’s Resources, and is passed to the help indexer.

applehelp_title¶

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

Specifies the help book title.

applehelp_codesign_identity¶

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

Specifies the identity to use for code signing. Use None if code signing is not to be performed.

Defaults to the value of the CODE_SIGN_IDENTITY environment variable, which is set by Xcode for script build phases, or None if that variable is not set.

applehelp_codesign_flags¶

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

A list of additional arguments to pass to codesign when signing the help book.

Defaults to a list based on the value of the OTHER_CODE_SIGN_FLAGS environment variable, which is set by Xcode for script build phases, or the empty list if that variable is not set.

applehelp_codesign_path¶

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

The path to the codesign program.

applehelp_indexer_path¶

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

The path to the hiutil program.

applehelp_disable_external_tools¶

类型:: bool
默认值:: False

Do not run the indexer or the code signing tool, no matter what other settings are specified.

This is mainly useful for testing, or where you want to run the Sphinx build on a non-macOS platform and then complete the final steps on a Mac for some reason.

Options for EPUB output¶

These options influence EPUB output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

Note

The actual value for some of these options is not important, but they are required for the Dublin Core metadata.

epub_basename¶

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

The basename for the EPUB file.

epub_theme¶

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

The HTML theme for the EPUB output. Since the default themes are not optimised for small screen space, using the same theme for HTML and EPUB output is usually not wise. This defaults to 'epub', a theme designed to save visual space.

epub_theme_options¶

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

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. The options understood by the builtin themes are described here.

Added in version 1.2.

epub_title¶

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

The title of the document.

Changed in version 2.0: It defaults to the project option (previously html_title).

epub_description¶

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

The description of the document.

Added in version 1.4.

Changed in version 1.5: Renamed from epub3_description

epub_author¶

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

The author of the document. This is put in the Dublin Core metadata.

epub_contributor¶

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

The name of a person, organisation, etc. that played a secondary role in the creation of the content of an EPUB Publication.

Added in version 1.4.

Changed in version 1.5: Renamed from epub3_contributor

epub_language¶

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

The language of the document. This is put in the Dublin Core metadata.

epub_publisher¶

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

The publisher of the document. This is put in the Dublin Core metadata. You may use any sensible string, e.g. the project homepage.

epub_copyright¶

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

The copyright of the document. See copyright for permitted formats.

epub_identifier¶

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

An identifier for the document. This is put in the Dublin Core metadata. For published documents this is the ISBN number, but you can also use an alternative scheme, e.g. the project homepage.

epub_scheme¶

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

The publication scheme for the epub_identifier. This is put in the Dublin Core metadata. For published books the scheme is 'ISBN'. If you use the project homepage, 'URL' seems reasonable.

epub_uid¶

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

A unique identifier for the document. This is put in the Dublin Core metadata. You may use a XML's Name format string. You can't use hyphen, period, numbers as a first character.

epub_cover¶

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

The cover page information. This is a tuple containing the filenames of the cover image and the html template. The rendered html cover page is inserted as the first item in the spine in content.opf. If the template filename is empty, no html cover page is created. No cover at all is created if the tuple is empty.

Examples:

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]]]
默认值:: []

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 dictionary is used for the <link> tag's attributes. For more information, see 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'),
)

The default value is ().

epub_pre_files¶

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

Additional files that should be inserted before the text generated by Sphinx. It is a list of tuples containing the file name and the title. If the title is empty, no entry is added to toc.ncx.

示例

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

epub_post_files¶

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

Additional files that should be inserted after the text generated by Sphinx. It is a list of tuples containing the file name and the title. This option can be used to add an appendix. If the title is empty, no entry is added to toc.ncx.

示例

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

epub_exclude_files¶

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

A sequence of files that are generated/copied in the build directory but should not be included in the EPUB file.

epub_tocdepth¶

类型:: int
默认值:: 3

The depth of the table of contents in the file toc.ncx. It should be an integer greater than zero.

Tip

A deeply nested table of contents may be difficult to navigate.

epub_tocdup¶

类型:: bool
默认值:: True

This flag determines if a ToC entry is inserted again at the beginning of its nested ToC listing. This allows easier navigation to the top of a chapter, but can be confusing because it mixes entries of different depth in one list.

epub_tocscope¶

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

This setting control the scope of the EPUB table of contents. The setting can have the following values:

'default': Include all ToC entries that are not hidden
'includehidden': Include all ToC entries

Added in version 1.2.

epub_fix_images¶

类型:: bool
默认值:: False

Try and fix image formats that are not supported by some EPUB readers. At the moment palette images with a small colour table are upgraded. This is disabled by default because the automatic conversion may lose information. You need the Python Image Library (Pillow) installed to use this option.

Added in version 1.2.

epub_max_image_width¶

类型:: int
默认值:: 0

This option specifies the maximum width of images. If it is set to a valuevgreater than zero, images with a width larger than the given value are scaled accordingly. If it is zero, no scaling is performed. You need the Python Image Library (Pillow) installed to use this option.

Added in version 1.2.

epub_show_urls¶

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

Control how to display URL addresses. This is very useful for readers that have no other means to display the linked URL. The setting can have the following values:

'inline': Display URLs inline in parentheses.
'footnote': Display URLs in footnotes.
'no': Do not display URLs.

The display of inline URLs can be customised by adding CSS rules for the class link-target.

Added in version 1.2.

epub_use_index¶

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

Add an index to the EPUB document.

Added in version 1.2.

epub_writing_mode¶

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

It specifies writing direction. It can accept 'horizontal' and 'vertical'

`epub_writing_mode`	`'horizontal'`	`'vertical'`
writing-mode	`horizontal-tb`	`vertical-rl`
page progression	left to right	right to left
iBook's Scroll Theme support	scroll-axis is vertical.	scroll-axis is horizontal.

Options for LaTeX output¶

These options influence LaTeX output.

latex_engine¶

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

The LaTeX engine to build the documentation. The setting can have the following values:

'pdflatex' -- PDFLaTeX (default)
'xelatex' -- XeLaTeX (default if language is one of el, zh_CN, or zh_TW)
'lualatex' -- LuaLaTeX
'platex' -- pLaTeX
'uplatex' -- upLaTeX (default if language is 'ja')

Important

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

Note

Sphinx 2.0 adds support for occasional Cyrillic and Greek letters or words in documents using a Latin language and 'pdflatex'. To enable this, the 'fontenc' key of latex_elements must be used appropriately.

Note

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

Changed in version 2.1.0: Use 'xelatex' (and LaTeX package xeCJK) by default for Chinese documents.

Changed in version 2.2.1: Use 'xelatex' by default for Greek documents.

Changed in version 2.3: Add 'uplatex' support.

Changed in version 4.0: Use 'uplatex' by default for Japanese documents.

latex_documents¶

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

This value determines how to group the document tree into LaTeX source files. It must be a list of tuples (startdocname, targetname, title, author, theme, toctree_only), where the items are:

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 master document for your LaTeX build, provide your master_doc here.)
targetname: File name of the LaTeX file in the output directory.
title: LaTeX document title. Can be empty to use the title of the startdoc document. This is inserted as LaTeX markup, so special characters like a backslash or ampersand must be represented by the proper LaTeX commands if they are to be inserted literally.
author: Author for the LaTeX document. The same LaTeX markup caveat as for title applies. Use \\and to separate multiple authors, as in: 'John \\and Sarah' (backslashes must be Python-escaped to reach LaTeX).
theme: LaTeX theme. See latex_theme.
toctree_only: Must be True or False. If True, the startdoc document itself is not included in the output, only the documents referenced by it via ToC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the LaTeX output.

Added in version 0.3: The 6th item toctree_only. Tuples with 5 items are still accepted.

Added in version 1.2: In the past including your own document class required you to prepend the document class name with the string "sphinx". This is not necessary anymore.

latex_logo¶

类型:: str
默认值:: ''

If given, this must be the name of an image file (path relative to the configuration directory) that is the logo of the documentation. It is placed at the top of the title page.

latex_toplevel_sectioning¶

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

This value determines the topmost sectioning unit. The default setting is 'section' if latex_theme is 'howto', and 'chapter' if it is 'manual'. The alternative in both cases is to specify 'part', which means that LaTeX document will use the \part command.

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

Added in version 1.4.

latex_appendices¶

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

A list of document names to append as an appendix to all manuals. This is ignored if latex_theme is set to 'howto'.

latex_domain_indices¶

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

If True, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index.

This value can be a Boolean or a list of index names that should be generated. To find out the index name for a specific index, look at the HTML file name. For example, the Python module index has the name 'py-modindex'.

示例

latex_domain_indices = {
    'py-modindex',
}

Added in version 1.0.

Changed in version 7.4: 允许并优先使用集合类型。

latex_show_pagerefs¶

类型:: bool
默认值:: False

Add page references after internal references. This is very useful for printed copies of the manual.

Added in version 1.0.

latex_show_urls¶

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

Control how to display URL addresses. This is very useful for printed copies of the manual. The setting can have the following values:

'no': Do not display URLs
'footnote': Display URLs in footnotes
'inline': Display URLs inline in parentheses

Added in version 1.0.

Changed in version 1.1: This value is now a string; previously it was a boolean value, and a true value selected the 'inline' display. For backwards compatibility, True is still accepted.

latex_use_latex_multicolumn¶

类型:: bool
默认值:: False

Use standard LaTeX's \multicolumn for merged cells in tables.

False: Sphinx's own macros are used for merged cells from grid tables. They allow general contents (literal blocks, lists, blockquotes, ...) but may have problems if the tabularcolumns directive was used to inject LaTeX mark-up of the type >{..}, <{..}, @{..} as column specification.
True: Use LaTeX's standard \multicolumn; this is incompatible with literal blocks in horizontally merged cells, and also with multiple paragraphs in such cells if the table is rendered using tabulary.

Added in version 1.6.

latex_table_style¶

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

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 customise them is via dedicated keys of The sphinxsetup configuration setting.

Important

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 the latex table color configuration keys instead.

To customise the styles for a table, use the :class: option if the table is defined using a directive, or otherwise insert a rst-class directive before the table (cf. Tables).

Currently recognised 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 The sphinxsetup configuration setting section.

Note

It is hard-coded in LaTeX that a single cell will obey the row colour even if there is a column colour set via \columncolor from a column specification (see tabularcolumns). Sphinx provides \sphinxnorowcolor which can be used in a table column specification like this:
```
>{\columncolor{blue}\sphinxnorowcolor}
```
Sphinx 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 Deprecated APIs section of this document in PDF format.

Hint

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.

Hint

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

Added in version 5.3.0.

Changed in version 6.0.0: Modify default from [] to ['booktabs', 'colorrows'].

latex_use_xindy¶

类型:: bool
默认值:: True if latex_engine in {'xelatex', 'lualatex'} else False

Use Xindy to prepare the index of general terms. By default, the LaTeX builder uses makeindex for preparing the index of general terms . Using Xindy means that words with UTF-8 characters will be ordered correctly for the language.

This option is ignored if latex_engine is 'platex' (Japanese documents; mendex replaces makeindex then).
The default is True for 'xelatex' or 'lualatex' as makeindex creates .ind files containing invalid bytes for the UTF-8 encoding if any indexed term starts with a non-ASCII character. With 'lualatex' this then breaks the PDF build.
The default is False for 'pdflatex', but True is recommended for non-English documents as soon as some indexed terms use non-ASCII characters from the language script. Attempting to index a term whose first character is non-ASCII will break the build, if latex_use_xindy is left to its default False.

Sphinx adds some dedicated support to the xindy base distribution for using 'pdflatex' engine with Cyrillic scripts. With both 'pdflatex' and Unicode engines, Cyrillic documents handle the indexing of Latin names correctly, even those having diacritics.

Added in version 1.8.

latex_elements¶

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

Added in version 0.5.

See the full documentation for latex_elements.

latex_docclass¶

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

A dictionary mapping 'howto' and 'manual' to names of real document classes that will be used as the base for the two Sphinx classes. Default is to use 'article' for 'howto' and 'report' for 'manual'.

Added in version 1.0.

Changed in version 1.5: In Japanese documentation (language is 'ja'), by default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.

latex_additional_files¶

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

A list of file names, relative to the configuration directory, to copy to the build directory when building LaTeX output. This is useful to copy files that Sphinx doesn't copy automatically, or to overwrite Sphinx LaTeX support files with custom versions. Image files that are referenced in source files (e.g. via .. image::) are copied automatically and should not be listed there.

Attention

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

Added in version 0.6.

Changed in version 1.2: This overrides the files provided from Sphinx such as sphinx.sty.

latex_theme¶

类型:: str
默认值:: 'manual'

The "theme" that the LaTeX output should use. It is a collection of settings for LaTeX output (e.g. document class, top level sectioning unit and so on).

The bundled first-party LaTeX themes are manual and howto:

manual: A LaTeX theme for writing a manual. It imports the report document class (Japanese documents use jsbook).
howto: A LaTeX theme for writing an article. It imports the article document class (Japanese documents use jreport). latex_appendices is only available for this theme.

Added in version 3.0.

latex_theme_options¶

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

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific.

Added in version 3.1.

latex_theme_path¶

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

A list of paths that contain custom LaTeX themes as subdirectories. Relative paths are taken as relative to the configuration directory.

Added in version 3.0.

Options for text output¶

These options influence text output.

text_add_secnumbers¶

类型:: bool
默认值:: True

Include section numbers in text output.

Added in version 1.7.

text_newlines¶

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

Determines which end-of-line character(s) are used in text output.

'unix': Use Unix-style line endings (\n).
'windows': Use Windows-style line endings (\r\n).
'native': Use the line ending style of the platform the documentation is built on.

Added in version 1.1.

text_secnumber_suffix¶

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

Suffix for section numbers in text output. Set to ' ' to suppress the final dot on section numbers.

Added in version 1.7.

text_sectionchars¶

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

A string of 7 characters that should be used for underlining sections. The first character is used for first-level headings, the second for second-level headings and so on.

Added in version 1.1.

Options for manual page output¶

These options influence manual page output.

man_pages¶

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

This value determines how to group the document tree into manual pages. It must be a list of tuples (startdocname, name, description, authors, section), where the items are:

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 page. (If you want to use the default master document for your manual pages build, provide your master_doc here.)
name: Name of the manual page. This should be a short string without spaces or special characters. It is used to determine the file name as well as the name of the manual page (in the NAME section).
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: A list of strings with authors, or a single string. Can be an empty string or list if you do not want to automatically generate an AUTHORS section in the manual page.
section: The manual page section. Used for the output file name as well as in the manual page header.

Added in version 1.0.

man_show_urls¶

类型:: bool
默认值:: False

Add URL addresses after links.

Added in version 1.1.

man_make_section_directory¶

类型:: bool
默认值:: True

Make a section directory on build man page.

Added in version 3.3.

Changed in version 4.0: The default is now False (previously True).

Changed in version 4.0.2: Revert the change in the default.

Options for Texinfo output¶

These options influence Texinfo output.

texinfo_documents¶

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

This value determines how to group the document tree into Texinfo source files. It must be a list of tuples (startdocname, targetname, title, author, dir_entry, description, category, toctree_only), where the items are:

startdocname: String that specifies the document name of 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 master_doc here.)
targetname: File name (no extension) of the Texinfo file in the output directory.
title: Texinfo document title. Can be empty to use the title of the startdoc document. Inserted as Texinfo markup, so special characters like @ and {} will need to be escaped to be inserted literally.
author: Author for the Texinfo document. Inserted as Texinfo markup. Use @* to separate multiple authors, as in: 'John@*Sarah'.
dir_entry: The name that will appear in the top-level DIR menu file.
description: Descriptive text to appear in the top-level DIR menu file.
category: Specifies the section which this entry will appear in the top-level DIR menu file.
toctree_only: Must be True or False. If True, the startdoc document itself is not included in the output, only the documents referenced by it via ToC trees. With this option, you can put extra stuff in the master document that shows up in the HTML, but not the Texinfo output.

Added in version 1.1.

texinfo_appendices¶

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

A list of document names to append as an appendix to all manuals.

Added in version 1.1.

texinfo_cross_references¶

类型:: bool
默认值:: True

Generate inline references in a document. Disabling inline references can make an info file more readable with a stand-alone reader (info).

Added in version 4.4.

texinfo_domain_indices¶

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

If True, generate domain-specific indices in addition to the general index. For e.g. the Python domain, this is the global module index.

This value can be a Boolean or a list of index names that should be generated. To find out the index name for a specific index, look at the HTML file name. For example, the Python module index has the name 'py-modindex'.

示例

texinfo_domain_indices = {
    'py-modindex',
}

Added in version 1.1.

Changed in version 7.4: 允许并优先使用集合类型。

texinfo_elements¶

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

A dictionary that contains Texinfo snippets that override those that Sphinx usually puts into the generated .texi files.

Keys that you may want to override include:

'paragraphindent'
Number of spaces to indent the first line of each paragraph, default 2. Specify 0 for no indentation.

'exampleindent'
Number of spaces to indent the lines for examples or literal blocks, default 4. Specify 0 for no indentation.

'preamble'
Texinfo markup inserted near the beginning of the file.

'copying'
Texinfo markup inserted within the @copying block and displayed after the title. The default value consists of a simple title page identifying the project.
Keys that are set by other options and therefore should not be overridden are 'author', 'body', 'date', 'direntry' 'filename', 'project', 'release', and 'title'.

Added in version 1.1.

texinfo_no_detailmenu¶

类型:: bool
默认值:: False

Do not generate a @detailmenu in the "Top" node's menu containing entries for each sub-node in the document.

Added in version 1.2.

texinfo_show_urls¶

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

Control how to display URL addresses. The setting can have the following values:

'footnote': Display URLs in footnotes.
'no': Do not display URLs.
'inline': Display URLs inline in parentheses.

Added in version 1.1.

Options for QtHelp output¶

These options influence qthelp output. This builder derives from the HTML builder, so the HTML options also apply where appropriate.

qthelp_basename¶

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

The basename for the qthelp file.

qthelp_namespace¶

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

The namespace for the qthelp file.

qthelp_theme¶

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

The HTML theme for the qthelp output.

qthelp_theme_options¶

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

A dictionary of options that influence the look and feel of the selected theme. These are theme-specific. The options understood by the builtin themes are described here.

Options for XML output¶

xml_pretty¶

类型:: bool
默认值:: True

Pretty-print the XML.

Added in version 1.2.

Options for the linkcheck builder¶

Filtering¶

These options control which links the linkcheck builder checks, and which failures and redirects it ignores.

linkcheck_allowed_redirects¶

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

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.

The linkcheck builder will emit a warning when it finds redirected links that don't meet the rules above. It can be useful to detect unexpected redirects when using 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

Check the validity of #anchors in links. Since this requires downloading the whole document, it is considerably slower when enabled.

Added in version 1.2.

linkcheck_anchors_ignore¶

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

A list of regular expressions that match anchors that the linkcheck builder should skip when checking the validity of anchors in links. For example, this allows skipping anchors added by a website's JavaScript.

Tip

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

Note

If you want to ignore anchors of a specific page or of pages that match a specific pattern (but still check occurrences of the same page(s) that don't have anchors), use linkcheck_ignore instead, for example as follows:

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

Added in version 1.5.

linkcheck_anchors_ignore_for_url¶

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

A list or tuple of regular expressions matching URLs for which the linkcheck builder 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.

Added in version 7.1.

linkcheck_exclude_documents¶

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

A list of regular expressions that match documents in which the linkcheck builder 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 subdirectory named 'legacy'
linkcheck_exclude_documents = [r'.*/legacy/.*']

Added in version 4.4.

linkcheck_ignore¶

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

A list of regular expressions that match URIs that should not be checked when doing a linkcheck build.

示例

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

Added in version 1.1.

HTTP Requests¶

These options control how the linkcheck builder makes HTTP requests, including how it handles redirects and authentication, and the number of workers to use.

linkcheck_auth¶

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

Pass authentication information when doing a linkcheck build.

A list of (regex_pattern, auth_info) tuples where the items are:

regex_pattern: A regular expression that matches a 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).

The linkcheck builder will use the first matching auth_info value it can find in the linkcheck_auth list, so values earlier in the list have higher priority.

示例

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

Added in version 2.3.

linkcheck_allow_unauthorized¶

类型:: bool
默认值:: False

When a webserver responds with an HTTP 401 (unauthorised) response, the current default behaviour of the linkcheck builder is to treat the link as "broken". To change that behaviour, set this option to True.

Changed in version 8.0: The default value for this option changed to False, meaning HTTP 401 responses to checked hyperlinks are treated as "broken" by default.

Added in version 7.3.

linkcheck_rate_limit_timeout¶

类型:: int
默认值:: 300

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 behaviour when servers indicate that requests are rate-limited, by setting the maximum duration (in seconds) that the builder will wait for between each attempt before recording a failure.

The linkcheck builder always respects a server's direction of when to retry (using the Retry-After header). 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 (in seconds). Custom timeouts should be given as a number of seconds.

Added in version 3.4.

linkcheck_report_timeouts_as_broken¶

类型:: bool
默认值:: False

If linkcheck_timeout expires while waiting for a response from a hyperlink, the linkcheck builder will report the link as a timeout by default. To report timeouts as broken instead, you can set linkcheck_report_timeouts_as_broken to True.

Changed in version 8.0: The default value for this option changed to False, meaning timeouts that occur while checking hyperlinks will be reported using the new 'timeout' status code.

Added in version 7.3.

linkcheck_request_headers¶

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

A dictionary that maps URL (without paths) to HTTP request headers.

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.

The value is a dictionary that maps header name to its value.

示例

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

The number of times the linkcheck builder will attempt to check a URL before declaring it broken.

Added in version 1.4.

linkcheck_timeout¶

类型:: int
默认值:: 30

The duration, in seconds, that the linkcheck builder will wait for a response after each hyperlink request.

Added in version 1.1.

linkcheck_workers¶

类型:: int
默认值:: 5

The number of worker threads to use when checking links.

Added in version 1.1.

Domain options¶

Options for the C domain¶

c_extra_keywords¶

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

A list of identifiers to be recognised as keywords by the C parser.

Added in version 4.0.3.

Changed in version 7.4: c_extra_keywords can now be a set.

c_id_attributes¶

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

A sequence of strings that the parser should additionally accept as attributes. For example, this can be used when #define has been used for attributes, for portability.

示例

c_id_attributes = [
    'my_id_attribute',
]

Added in version 3.0.

Changed in version 7.4: c_id_attributes can now be a tuple.

c_maximum_signature_line_length¶

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

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, there is no maximum length and the entire signature will be displayed on a single logical line.

This is a domain-specific setting, overriding maximum_signature_line_length.

Added in version 7.1.

c_paren_attributes¶

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

A sequence of strings that the parser should additionally accept as attributes with one argument. That is, if my_align_as is in the list, then my_align_as(X) is parsed as an attribute for all strings X that have balanced braces ((), [], and {}). For example, this can be used when #define has been used for attributes, for portability.

示例

c_paren_attributes = [
    'my_align_as',
]

Added in version 3.0.

Changed in version 7.4: c_paren_attributes can now be a tuple.

Options for the C++ domain¶

cpp_id_attributes¶

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

A sequence of strings that the parser should additionally accept as attributes. For example, this can be used when #define has been used for attributes, for portability.

示例

cpp_id_attributes = [
    'my_id_attribute',
]

Added in version 1.5.

Changed in version 7.4: cpp_id_attributes can now be a tuple.

cpp_index_common_prefix¶

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

A list of prefixes that will be ignored when sorting C++ objects in the global index.

示例

cpp_index_common_prefix = [
    'awesome_lib::',
]

Added in version 1.5.

cpp_maximum_signature_line_length¶

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

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, there is no maximum length and the entire signature will be displayed on a single logical line.

This is a domain-specific setting, overriding maximum_signature_line_length.

Added in version 7.1.

cpp_paren_attributes¶

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

A sequence of strings that the parser should additionally accept as attributes with one argument. That is, if my_align_as is in the list, then my_align_as(X) is parsed as an attribute for all strings X that have balanced braces ((), [], and {}). For example, this can be used when #define has been used for attributes, for portability.

示例

cpp_paren_attributes = [
    'my_align_as',
]

Added in version 1.5.

Changed in version 7.4: cpp_paren_attributes can now be a tuple.

Options for the Javascript domain¶

javascript_maximum_signature_line_length¶

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

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, there is no maximum length and the entire signature will be displayed on a single logical line.

This is a domain-specific setting, overriding maximum_signature_line_length.

Added in version 7.1.

Options for the Python domain¶

add_module_names¶

类型:: bool
默认值:: True

A boolean that decides whether module names are prepended to all object names (for object types where a "module" of some kind is defined), e.g. for py:function directives.

modindex_common_prefix¶

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

A list of prefixes that are ignored for sorting the Python module index (e.g., if this is set to ['foo.'], then foo.bar is shown under B, not F). This can be handy if you document a project that consists of a single package.

Caution

Works only for the HTML builder currently.

Added in version 0.6.

python_display_short_literal_types¶

类型:: bool
默认值:: False

This value controls how Literal types are displayed.

Examples¶

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_maximum_signature_line_length¶

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

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, there is no maximum length and the entire signature will be displayed on a single 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.

python_use_unqualified_type_names¶

类型:: bool
默认值:: False

Suppress the module name of the python reference if it can be resolved.

Added in version 4.0.

Caution

This feature is experimental.

trim_doctest_flags¶

类型:: bool
默认值:: True

Remove doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers for all code blocks showing interactive Python sessions (i.e. doctests). See the extension doctest for more possibilities of including doctests.

Added in version 1.0.

Changed in version 1.1: Now also removes <BLANKLINE>.

Extension options¶

Extensions frequently have their own configuration options. Those for Sphinx's first-party extensions are documented in each extension's page.

Example configuration file¶

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