配置

这个 configuration directory 必须包含名为的文件 conf.py 。这个文件(包含Python代码)称为“构建配置文件”,包含(几乎)定制Sphinx输入和输出行为所需的所有配置。

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

配置文件在构建时以Python代码的形式执行(使用 importlib.import_module() 并将当前目录设置为其包含的目录),因此可以执行任意复杂的代码。然后,Sphinx从文件的名称空间中读取简单名称作为其配置。

需要注意的重要事项:

  • 如果未另行记录,则值必须为字符串,其缺省值为空字符串。

  • 术语“完全限定名称”是指在模块内命名可导入的Python对象的字符串;例如,FQN "sphinx.builders.Builder" 指的是 Builder 中的类 sphinx.builders 模块。

  • 请记住,文档名称使用 / 作为路径分隔符,并且不包含文件扩展名。

  • 自.以来 conf.py 被读取为一个Python文件时,通常的规则适用于编码和Unicode支持。

  • 配置名称空间的内容是Pickleed的(以便Sphinx可以在配置更改时发现),因此它可能不包含不可拾取的值--使用以下命令从名称空间中删除它们 del 如果合适的话。模块会自动删除,因此您不需要 del 您的进口后使用。

  • 有一个特殊的对象名为 tags 在配置文件中可用。它可用于查询和更改标签(请参见 包括基于标签的内容 )。使用 tags.has('tag') 要查询, tags.add('tag')tags.remove('tag') 去改变。仅通过 -t 命令行选项或VIA tags.add('tag') 可以使用以下命令进行查询 tags.has('tag') 。请注意,当前构建器标记在中不可用 conf.py ,因为它是创建的 after 构建器被初始化。

项目信息

project

记录的项目的名称。

author

该文件的作者姓名(S)。缺省值为 'unknown'

样式中的版权声明 '2008, Author Name'

在 7.1 版本发生变更: 该值现在可以是上述形式的版权声明序列,这些声明将分别显示在各自的行中。

的别名 copyright

在 3.5 版本加入.

version

主要项目版本,用作 |version| 。例如,对于Python文档,这可能类似于 2.6

release

完整的项目版本,用作 |release| 并且例如在所述HTML模板中。例如,对于Python文档,这可能类似于 2.6.0rc1

如果您不需要之间提供的分隔 versionrelease ,只需将它们设置为相同的值。

常规配置

extensions

的模块名称的字符串列表 extensions 。这些可以是Sphinx(名为 sphinx.ext.* )或定制的。

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

import sys, os

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

extensions = ['extname']

这样,您就可以加载一个名为 extname 从子目录中 sphinxext

配置文件本身可以是一个扩展名;为此,您只需提供 setup() 在其中发挥作用。

source_suffix

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

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

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

该值也可以是文件扩展名列表:那么Sphinx将认为它们都映射到 'restructuredtext' 文件类型。

缺省值为 {'.rst': 'restructuredtext'}

备注

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

在 1.3 版本发生变更: 现在可以是扩展名列表。

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

source_encoding

所有REST源文件的编码。建议的编码和默认值为 'utf-8-sig'

在 0.5 版本加入: 以前,Sphinx只接受UTF-8编码源。

source_parsers

如果给定的话,一个针对不同源代码的解析器类词典就足够了。键是后缀,值可以是类,也可以是给出解析器类的完全限定名称的字符串。解析器类可以是 docutils.parsers.Parsersphinx.parsers.Parser 。带有不在词典中的后缀的文件将使用默认的reStrufredText解析器进行解析。

例如::

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

备注

参考 降价 有关在Sphinx中使用Markdown的更多信息。

在 1.3 版本加入.

自 1.8 版本弃用: 现在Sphinx提供了一个API Sphinx.add_source_parser() 若要注册源解析器,请执行以下操作。请用它来代替。

master_doc

相同于 root_doc

在 4.0 版本发生变更: 已重命名 master_docroot_doc

root_doc

根文档的文档名,即包含根的文档 toctree 指令。缺省值为 'index'

在 2.0 版本发生变更: 默认设置更改为 'index' 从… 'contents'

在 4.0 版本发生变更: 已重命名 root_doc 从… master_doc

exclude_patterns

GLOB样式模式的列表 [1] 在查找源文件时应将其排除。它们与相对于源目录的源文件名匹配,在所有平台上都使用斜杠作为目录分隔符。

示例模式:

  • 'library/xml.rst' --忽略 library/xml.rst 文件

  • 'library/xml' --忽略 library/xml 目录

  • 'library/xml*' -- ignores all files and directories starting with library/xml

  • '**/.svn' --忽略所有 .svn 目录

exclude_patterns 中查找静态文件时,也会参考 html_static_pathhtml_extra_path

在 1.0 版本加入.

include_patterns

GLOB样式模式的列表 [1] 用于查找源文件的。它们与相对于源目录的源文件名匹配,在所有平台上都使用斜杠作为目录分隔符。缺省值为 ** 这意味着所有文件都是从源目录递归包含的。

示例模式:

  • '**' --源目录和子目录中的所有文件,递归

  • 'library/xml' --只有 library/xml 目录

  • 'library/xml*' -- all files and directories starting with library/xml

  • '**/doc' --全部 doc 目录(如果文档与源文件位于同一位置,这可能很有用)

在 5.1 版本加入.

templates_path

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

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

template_bridge

具有可调用(或简单地说是类)的完全限定名称的字符串,该可调用返回 TemplateBridge 。然后,该实例用于呈现HTML文档,并可能呈现其他构建器(当前为Change构建器)的输出。(请注意,如果要使用HTML主题,模板桥必须具有主题感知能力。)

rst_epilog

将包括在读取的每个源文件的末尾的reStrutiredText字符串。这是一个可能的位置,可以添加应该在每个文件(另一个是 rst_prolog )。示例::

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

在 0.6 版本加入.

rst_prolog

将包括在所读取的每个源文件的开头的reStrutiredText的字符串。这是一个可能的位置,可以添加应该在每个文件(另一个是 rst_epilog )。示例::

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

在 1.0 版本加入.

primary_domain

默认设置的名称 domain 。也可以 None 要禁用默认域,请执行以下操作。缺省值为 'py' 。其他域中的那些对象(无论域名是显式给定的,还是由 default-domain 指令)将在命名时显式地将域名放在前面(例如,当默认域为C时,将命名为“Python Function”,而不仅仅是“Function”)。

在 1.0 版本加入.

default_role

用作默认角色的REST角色的名称(内置或Sphinx扩展),即用于标记的文本 `like this 。可以将其设置为 `'py:obj'`` 使 `filter 对Python函数“Filter”的交叉引用。缺省值为 ``None` ,它不会重新分配默认角色。

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

在 0.4 版本加入.

keep_warnings

如果为真,则在构建的文档中将警告保留为“系统消息”段落。无论此设置如何,警告都将始终写入标准错误流 sphinx-build 就是奔跑。

缺省值为 False ,0.5之前的行为是始终保留它们。

在 0.5 版本加入.

suppress_warnings

禁止显示任意警告消息的警告类型列表。

Sphinx支持以下警告类型:

  • app.add_node

  • app.add_directive

  • app.add_role

  • app.add_generic_role

  • app.add_source_parser

  • autosectionlabel.*

  • 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

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

现在,应该考虑这个选项 experimental

在 1.4 版本加入.

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

在 1.5.1 版本发生变更: 增列 epub.unknown_project_files

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

在 2.1 版本发生变更: 增列 autosectionlabel.*

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

在 4.3 版本发生变更: 增列 toc.excludedtoc.not_readable

在 4.5 版本加入:

增列 i18n.inconsistent_references

在 7.1 版本加入: 增列 index 警告类型。

needs_sphinx

如果设置为 major.minor 版本字符串,如 '1.1' ,狮身人面像会将其与其版本进行比较,如果太旧则拒绝建造。默认设置为无要求。

在 1.0 版本加入.

在 1.4 版本发生变更: 还接受微版本串

needs_extensions

该值可以是指定中扩展模块的版本要求的字典 extensions ,例如 needs_extensions = {'sphinxcontrib.something': '1.5'} 。版本字符串的格式应为 major.minor 。不必为所有扩展指定要求,只需为要检查的扩展指定要求。

这要求扩展模块将其版本指定为Sphinx(请参见 Sphinx扩展API 关于如何做到这一点)。

在 1.3 版本加入.

manpages_url

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

  • page -手册页面 (man )

  • section -手册部分 (1 )

  • path -指定的原始手册页面和章节 (man(1) )

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

备注

这项功能目前只影响到了HTML作者,但将来可能会扩大。

在 1.7 版本加入.

nitpicky

如果是真的,狮身人面像将警告 all 找不到目标的引用。缺省值为 False 。属性临时激活此模式。 -n 命令行开关。

在 1.0 版本加入.

nitpick_ignore

一组或一列 (type, target) 在“挑剔模式”下生成警告时应忽略的元组(默认为空)。请注意 type 应包括域名(如果存在)。示例条目如下 ('py:func', 'int')('envvar', 'LD_LIBRARY_PATH')

在 1.1 版本加入.

在 6.2 版本发生变更: 将允许的容器类型更改为集、列表或元组

nitpick_ignore_regex

的扩展版本 nitpick_ignore ,它转而解释 typetarget 字符串作为正则表达式。请注意,正则表达式必须匹配整个字符串(就好像 ^$ 插入了标记)。

例如, (r'py:.*', r'foo.*bar\.B.*') 将忽略所有以 'foo' 并拥有 'bar.B' 在它们中,例如 ('py:const', 'foo_package.bar.BAZ_VALUE')('py:class', 'food.bar.Barman')

在 4.1 版本加入.

在 6.2 版本发生变更: 将允许的容器类型更改为集、列表或元组

numfig

如果为True,则如果图形、表格和代码块带有标题,则会自动对它们进行编号。这个 numref 角色已启用。到目前为止,只有HTML和LaTeX构建者遵守了这一点。缺省值为 False

备注

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

在 1.3 版本加入.

numfig_format

词典映射 'figure''table''code-block''section' 转换为用于设置图形数字格式的字符串。作为一个特殊的角色, %s 将被替换为数字编号。

默认情况下,使用 'Fig. %s''figure''Table %s''table''Listing %s''code-block''Section %s''section'

在 1.3 版本加入.

numfig_secnum_depth
  • 如果设置为 0 、图形、表格和代码块从开始连续编号 1

  • 如果 1 (default) numbers will be x.1, x.2, ... with x the section number (top level sectioning; no x. 如果没有章节)。这仅适用于已通过 :numbered: 选项中的 toctree 指令。

  • 2 意味着数字将会是 x.y.1x.y.2 ..如果位于子部分中(但仍 x.1x.2 ..如果位于横断面的正下方,并且 12 ..如果不是在任何顶级部分。)

  • 等等.。

在 1.3 版本加入.

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

smartquotes

如果为真,则 Docutils Smart Quotes transform, originally based on SmartyPants (仅限于英文),目前适用于多种语言,将用于将引号和破折号转换为排版正确的实体。默认: True

在 1.6.6 版本加入: 它取代了不受欢迎的 html_use_smartypants 。默认情况下,它适用于除 mantext (见 smartquotes_excludes 。)

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

smartquotes_action

此字符串自定义智能引号转换。请参阅该文件 smartquotes.pyDocutils repository 了解更多细节。默认设置 'qDe' 培养师范生 q u引用字符 "' ,嗯-和恩- D 灰烬 ----- ,以及 e llipses ...

在 1.6.6 版本加入.

smartquotes_excludes

这是一个 dict 其默认为::

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

每个条目都给出了一个充分条件来忽略 smartquotes 设置并停用智能报价转换。接受的密钥如下所示 'builders''languages' 。这些值是列表。

备注

目前,如果调用 make 对于多个目标,第一个目标名称是唯一针对 'builders' 进入,它将为所有人做出决定。此外,还有一个 make text 以下是 make html 需要在以下表格中发出 make text O="-E" 强制重新解析源文件,因为缓存的文件已经转换。另一方面,直接使用 sphinx-build 因为它在每个构建器位置缓存(在其默认使用情况下)解析的源文件。

提示

另一种有效地停用(或定制)给定构建器的智能报价的方法,例如 latex ,就是使用 make 这条路:

make latex O="-D smartquotes_action="

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

在 1.6.6 版本加入.

user_agent

斯芬克斯的用户代理。它用于HTTP访问上的标头(例如Linkcheck、intersphinx等)。缺省值为 "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z"

在 2.3 版本加入.

tls_verify

如果为真,Sphinx将验证服务器证书。缺省值为 True

在 1.5 版本加入.

tls_cacerts

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

在 1.5 版本加入.

小技巧

狮身人面像使用 requests 作为内部的HTTP库。因此,Sphinx引用指向的目录上的认证文件 REQUESTS_CA_BUNDLE 环境变量IF tls_cacerts 未设置。

today
today_fmt

这些值确定如何设置当前日期的格式,该日期用作 |today|

  • 如果您设置为 today 设置为非空值,则使用它。

  • 否则,当前时间将使用 time.strftime() 和中给出的格式 today_fmt

默认设置为现在 today 以及一个 today_fmt'%b %d, %Y' (或者,如果通过启用翻译 language 所选区域设置的等效格式)。

highlight_language

用来突出显示源代码的默认语言。缺省值为 'default' 。它类似于 'python3' ;它主要是一个超集 'python' 但它会退回到 'none' 如果失败则不会发出任何警告。 'python3' 如果失败,其他语言将发出警告。

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

在 0.5 版本加入.

在 1.4 版本发生变更: 默认设置为现在 'default' 。如果您更喜欢仅高亮显示Python2,则可以将其设置回 'python'

highlight_options

将语言名称映射到Pygments的词法分析器模块选项的词典。这些选项是特定于词法分析器的;有关每个选项的理解,请参阅 Pygments documentation

示例::

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

还允许使用单个选项词典。则它被识别为对由 highlight_language **

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

在 1.3 版本加入.

在 3.5 版本发生变更: 允许为多种语言配置突出显示选项

pygments_style

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

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

maximum_signature_line_length

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

什么时候 None (默认),没有最大长度,整个签名将显示在单个逻辑行上。

“逻辑行”类似于硬行中断-构建者或主题可以选择“软换行”单个逻辑行,并且此设置不会影响该行为。

域可以提供选项来抑制单个对象指令上的任何硬包装,例如在C、C++和Python域(例如 py:function:single-line-parameter-list )。

在 7.1 版本加入.

add_function_parentheses

决定是否将括号附加到函数和方法角色文本的布尔值(例如 :func:`input )表示该名称是可调用的。缺省值为 ``True`

add_module_names

一个布尔值,它决定是否将模块名称放在所有名称前面 object 名称(对于定义了某种“模块”的对象类型),例如for py:function 指令。缺省值为 True

toc_object_entries

创建域对象(例如,函数、类、属性等)的目录条目。缺省值为 True

toc_object_entries_show_parents

一个字符串,它确定域对象(例如函数、类、属性等)显示在它们的目录条目中。

使用 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. 父母的级别。这是默认设置。

使用 hide 若要仅显示元素的名称,而不显示任何父元素(即 method() )。

使用 all 要显示对象的完全限定名称(即 module.Class.method() ),显示所有父项。

在 5.2 版本加入.

show_authors

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

modindex_common_prefix

对Python模块索引进行排序时忽略的前缀列表(例如,如果设置为 ['foo.'] ,那么 foo.bar 显示在下面 B ,不是 F )。如果您记录由单个包组成的项目,这可能会很方便。目前仅适用于HTML构建器。缺省值为 []

在 0.6 版本加入.

trim_footnote_reference_space

删除脚注引用之前的空格,这些空格是REST解析器识别脚注所必需的,但在输出中看起来不太好。

在 0.6 版本加入.

trim_doctest_flags

如果为True,则doctest标志(注释如下 # doctest: FLAG, ... )和行的末尾 <BLANKLINE> 所有显示交互式Python会话的代码块的标记都被移除(即doctest)。缺省值为 True 。请参阅扩展名 doctest 以获取更多包括DOC测试的可能性。

在 1.0 版本加入.

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

strip_signature_backslash

缺省值为 False 。如果启用反斜杠剥离,则每次出现 \\ 在域中,指令将更改为 \ ,即使在字符串文字中也是如此。这是3.0版之前的行为,并将此变量设置为 True 将恢复这种行为。

在 3.0 版本加入.

option_emphasise_placeholders

缺省值为 False 。启用时,强调占位符 option 指令。要显示原义大括号,请使用反斜杠转义 (\{ )。例如, option_emphasise_placeholders=True.. option:: -foption={TYPE} 将呈现为 TYPE 被强调了。

在 5.1 版本加入.

国际化的选择

这些选项会影响斯芬克斯的 Native Language Support 。请参阅上的文档 国际化 了解更多细节。

language

文档编写时所用语言的代码。Sphinx自动生成的任何文本都将使用该语言。此外,Sphinx会尝试用从以下地址获得的翻译集替换文档中的单个段落 locale_dirs 。狮身人面像将搜索特定语言的数字,命名为 figure_language_filename (例如,德文版 myfigure.png 将会是 myfigure.de.png 默认设置),并用它们替换原始图形。在LaTeX构建器中,将选择合适的语言作为 Babel 包裹。缺省值为 'en'

在 0.5 版本加入.

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

在 5.0 版本发生变更.

Sphinx目前支持的语言包括:

  • ar --阿拉伯语

  • bg 保加利亚人

  • bn --孟加拉语

  • ca --加泰罗尼亚语

  • cak --卡奇克尔

  • cs --捷克

  • cy --威尔士

  • da --丹麦

  • de --德语

  • el --希腊

  • en --英语(默认)

  • eo --世界语

  • es --西班牙语

  • et --爱沙尼亚

  • eu --巴斯克

  • fa --伊朗

  • fi --芬兰

  • fr --法语

  • he --希伯来语

  • hi --印地语

  • hi_IN --印地语(印度)

  • hr 克罗地亚人

  • hu --匈牙利

  • id --印度尼西亚

  • it --意大利

  • ja --日语

  • ko --韩语

  • lt 立陶宛人

  • lv --拉脱维亚

  • mk --马其顿

  • nb_NO --挪威博克马尔

  • ne --尼泊尔

  • nl --荷兰

  • pl --波兰语

  • pt -葡萄牙语

  • pt_BR --巴西葡萄牙语

  • pt_PT --欧洲葡萄牙语

  • ro 罗马尼亚人

  • ru --俄语

  • si -僧伽罗语

  • sk --斯洛伐克

  • sl --斯洛文尼亚

  • sq --阿尔巴尼亚语

  • sr --塞尔维亚语

  • sr@latin --塞尔维亚语(拉丁语)

  • sr_RS --塞尔维亚语(西里尔文)

  • sv --瑞典人

  • ta --泰米尔

  • te --泰卢固语

  • tr --土耳其语

  • uk_UA --乌克兰人

  • ur --乌尔都语

  • vi --越南语

  • zh_CN --简体中文

  • zh_TW --繁体中文

locale_dirs

在 0.5 版本加入.

在其中搜索其他邮件目录的目录(请参见 language ),相对于源目录。此路径上的目录按标准搜索 gettext 模块。

内部消息从文本域中提取 sphinx ;因此,如果您添加目录 ./locale 根据此设置,消息目录(从 .po 格式使用 msgfmt )必须在 ./locale/language/LC_MESSAGES/sphinx.mo 。单个文档的文本域取决于 gettext_compact

缺省值为 ['locales']

备注

这个 -v option for sphinx-build command 对于检查locale_dirs配置是否按预期工作很有用。如果找不到消息目录目录,它将发出调试消息。

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

gettext_allow_fuzzy_translations

如果为真,则使用消息目录中的“模糊”消息进行翻译。缺省值为 False

在 4.3 版本加入.

gettext_compact

在 1.1 版本加入.

如果为True,则文档的文本域是其文档名称(如果它是顶级项目文件),否则为其最基本的目录。

如果设置为字符串,则所有文档的文本域都是该字符串,从而使所有文档使用单个文本域。

默认情况下,文档 markup/code.rst 最终落到了 markup 文本域。将此选项设置为 False 是的,它是 markup/code

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

gettext_uuid

如果为True,Sphinx将生成UUID信息,用于消息目录中的版本跟踪。它用于:

  • 在.pot文件中为每个msgid添加uid行。

  • 计算新消息ID和以前保存的旧消息ID之间的相似度。这项计算需要很长时间。

如果想要加速计算,可以使用 python-levenshtein 使用C编写的第三方包 pip install python-levenshtein

缺省值为 False

在 1.3 版本加入.

gettext_location

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

缺省值为 True

在 1.3 版本加入.

gettext_auto_build

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

缺省值为 True

在 1.3 版本加入.

gettext_additional_targets

指定名称以启用附加应用于I18N的getText提取和转换。您可以指定以下名称:

指标:

索引项

文字块:

文字块 (:: 注释和 code-block 指令)

DOCST块:

文档测试块

未加工的:

原始含量

图像:

图像/图形URI

例如: gettext_additional_targets = ['literal-block', 'image']

缺省值为 []

在 1.3 版本加入.

在 4.0 版本发生变更: 默认情况下,会翻译图像的Alt文本。

figure_language_filename

特定语言图形的文件名格式。缺省值为 {root}.{language}{ext} 。它将扩展到 dirname/filename.en.png 从… .. image:: dirname/filename.png 。可用的格式令牌包括:

  • {root} - the filename, including any path component, without the file extension, e.g. dirname/filename

  • {path} - the directory path component of the filename, with a trailing slash if non-empty, e.g. dirname/

  • {docpath} -当前文档的目录路径组件,如果非空,则使用尾部斜杠。

  • {basename} - the filename without the directory path or file extension components, e.g. filename

  • {ext} - the file extension, e.g. .png

  • {language} - the translation language, e.g. en

例如,将其设置为 {path}{language}/{basename}{ext} 将扩展到 dirname/en/filename.png 取而代之的是。

在 1.4 版本加入.

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

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

translation_progress_classes

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

  • True :添加 translateduntranslated 类添加到具有可翻译内容的所有节点。

  • translated :仅添加 translated 班级。

  • untranslated :仅添加 untranslated 班级。

  • False :不添加任何类来指示翻译进度。

默认为 False

在 7.1 版本加入.

数学选项

这些选项会影响数学表示法。

math_number_all

将此选项设置为 True 如果希望对所有显示的数学进行编号。缺省值为 False

math_eqref_format

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

示例: 'Eq.{number}' 被呈现为,例如, Eq.10

math_numfig

如果 True 时,显示的数学公式会跨页编号 numfig 已启用。这个 numfig_secnum_depth 环境受到尊重。这个 eq ,不是 numref ,角色必须用于引用公式编号。缺省值为 True

在 1.7 版本加入.

用于HTML输出的选项

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

html_theme

HTML输出应该使用的“主题”。请参阅 section about theming 。缺省值为 'alabaster'

在 0.6 版本加入.

html_theme_options

影响所选主题外观的选项词典。这些是特定于主题的。有关内置主题理解的选项,请参见 this section

在 0.6 版本加入.

html_theme_path

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

在 0.6 版本加入.

html_style

用于HTML页的样式表。该名称的文件必须存在于Sphinx的 static/ 路径,或使用中给出的某个自定义路径 html_static_path 。默认是所选主题提供的样式表。如果与主题的样式表相比,您只想添加或覆盖几项内容,请使用css @import 要导入主题的样式表,请执行以下操作。

html_title

用Sphinx自己的模板生成的HTML文档的“标题”。它被追加到 <title> 标记,并在导航栏中用作“最顶层”元素。默认为 '<project> v<revision> documentation'

html_short_title

这是一个较短的“标题”,用来表示这些HTML文档。它用于页眉和HTML帮助文档中的链接。如果未指定,则默认为 html_title

在 0.4 版本加入.

html_baseurl

指向HTML文档根目录的基本URL。它用来指示文件的位置,使用 The Canonical Link Relation 。默认: ''

在 1.8 版本加入.

html_codeblock_linenos_style

代码块的行号样式。

  • 'table' --使用显示行号 <table> 标牌

  • 'inline' --使用显示行号 <span> 标记(默认)

在 3.2 版本加入.

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

自 4.0 版本弃用.

html_context

要传递到所有页面的模板引擎上下文中的值字典。也可以将单个值放入此词典中 -A 命令行选项 sphinx-build

在 0.5 版本加入.

如果给定,这必须是图像文件的名称(相对于 configuration directory )这是文档的徽标,或指向徽标的图像文件的URL。它被放置在侧边栏的顶部;因此其宽度不应超过200像素。默认: None

在 0.4.1 版本加入: 该图像文件将被复制到 _static 目录,但仅当该文件不存在的情况下。

在 4.0 版本发生变更: 还接受徽标文件的URL。

html_favicon

如果给定,这必须是图像文件的名称(相对于 configuration directory )这是文档的收藏图标,或指向该收藏图标的图像文件的URL。现代浏览器将其用作选项卡、窗口和书签的图标。它应该是Windows样式的图标文件 (.ico ),大小为16x16或32x32像素。默认: None

在 0.4 版本加入: 该图像文件将被复制到 _static 目录,但仅当该文件不存在的情况下。

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

html_css_files

一个css文件列表。该条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典。这个 filename 必须相对于 html_static_path ,或具有如下方案的完整URI https://example.org/style.css 。这个 attributes 用于以下属性 <link> 标签。它默认为空列表。

示例::

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

作为一种特殊属性, priority 可以设置为整数以更早或更慢的步骤加载css文件。有关更多信息,请参阅 Sphinx.add_css_file()

在 1.8 版本加入.

在 3.5 版本发生变更: 支持优先级属性

html_js_files

一份JavaScript的列表 filename 。该条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典。这个 filename 必须相对于 html_static_path ,或具有如下方案的完整URI https://example.org/script.js 。这个 attributes 用于以下属性 <script> 标签。它默认为空列表。

示例::

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

作为一种特殊属性, priority 可以设置为整数以更早或更慢的步骤加载css文件。有关更多信息,请参阅 Sphinx.add_css_file()

在 1.8 版本加入.

在 3.5 版本发生变更: 支持优先级属性

html_static_path

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

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

备注

出于安全原因,以下目录下的点文件 html_static_path 不会被复制。如果您想要故意复制它们,请将每个文件路径添加到此设置:

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

另一种方法是,您还可以使用 html_extra_path 。它允许复制目录下的点文件。

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

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

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

html_extra_path

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

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

在 1.2 版本加入.

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

html_last_updated_fmt

如果不是NONE,则在每个页面底部插入“上次更新日期:”时间戳,并使用给定的 strftime() 格式化。空字符串等效于 '%b %d, %Y' (或与区域设置相关的等价物)。

html_use_smartypants

如果为True,则引号和破折号将转换为排版正确的实体。默认: True

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

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

在 3.5 版本加入.

每个标题和描述环境的链接锚点的文本。允许使用HTML实体和Unicode。默认:段落符号;

在 3.5 版本加入.

html_sidebars

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

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

这些值可以是列表,也可以是单个字符串。

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

    默认侧边栏(用于不匹配任何模式的文档)由主题本身定义。默认情况下,内置主题使用以下模板: ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']

  • 如果值是单个字符串,则它指定要在 'sourcelink.html''searchbox.html' 参赛作品。这是为了与Sphinx 1.0之前的版本兼容。

自 1.7 版本弃用: 的单个字符串值 html_sidebars 将在2.0中删除

可以呈现的内置侧栏模板包括:

  • localtoc.html --当前文档的细粒度目录

  • globaltoc.html --整个文档集的粗粒度目录,折叠

  • relations.html --指向上一份和下一份文件的两个链接

  • sourcelink.html --指向当前文档的源的链接(如果在中启用 html_show_sourcelink

  • searchbox.html --“快速搜索”框

示例::

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

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

在 1.0 版本加入: 使用全局键和指定多个侧边栏的能力。

请注意,仅当所选主题不具有侧边栏(如内置)时,此值才有效 scrollshaiku 主题。

html_additional_pages

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

示例::

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

这将呈现模板 customdownload.html 作为页面 download.html

html_domain_indices

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

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

在 1.0 版本加入.

html_use_index

如果为True,则向HTML文档添加索引。缺省值为 True

在 0.4 版本加入.

html_split_index

如果为True,则索引生成两次:一次作为包含所有条目的单页,一次作为每个起始字母的一页。缺省值为 False

在 0.4 版本加入.

html_copy_source

如果为True,则REST源代码作为 _sources/name 。缺省值为 True

如果为真(和 html_copy_source 也是正确的),指向REST源代码的链接将被添加到侧边栏。缺省值为 True

在 0.6 版本加入.

要附加到源链接的后缀(请参见 html_show_sourcelink ),除非他们已经有了这个后缀。缺省值为 '.txt'

在 1.5 版本加入.

html_use_opensearch

如果非空,则返回 OpenSearch 将输出描述文件,并且所有页面都将包含 <link> 引用它的标签。由于OpenSearch不支持其搜索页面位置的相对URL,因此此选项的值必须是提供这些文档的基本URL(没有尾随斜杠),例如 "https://docs.python.org" 。缺省值为 ''

html_file_suffix

这是生成的HTML文件的文件名后缀,如果设置为 str 价值。如果保留为默认设置 None ,后缀将为 ".html"

在 0.4 版本加入.

生成的指向HTML文件的链接的后缀。默认设置为Anywhere html_file_suffix 设置为;可以进行不同的设置(例如,以支持不同的Web服务器设置)。

在 0.6 版本加入.

如果是真的,“(C)版权...”显示在HTML页脚中。缺省值为 True

在 1.0 版本加入.

html_show_search_summary

如果为True,则关键字周围的文本显示为每个搜索结果的摘要。缺省值为 True

在 4.5 版本加入.

html_show_sphinx

如果为True,则“Created with Sphinx”将显示在HTML页脚中。缺省值为 True

在 0.4 版本加入.

html_output_encoding

对HTML输出文件进行编码。缺省值为 'utf-8' 。请注意,此编码名称必须同时是有效的Python编码名称和有效的HTML charset 价值。

在 1.0 版本加入.

html_compact_lists

如果为True,则由单个段落和/或子列表组成的所有项组成的列表...(递归定义)将不会使用 <p> 元素的任何项。这是标准的Docutils行为。默认: True

在 1.0 版本加入.

html_secnumber_suffix

节编号的后缀。默认: ". " 。设置为 " " 以取消节号上的最后一个点。

在 1.0 版本加入.

html_search_language

用于生成HTML全文搜索索引的语言。默认设置为使用选择的全局语言 language 。如果不支持该语言, "en" 用于选择英语语言。

提供对以下语言的支持:

  • da --丹麦

  • nl --荷兰

  • en --英语

  • fi --芬兰

  • fr --法语

  • de --德语

  • hu --匈牙利

  • it --意大利

  • ja --日语

  • no --挪威

  • pt -葡萄牙语

  • ro 罗马尼亚人

  • ru --俄语

  • es --西班牙语

  • sv --瑞典人

  • tr --土耳其语

  • zh --中文

加快构建速度

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

在 1.1 版本加入: 通过支持 enja

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

html_search_options

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

英语支持人员没有选择余地。

日本的支持有以下几个选项:

类型:

type`是点分模块路径字符串,用于指定应从中派生的拆分器实现 :class:!sphinx.search.ja.BaseSplitter` 。如果未指定或 None 是指定的, 'sphinx.search.ja.DefaultSplitter' 将会被使用。

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

'sphinx.search.ja.DefaultSplitter':

TinySegmenter算法。这是默认拆分器。

'sphinx.search.ja.MecabSplitter':

MeCab绑定。要使用此拆分器,需要‘mecab’python绑定或动态链接库(对于Linux,需要‘libmecab.so’;对于Windows,需要‘libmecab.dll’)。

'sphinx.search.ja.JanomeSplitter':

珍妮姆装订。要使用这个拆分器, Janome 是必需的。

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

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

选项: 'mecab'
dic_enc:

_`dic_enc option`是MeCab算法的编码。

迪克特:

_`dict option`是用于MeCab算法的字典。

利布:

_`lib option`是未安装Python绑定时,通过ctype查找MeCab库的库名。

例如::

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

_`USER_DIC选项`是Janome的用户词典文件路径。

user_dic_enc:

user_dic_enc option`是由指定的用户词典文件的编码 ``user_dic` 选择。默认值为‘UTF8’。

在 1.1 版本加入.

在 1.4 版本发生变更: 重新组织了日语的Html_Search_Options,任何自定义拆分器都可以由 type 设置。

中国的支持有以下几个选项:

  • dict -- jieba 如果要使用自定义词典,则为词典路径。

html_search_scorer

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

在 1.2 版本加入.

如果为True,则图像本身链接到原始图像(如果它没有“目标”选项或与缩放相关的选项:“Scale”、“Width”、“Height”)。缺省值为 True

文档作者可以使用以下命令手动禁用此功能 no-scaled-link 类添加到图像:

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

在 1.3 版本加入.

在 3.0 版本发生变更: 对于具有以下各项的图像,该选项被禁用 no-scaled-link 班级

html_math_renderer

用于HTML输出的MATH_RENDER扩展名。缺省值为 'mathjax'

在 1.8 版本加入.

html_experimental_html5_writer

输出由HTML5编写器处理。缺省值为 False

在 1.6 版本加入.

自 2.0 版本弃用.

html4_writer

输出由HTML4编写器处理。缺省值为 False

用于单个HTML输出的选项

singlehtml_sidebars

自定义侧栏模板,必须是将文档名称映射到模板名称的词典。并且它只允许名为的密钥 'index' 。所有其他关键点都将被忽略。有关详细信息,请参阅 html_sidebars 。默认情况下,它与 html_sidebars

用于输出HTML帮助的选项

htmlhelp_basename

HTML帮助生成器的输出文件基名称。缺省值为 'pydoc'

htmlhelp_file_suffix

这是生成的HTML帮助文件的文件名后缀。缺省值为 ".html"

在 2.0 版本加入.

生成的指向HTML文件的链接的后缀。缺省值为 ".html"

在 2.0 版本加入.

Apple帮助输出选项

在 1.3 版本加入.

这些选项会影响Apple帮助输出。此构建器派生自HTML构建器,因此在适当的地方也可以应用HTML选项。

备注

Apple帮助输出只能在Mac OS X 10.6及更高版本上运行,因为它需要 hiutilcodesign 命令行工具,这两种工具都不是开源的。

您可以使用以下命令禁用这些工具 applehelp_disable_external_tools ,但只有在索引器运行于 .lproj 捆绑包中的文件夹。

applehelp_bundle_name

Apple Help Book的基本名称。默认设置为 project 名字。

applehelp_bundle_id

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

警告

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

applehelp_dev_region

开发区。默认为 'en-us' ,这是苹果推荐的设置。

applehelp_bundle_version

捆绑包版本(字符串形式)。默认为 '1'

applehelp_icon

帮助包图标文件,或 None 因为没有图标。根据苹果的文档,这应该是一个16x16像素版本的应用程序的图标,具有透明的背景,另存为PNG文件。

applehelp_kb_product

与一起使用的产品标签 applehelp_kb_url 。默认为 '<project>-<release>'

applehelp_kb_url

知识库服务器的URL,例如 https://example.com/kbsearch.py?p='product'&q='query'&l='lang' 。Help查看器将替换这些值 'product''query''lang' 在运行时使用 applehelp_kb_product 、用户在搜索框中输入的文本和用户的系统语言。

默认为 None 不需要远程搜索。

applehelp_remote_url

远程内容的URL。您可以将您的帮助手册的副本 Resources 文件夹,Help查看器将尝试使用它来获取更新的内容。

例如,如果您将其设置为 https://example.com/help/Foo/ Help查看器需要一份 index.html 对于会说英语的客户,它将查看 https://example.com/help/Foo/en.lproj/index.html

默认为 None 没有远程内容。

applehelp_index_anchors

如果 True ,告诉帮助索引器对生成的HTML中的锚点进行索引。属性跳到特定主题时,这会很有用。 AHLookupAnchor 函数或 openHelpAnchor:inBook: 方法。它还允许您使用 help:anchor URL;有关此主题的更多信息,请参阅Apple文档。

applehelp_min_term_length

控制帮助索引器的最小术语长度。默认为 None ,这意味着将使用默认设置。

applehelp_stopwords

语言规范(使用内置的停用词),或停用词plist的路径,或者 None 如果你不想使用停用词。可以在以下位置找到默认的停用字plist /usr/share/hiutil/Stopwords.plist 在撰写本文时,它包含以下语言的停用词:

语言

代码

英语

恩恩

德语

De

西班牙语

ES

法语

是的

瑞典语

服务提供商

匈牙利语

意大利语

默认为 language ,或者如果未设置,则设置为 'en'

applehelp_locale

指定要为其生成帮助的区域设置。这用于确定 .lproj 帮助手册中的文件夹 Resources ,并被传递到帮助索引器。

默认为 language ,或者如果未设置,则设置为 'en'

applehelp_title

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

applehelp_codesign_identity

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

缺省为环境变量的值 CODE_SIGN_IDENTITY ,它由Xcode为脚本生成阶段设置,或者 None 如果未设置该变量。

applehelp_codesign_flags

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

缺省为基于环境变量的值的列表 OTHER_CODE_SIGN_FLAGS ,它是由Xcode为脚本构建阶段设置的,如果没有设置该变量,则返回空列表。

applehelp_indexer_path

通向 hiutil 程序。默认为 '/usr/bin/hiutil'

applehelp_codesign_path

通向 codesign 程序。默认为 '/usr/bin/codesign'

applehelp_disable_external_tools

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

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

默认为 False

用于epub输出的选项

这些选项会影响epub输出。由于此构建器派生自HTML构建器,因此在适当的情况下也会应用HTML选项。某些选项的实际值并不重要,只需将它们输入到 Dublin Core metadata

epub_basename

Epub文件的基本名称。它缺省为 project 名字。

epub_theme

Epub输出的HTML主题。由于默认主题没有针对小屏幕空间进行优化,因此使用相同的主题作为HTML和epub输出通常是不明智的。该默认为 'epub' ,一个为节省视觉空间而设计的主题。

epub_theme_options

影响所选主题外观的选项词典。这些是特定于主题的。有关内置主题理解的选项,请参见 this section

在 1.2 版本加入.

epub_title

文档的标题。它缺省为 html_title 选项,但可以为epub创建单独设置。它缺省为 project 选择。

在 2.0 版本发生变更: 它缺省为 project 选择。

epub_description

文档的说明。缺省值为 'unknown'

在 1.4 版本加入.

在 1.5 版本发生变更: 重命名自 epub3_description

epub_author

文档的作者。这放在都柏林核心元数据中。它缺省为 author 选择。

epub_contributor

在EPUB出版物的内容创建中扮演次要角色的个人、组织等的名称。缺省值为 'unknown'

在 1.4 版本加入.

在 1.5 版本发生变更: 重命名自 epub3_contributor

epub_language

文档的语言。这放在都柏林核心元数据中。缺省值为 language 选项或 'en' 如果未设置。

epub_publisher

文档的发布者。这放在都柏林核心元数据中。您可以使用任何合理的字符串,例如项目主页。默认设置为 author 选择。

文档的版权。它缺省为 copyright 选项,但可以为epub创建单独设置。

epub_identifier

文档的标识符。这放在都柏林核心元数据中。对于已发布的文件,这是ISBN编号,但您也可以使用替代方案,例如项目主页。缺省值为 'unknown'

epub_scheme

的出版计划 epub_identifier 。这放在都柏林核心元数据中。对于出版的书籍,该计划是 'ISBN' 。如果您使用项目主页, 'URL' 看起来很合理。缺省值为 'unknown'

epub_uid

文档的唯一标识符。这放在都柏林核心元数据中。您可以使用 XML's Name format 弦乐。不能使用连字符、句点、数字作为第一个字符。缺省值为 'unknown'

epub_cover

封面信息。这是一个包含封面图像和html模板的文件名的元组。将呈现的html封面作为第一个项目插入 content.opf 。如果模板文件名为空,则不会创建任何html封面。如果元组为空,则根本不会创建封面。示例:

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

缺省值为 ()

在 1.1 版本加入.

epub_css_files

一个css文件列表。该条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典。有关详细信息,请参阅 html_css_files

在 1.8 版本加入.

epub_guide

的引导元素的元数据 content.opf 。这是一个元组序列,包含 type vt.的. uri 以及 title 可选的指南信息。请参阅OPF文档,网址为 http://idpf.org/epub 了解更多细节。如果可能,默认条目为 covertoc 类型将自动插入。但是,如果默认条目不合适,则可以显式覆盖这些类型。示例::

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

缺省值为 ()

epub_pre_files

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

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

缺省值为 []

epub_post_files

应该在Sphinx生成的文本之后插入的其他文件。它是包含文件名和标题的元组列表。此选项可用于添加附录。如果标题为空,则不会向 toc.ncx 。缺省值为 []

epub_exclude_files

在构建目录中生成/复制但不应包含在epub文件中的文件列表。缺省值为 []

epub_tocdepth

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

epub_tocdup

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

epub_tocscope

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

  • 'default' --包括所有未隐藏的目录条目(默认)

  • 'includehidden' --包括所有目录条目

在 1.2 版本加入.

epub_fix_images

此标志确定是否应尝试修复某些epub阅读器不支持的图像格式。目前,带有小颜色表的调色板图像进行了升级。要使用此选项,您需要安装Pillow,即Python图像库。缺省值为 False 因为自动转换可能会丢失信息。

在 1.2 版本加入.

epub_max_image_width

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

在 1.2 版本加入.

epub_show_urls

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

  • 'inline' --在括号中以内联方式显示URL(默认)

  • 'footnote' --在脚注中显示URL

  • 'no' --不显示URL

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

在 1.2 版本加入.

epub_use_index

如果为True,则向epub文档添加索引。它缺省为 html_use_index 选项,但可以为epub创建单独设置。

在 1.2 版本加入.

epub_writing_mode

它指定了写入方向。它可以接受 'horizontal' (默认)和 'vertical'

epub_writing_mode

'horizontal'

'vertical'

写入模式 [2]

horizontal-tb

vertical-rl

页面进度

从左到右

从右到左

IBook的滚动主题支持

滚动轴是垂直的。

滚动轴是水平的。

LaTeX输出选项

这些选项会影响 Latex 的输出。

latex_engine

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

  • 'pdflatex' --PDFLaTeX(默认)

  • 'xelatex' --XeLaTeX

  • 'lualatex' --LuaLaTeX

  • 'platex' --Platex

  • 'uplatex' --upLaTeX(默认为 language'ja' )

'pdflatex' S对UNICODE字符的支持是有限的。

备注

2.0版增加了 'pdflatex' 支持偶尔使用西里尔字母或希腊字母或单词的拉丁语文档。这不是自动的,请参见 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 成为日语文档的默认设置。

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 latex_elements 'preamble' key). You may prefer r'\usepackage[math-style=literal]{unicode-math}' to keep a Unicode literal such as α (U+03B1) for example as is in output, rather than being rendered as \(\alpha\).

latex_documents

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

startdocname

字符串,该字符串指定 document name LaTeX文件的主文档。引用的所有文档 startdoc 目录树中的文档将包含在LaTeX文件中。(如果您希望在LaTeX版本中使用默认根文档,请提供 root_doc 在这里。)

targetname

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

title

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

author

Author for the LaTeX document. The same LaTeX markup caveat as for title applies. Use \\and to separate multiple authors, as in: 'John \\and Sarah' (backslashes must be Python-escaped to reach LaTeX).

theme

Latex 主题。看见 latex_theme

toctree_only

一定是 TrueFalse 。如果为真,则 startdoc 输出中不包括文档本身,仅包括它通过目录树引用的文档。使用此选项,您可以将额外的内容放入显示在HTML中的主文档中,而不是LaTeX输出中。

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

在 0.3 版本加入: 第六条 toctree_only 。仍然接受包含5个项目的元组。

如果给定,这必须是作为文档徽标的图像文件的名称(相对于配置目录)。它被放置在标题页的顶部。默认: None

latex_toplevel_sectioning

该值确定最上面的剖分单位。它应该从以下选项中选择 'part''chapter''section' 。缺省值为 None ;最上面的分段单位按文件类切换: section 如果DocumentClass将为 howto ,否则 chapter 将会被使用。

请注意,如果LaTeX使用 \part 命令,则一级深的分段单元的编号与HTML编号不同步,因为LaTeX编号是连续的 \chapter (或 \sectionhowto 。)

在 1.4 版本加入.

latex_appendices

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

latex_domain_indices

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

该值可以是bool,也可以是应该生成的索引名称列表,如FOR html_domain_indices

在 1.0 版本加入.

latex_show_pagerefs

如果为True,则在内部引用之后添加页引用。这对于手册的打印副本非常有用。缺省值为 False

在 1.0 版本加入.

latex_show_urls

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

  • 'no' --不显示URL(默认)

  • 'footnote' --在脚注中显示URL

  • 'inline' --在括号中以内联方式显示URL

在 1.0 版本加入.

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

latex_use_latex_multicolumn

缺省值为 False :这意味着Sphinx自己的宏用于网格表中的合并单元格。它们允许一般内容(字面块、列表、块引号等)但可能会有问题,如果 tabularcolumns 指令用于注入类型的LaTeX标记 >{..}<{..}@{..} 作为柱规格。

设置为 True 使用LaTeX标准的手段 \multicolumn ;这与水平合并单元格中的文字块不兼容,如果表格使用 tabulary

在 1.6 版本加入.

latex_table_style

样式类(字符串)的列表。目前支持:

  • 'booktabs' :没有垂直线,只有2到3行水平线(如果有标题,则为后者),使用 booktabs 包裹。

  • 'borderless' :没有任何台词。

  • 'colorrows' :表格行以交替的背景颜色呈现。定制它们的界面是通过 dedicated keys这个 sphinxsetup 配置设置

    重要

    'colorrows' 风格, \rowcolors LaTeX命令变成了no-op(该命令有限制,并且从未正确支持Sphinx在LaTeX中生成的所有类型的表)。请更新您的项目以使用 latex table color configuration 钥匙。

默认: ['booktabs', 'colorrows']

在 5.3.0 版本加入.

在 6.0.0 版本发生变更: 修改默认发件人 []['booktabs', 'colorrows']

每个表都可以通过以下方式覆盖全局样式 :class: 选项,或 .. rst-class:: 对于非指令表(参见 表格 )。当前可识别的类有 booktabsborderlessstandardcolorrowsnocolorrows 。后两项可以与前三项中的任何一项组合。这个 standard 类生成同时具有水平线和垂直线的表(这是Sphinx到目前为止的默认设置)。

如果设置了单行多列合并单元格,则它将遵循行颜色。另请参阅 TableMergeColor{Header,Odd,Even}这个 sphinxsetup 配置设置 一节。

备注

  • 它在LaTeX中是硬编码的,即使有列颜色设置为 \columncolor 从列规范(请参见 tabularcolumns )。狮身人面像提供 \sphinxnorowcolor 它可以像这样使用:

    >{\columncolor{blue}\sphinxnorowcolor}
    

    在表列规范中。

  • 狮身人面像还提供 \sphinxcolorblend 然而,这需要 xcolor 包裹。下面是一个例子:

    >{\sphinxcolorblend{!95!red}}
    

    这意味着在该列中,行的颜色将略带红色;请参阅 xcolor 有关其语法的更多信息,请参阅文档 \blendcolors 命令(a \blendcolors 代替 \sphinxcolorblend 会修改单元格的颜色 contents ,而不是细胞的 background colour panel ...)。中可以找到一个用法示例 已弃用接口 本文档的部分内容为PDF格式。

    提示

    如果要将特殊颜色用于 contents 给定列的单元格中使用 >{\noindent\color{<color>}} ,可能是除了上述之外。

  • 多行合并单元格,无论是单列还是多列,当前都会忽略任何设置的列、行或单元格颜色。

  • 对于简单的单元格,可以通过 raw 指令和 \cellcolor 在单元格内容中的任何位置使用的LaTeX命令。这目前在合并后的单元格中不起作用,无论是哪种类型。

提示

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

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

latex_use_xindy

如果 True ,由Sphinx创建的LaTeX文件生成的PDF将使用 xindy (doc) 而不是 makeindex 编制一般术语索引(自 index 用法)。这意味着具有UTF-8字符的单词将针对 language

  • 如果出现以下情况,则忽略此选项 latex_engine'platex' (日文文件; mendex 取代 makeindex 然后)。

  • 缺省值为 True'xelatex''lualatex' AS makeindex ,如果任何索引项以非ASCII字符开头,则创建 .ind 包含无效字节的文件,无法进行UTF-8编码。使用 'lualatex' 这就破坏了PDF构建。

  • 缺省值为 False'pdflatex'True 建议在某些索引项使用语言脚本中的非ASCII字符时立即用于非英语文档。

狮身人面像增加了 xindy 基本发行版一些专用的支持使用 'pdflatex' 使用西里尔字母的引擎。无论是与 'pdflatex' 或Unicode引擎,西里尔语文档可以正确处理拉丁文名称的索引,甚至可以使用变音符号。

在 1.8 版本加入.

latex_elements

在 0.5 版本加入.

它的 documentation 已搬到 Latex 定制

latex_docclass

词典映射 'howto''manual' 设置为将用作两个Sphinx类的基础的实际文档类的名称。默认情况下,使用 'article''howto''report''manual'

在 1.0 版本加入.

在 1.5 版本发生变更: 在日语文档中 (language'ja' ),默认情况下 'jreport' 用于 'howto''jsbook''manual'

latex_additional_files

生成LaTeX输出时要复制到构建目录的相对于配置目录的文件名列表。这对于复制Sphinx不会自动复制的文件非常有用,例如,如果在添加的自定义LaTeX中引用它们 latex_elements 。源文件中引用的图像文件(例如,通过 .. image:: )会自动复制。

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

注意

带扩展名的文件名 .tex 将自动移交给由以下触发的PDF构建过程 sphinx-build -M latexpdf 或通过 make latexpdf 。如果仅将该文件添加为 \input{} 在修改后的前同步码中,您必须添加另一个后缀,例如 .txt 设置为文件名,并相应地调整 \input{} 命令添加到LaTeX文件序言中。

在 0.6 版本加入.

在 1.2 版本发生变更: 这将覆盖Sphinx提供的文件,例如 sphinx.sty

latex_theme

LaTeX输出应该使用的“主题”。它是LaTeX输出设置的集合(例如文档类、顶级分段单元等)。

作为一款内置的 Latex 主题, manualhowto 是捆绑在一起的。

manual

用于编写手册的 Latex 主题。它导入了 report Document类(日语文档使用 jsbook )。

howto

用来写文章的 Latex 主题。它导入了 article Document类(日语文档使用 jreport 而是)。 latex_appendices 仅适用于此主题。

默认为 'manual'

在 3.0 版本加入.

latex_theme_options

影响所选主题外观的选项词典。

在 3.1 版本加入.

latex_theme_path

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

在 3.0 版本加入.

用于文本输出的选项

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

text_newlines

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

  • 'unix' :使用Unix样式的行尾 (\n )

  • 'windows' :使用Windows样式的行尾 (\r\n )

  • 'native' :使用构建文档的平台的行尾样式

默认: 'unix'

在 1.1 版本加入.

text_sectionchars

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

缺省值为 '*=-~"+`'

在 1.1 版本加入.

text_add_secnumbers

一个布尔值,它决定文本输出中是否包含节号。缺省值为 True

在 1.7 版本加入.

text_secnumber_suffix

文本输出中的节号的后缀。默认: ". " 。设置为 " " 以取消节号上的最后一个点。

在 1.7 版本加入.

用于手动页面输出的选项

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

man_pages

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

startdocname

字符串,该字符串指定 document name 手册页的主文档。引用的所有文档 startdoc 目录树中的文档将包含在手册文件中。(如果要使用默认根文档构建手册页面,请使用您的 root_doc 在这里。)

name

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

description

手册页的说明。这在名称部分中使用。如果不想自动生成NAME节,则可以为空字符串。

authors

具有作者的字符串列表,或单个字符串。如果不希望在手册页中自动生成作者部分,则可以为空字符串或列表。

section

手册页部分。用于输出文件名以及在手册页眉中。

在 1.0 版本加入.

man_show_urls

如果为True,则在链接后添加URL地址。缺省值为 False

在 1.1 版本加入.

man_make_section_directory

如果为True,则在构建手册页上创建一个部分目录。默认为True。

在 3.3 版本加入.

在 4.0 版本发生变更: 默认设置更改为 False 从… True

在 4.0.2 版本发生变更: 默认设置更改为 True 从… False 再来一次。

用于纹理信息输出的选项

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

texinfo_documents

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

startdocname

字符串,该字符串指定 document name 纹理信息文件的主文档的。引用的所有文档 startdoc 目录树中的文档将包含在文本信息文件中。(如果您想要为您的纹理信息版本使用默认主文档,请提供您的 root_doc 在这里。)

targetname

输出目录中的文本信息文件的文件名(无扩展名)。

title

文本信息文档标题。可以为空以使用 startdoc 文件。作为纹理信息标记插入,因此特殊字符,如 @{} 将需要转义才能按字面插入。

author

纹理信息文档的作者。作为纹理信息标记插入。使用 @* 要分隔多个作者,如: 'John@*Sarah'

dir_entry

将出现在顶层的名称 DIR 菜单文件。

description

要在顶层显示的描述性文本 DIR 菜单文件。

category

指定此条目将显示在顶级中的节 DIR 菜单文件。

toctree_only

一定是 TrueFalse 。如果为真,则 startdoc 输出中不包括文档本身,仅包括它通过目录树引用的文档。使用此选项,您可以将额外的内容放入显示在HTML中的主文档中,而不是显示在纹理信息输出中。

在 1.1 版本加入.

texinfo_appendices

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

在 1.1 版本加入.

texinfo_domain_indices

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

该值可以是bool,也可以是应该生成的索引名称列表,如FOR html_domain_indices

在 1.1 版本加入.

texinfo_show_urls

控制如何显示URL地址。

  • 'footnote' --在脚注中显示URL(默认)

  • 'no' --不显示URL

  • 'inline' --在括号中以内联方式显示URL

在 1.1 版本加入.

texinfo_no_detailmenu

如果为True,则不生成 @detailmenu 在“Top”节点的菜单中,包含文档中每个子节点的条目。缺省值为 False

在 1.2 版本加入.

texinfo_elements

包含覆盖那些Sphinx通常输入到生成的 .texi 档案。

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

    'paragraphindent'

    每段第一行缩进的空格数,默认为 2 。指定 0 无缩进。

    'exampleindent'

    用于缩进示例或文字块的行的空格数,默认 4 。指定 0 无缩进。

    'preamble'

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

    'copying'

    纹理信息标记插入到 @copying 块,并显示在标题之后。缺省值由一个标识项目的简单标题页组成。

  • 由其他选项设置的、因此不应被覆盖的关键字包括:

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

在 1.1 版本加入.

texinfo_cross_references

如果为False,则不在文档中生成内联引用。这使得使用独立阅读器的INFO文件更具可读性 (info )。缺省值为 True

在 4.4 版本加入.

QtHelp输出选项

这些选项会影响qthelp输出。由于此构建器派生自HTML构建器,因此在适当的情况下也会应用HTML选项。

qthelp_basename

Qthelp文件的基本名称。它缺省为 project 名字。

qthelp_namespace

Qthelp文件的命名空间。默认为 org.sphinx.<project_name>.<project_version>

qthelp_theme

Qthelp输出的HTML主题。该默认为 'nonav'

qthelp_theme_options

影响所选主题外观的选项词典。这些是特定于主题的。有关内置主题理解的选项,请参见 this section

链接检查构建器的选项

linkcheck_ignore

执行操作时不应检查的与URI匹配的正则表达式列表 linkcheck 建造。示例::

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

在 1.1 版本加入.

linkcheck_allowed_redirects

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

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

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

示例:

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

如果设置,则LinkCheck生成器将在发现不允许的重定向时发出警告。下检测意外重定向非常有用 the warn-is-error mode

在 4.1 版本加入.

linkcheck_request_headers

将基URL映射到HTTP请求标头的词典。

键是基于URL的字符串,如下所示 "https://www.sphinx-doc.org/" 。要为其他主机指定标头,请执行以下操作: "*" 可以使用。仅当URL与其他设置不匹配时,它才匹配所有主机。

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

示例:

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

在 3.1 版本加入.

linkcheck_retries

链接检查生成器在宣布某个URL已损坏之前尝试检查该URL的次数。默认为1次尝试。

在 1.4 版本加入.

linkcheck_timeout

链接检查生成器的超时值(以秒为单位)。默认情况下,使用Python的全局套接字超时。

在 1.1 版本加入.

linkcheck_workers

检查链接时使用的工作线程数。默认为5个线程。

在 1.1 版本加入.

linkcheck_anchors

如果为True,则检查 #anchor 链接中的S。由于这需要下载整个文档,因此在启用时速度会相当慢。缺省值为 True

在 1.2 版本加入.

linkcheck_anchors_ignore

检查链接中锚点的有效性时,与锚点Sphinx匹配的正则表达式列表应该跳过。这允许跳过网站的JavaScript添加到控制动态页面的锚点,或者在触发内部REST请求时。缺省值为 ["^!"]

小技巧

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

备注

如果要忽略特定页面的锚点或与特定模式匹配的页面的锚点(但仍要检查相同页面(S)中没有锚点的匹配项),请使用 linkcheck_ignore 相反,例如如下所示:

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

在 1.5 版本加入.

linkcheck_anchors_ignore_for_url

与Sphinx不应检查其锚的有效性的URL匹配的正则表达式的列表或元组。这允许跳过基于每个页面的锚点检查,同时仍然检查页面本身的有效性。默认为空的元组 ()

在 7.1 版本加入.

linkcheck_auth

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

一份名单 (regex_pattern, auth_info) 项目所在位置的元组:

regex_pattern

与URI匹配的正则表达式。

auth_info

用于该URI的身份验证信息。该值可以是 requests 库(请参见 requests Authentication 有关详细信息)。

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

示例::

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

在 2.3 版本加入.

linkcheck_rate_limit_timeout

这个 linkcheck 建筑商可能会在短时间内向同一站点发出大量请求。当服务器指示请求受到速率限制时,此设置控制生成器行为。

如果服务器指示何时重试(使用 Retry-After 标题)、 linkcheck 始终遵循服务器指示。

否则, linkcheck 在重试之前等待一分钟,并持续将两次尝试之间的等待时间增加一倍,直到成功或超过 linkcheck_rate_limit_timeout 。默认情况下,超时为5分钟。

在 3.4 版本加入.

linkcheck_exclude_documents

与Sphinx不应检查链接有效性的文档匹配的正则表达式列表。这可用于允许文档的遗留或历史部分中的链接衰减。

示例::

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

在 4.4 版本加入.

用于XML构建器的选项

xml_pretty

如果为真,则将XML打印出来。缺省值为 True

在 1.2 版本加入.

脚注

针对C域的选项

c_id_attributes

解析器还应接受作为属性的字符串列表。例如,当属性已被 #define D代表可移植性。

在 3.0 版本加入.

c_paren_attributes

解析器还应接受的字符串列表,作为带有一个参数的属性。也就是说,如果 my_align_as 在名单上,那么 my_align_as(X) 被解析为所有字符串的属性 X 有平衡大括号的 (()[] ,以及 {} )。例如,当属性已被 #define D代表可移植性。

在 3.0 版本加入.

c_extra_keywords

要被C解析器识别为关键字的标识符列表。默认为 ['alignas', 'alignof', 'bool', 'complex', 'imaginary', 'noreturn', 'static_assert', 'thread_local']

在 4.0.3 版本加入.

c_maximum_signature_line_length

如果签名的字符长度超过设置的数字,则每个参数将显示在单独的逻辑行上。这是特定于域的设置,重写 maximum_signature_line_length

在 7.1 版本加入.

C++域的选项

cpp_index_common_prefix

对全局索引中的C++对象进行排序时将忽略的前缀列表。例如 ['awesome_lib::']

在 1.5 版本加入.

cpp_id_attributes

解析器还应接受作为属性的字符串列表。例如,当属性已被 #define D代表可移植性。

在 1.5 版本加入.

cpp_paren_attributes

解析器还应接受的字符串列表,作为带有一个参数的属性。也就是说,如果 my_align_as 在名单上,那么 my_align_as(X) 被解析为所有字符串的属性 X 有平衡大括号的 (()[] ,以及 {} )。例如,当属性已被 #define D代表可移植性。

在 1.5 版本加入.

cpp_maximum_signature_line_length

如果签名的字符长度超过设置的数字,则每个参数将显示在单独的逻辑行上。这是特定于域的设置,重写 maximum_signature_line_length

在 7.1 版本加入.

用于Python域的选项

python_display_short_literal_types

该值控制如何 Literal 将显示类型。该设置为布尔值,默认为 False

实例

下面的示例使用以下内容 py:function 指令:

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

什么时候 FalseLiteral 类型按照标准的Python语法显示,即:

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

什么时候 TrueLiteral 类型显示为短的、 PEP 604 -受启发的语法,即:

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

在 6.2 版本加入.

python_use_unqualified_type_names

如果为True,则在可以解析的情况下取消显示Python引用的模块名称。缺省值为 False

在 4.0 版本加入.

备注

此配置仍处于实验阶段

python_maximum_signature_line_length

如果签名的字符长度超过设置的数字,则每个参数或类型参数将显示在单独的逻辑行上。这是特定于域的设置,重写 maximum_signature_line_length

对于Python域,签名长度取决于是否设置了类型参数或参数列表的格式。对于前者,签名长度忽略参数列表的长度;对于后者,签名长度忽略类型参数列表的长度。

例如,使用 python_maximum_signature_line_length = 20 ,则仅类型参数列表将被换行,而参数列表将呈现在一行上

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

在 7.1 版本加入.

用于Java Script域的选项

javascript_maximum_signature_line_length

如果签名的字符长度超过设置的数字,则每个参数将显示在单独的逻辑行上。这是特定于域的设置,重写 maximum_signature_line_length

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