配置

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

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

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

重点注意:

  • 如果没有另外记录, 则值必须是字符串, 并且它们的默认值为空字符串。

  • 术语“全限定名”指的是一个字符串,该字符串对模块内的可导入Python对象进行命名:例如,FQN“sphinx.builders.Builder”表示构建器中的“sphinx.builders”模块。

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

  • 因为 conf.py 作为Python文件读取,通常的规则适用于编码和Unicode支持。

  • 配置名称空间的内容被pickle(以便Sphinx能够在配置更改时发现),因此它可能不包含不可pickle的值——如果合适的话,使用“del”从名称空间中删除它们。模块会自动删除,所以您不需要在使用后“del”您的导入。

  • 配置文件中有一个名为“tags”的特殊对象。 它可用于查询和更改标记(请参阅 引用基于标签的内容)。 使用 “tags.has(‘tag’)”来查询,“tags.add(‘tag’)” 和“tags.remove(‘tag’)”来改变。只有通过 -t 命令行选项或“tags.add(‘tag’)”设置的标签可以使用 “tags.has(‘tag’)”进行查询。 请注意, 当前生成器标记在 “conf.py”中不可用, 因为它是在初始化生成器之后创建的。

项目信息

project

记录的项目名称。

author

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

“2008,Author Name”风格的版权声明。

An alias of copyright.

3.5 新版功能.

version

主要项目版本,用作“5.0.0+/60203e34a”的替代品。 例如,对于Python文档,这可能类似于“2.6”。

release

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

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

一般配置

extensions

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

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

import sys, os

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

extensions = ['extname']

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

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

source_suffix

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

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

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

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

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

注解

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

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

在 1.8 版更改: 支持文件类型映射

source_encoding

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

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

source_parsers

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

例如:

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

注解

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

1.3 新版功能.

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

master_doc

Same as root_doc.

在 4.0 版更改: Renamed master_doc to root_doc.

root_doc

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

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

在 4.0 版更改: Renamed root_doc from master_doc.

exclude_patterns

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

示例模式:

  • “‘library/xml.rst’” – 忽略 the “library/xml.rst” 文件 (替换条目 unused_docs)

  • “‘library/xml’” – 忽略“library/xml”目录

  • “‘library/xml*’” – 忽略以“library/xml”开头的所有文件和目录

  • “‘**/.svn’”–忽略所有“.svn”目录

在:confval:html_static_pathhtml_extra_path`中查找静态文件时也会查询 :confval:`exclude_patterns

1.0 新版功能.

templates_path

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

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

template_bridge

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

rst_epilog

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

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

0.6 新版功能.

rst_prolog

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

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

1.0 新版功能.

primary_domain

默认:doc:域 `</usage/restructuredtext/domains>的名称,也可以为“None”禁用默认域。默认值是 “’py’”。其他域中的对象(无论域名是显式给定的,还是由:rst:dir:`默认域 指令选择的)将在命名时显式地加上域名(例如,当默认域为 C 时,Python 函数将被命名为 “Python function”,而不仅仅是 “function”)。

1.0 新版功能.

default_role

用作默认角色的 reST 角色(内置或 Sphinx 扩展)的名称,即标记为“‘这样’”的文本,可以设置为“‘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

  • download.not_readable

  • 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.secnum

  • epub.unknown_project_files

  • epub.duplicated_toc_entry

  • autosectionlabel.*

您可以从这些类型中进行选择。

现在,这个选项应该被视为 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 版更改: Added epub.duplicated_toc_entry

needs_sphinx

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

1.0 新版功能.

在 1.4 版更改: 也接受微版本字符串

needs_extensions

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

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

1.3 新版功能.

manpages_url

交叉引用的URL manpage 指令。如果将其定义为“https://manpages.debian.org/{path}”, 则:literal::manpage:`man(1)` 角色将链接到<https://manpages.debian.org/man(1)> 。可用的模式是:

  • “page”- 手册页 (“man”)

  • “section” - 手册部分 (“1”)

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

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

注解

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

1.7 新版功能.

nitpicky

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

1.0 新版功能.

nitpick_ignore

在“nitpicky模式”下生成警告时应该忽略的(类型,目标)元组列表(默认为空)。注意,类型应该包括域名,如果存在。示例条目是“(‘py:func’, ‘int’)“或“(‘envvar’, ‘LD_LIBRARY_PATH’)”。

1.1 新版功能.

nitpick_ignore_regex

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

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

4.1 新版功能.

numfig

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

注解

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

1.3 新版功能.

numfig_format

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

默认是使用“‘Fig.%s’”为“‘figure’”, “‘Table%s’”为“‘table’”,“‘Listing%s’”为“‘code-block’”和“‘Section’”为 “‘section’”。

1.3 新版功能.

numfig_secnum_depth
  • 如果设置为“0”,则数字,表格和代码块从“1”开始连续编号。

  • 如果“1”(默认)数字将是“x.1”。“x.2”,… 与“x”的节号(顶级切片;没有“x”如果没有部分)。只有当通过 toctree 指令的“:numbered:”选项激活了段号时,这才自然适用。

  • “2”表示数字将是“x.y.1”,“x.y.2”,…如果位于子区域(但仍然是 x.1 ,x.2 ,… 如果直接位于一个部分和 1 ,2 , … 如果不在任何顶级部分。)

  • 等等…

1.3 新版功能.

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

smartquotes

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

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

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

smartquotes_action

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

1.6.6 新版功能.

smartquotes_excludes

这是一个“dict”,其默认值为:

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

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

注解

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

提示

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

make latex O="-D smartquotes_action="

这可以遵循一些“make html”没有问题,对比的情况,从前面的说明。它需要Docutils 0.14或更高版本。

1.6.6 新版功能.

user_agent

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

2.3 新版功能.

tls_verify

如果为“true”,Sphinx将验证服务器认证。

1.5 新版功能.

tls_cacerts

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

1.5 新版功能.

小技巧

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

today
today_fmt

这些值决定了如何格式化当前日期,用作“2021 年 06 月 14 日”的替换。

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

  • 否则,使用:func:time.strftime`格式化当前时间,格式为 :confval:`today_fmt

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

highlight_language

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

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

0.5 新版功能.

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

highlight_options

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

例如:

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

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

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

1.3 新版功能.

在 3.5 版更改: Allow to configure highlight options for multiple languages

pygments_style

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

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

add_function_parentheses

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

add_module_names

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

show_authors

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

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会话的所有代码块(即doctests) 。默认为“True”。有关包含 doctests 的更多可能性,请参阅扩展名:mod:~sphinx.ext.doctest

1.0 新版功能.

在 1.1 版更改: 现在也删除了“<BLANKLINE>”。

strip_signature_backslash

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

3.0 新版功能.

国际化选项

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

language

文档编写语言的代码。Sphinx自动生成的任何文本都将使用该语言。此外,Sphinx将尝试使用以下内容替换您文档中的各个段落 locale_dirs。Sphinx将搜索由 :confval:`figure_language_filename`(例如“myfigure.png”的德语版默认为“myfigure.de.png”)命名的语言特定数字,并将其替换为原始数字。在LaTeX构建器中,将选择合适的语言作为 Babel 包的选项。默认为“None”,这意味着不会进行任何翻译。

0.5 新版功能.

在 1.4 版更改: 支持数字替换

目前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” – 印度尼西亚语

  • “id” – 印度尼西亚语

  • “ja” – 日语

  • “ko” – 朝鲜语

  • “lt” – 立陶宛语

  • “lv” – 拉脱维亚语

  • “mk” – 马其顿语

  • “nb_NO” – 挪威博克马尔语

  • “ne” – 尼泊尔语

  • “nl” – 荷兰语

  • “pl” – 波兰语

  • “pt” – 葡萄牙语

  • “pt_BR – 巴西葡萄牙语

  • “pt_PT” – 欧洲葡萄牙语

  • “ro” – 罗马尼亚语

  • “ru” – 俄语

  • “si” – 僧伽罗语

  • “sk” – 斯洛伐克语

  • “sl” – 斯洛文尼亚语

  • “sq”– 阿尔巴尼亚语

  • “sr”– 塞尔维亚语

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

  • “sr_RS”– 塞尔维亚语(斯拉夫字母)

  • “sv” – 瑞典语

  • “ta”– 泰米尔语

  • “te”– 泰卢固语

  • “tr” – 土耳其语

  • “uk_UA” – 乌克兰语

  • “ur”– 乌尔都语

  • “vi” – 越南语

  • “zh_CN” – 简体中文

  • “zh_TW” – 繁体中文

locale_dirs

0.5 新版功能.

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

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

默认是“[‘locales’]”。

注解

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

在 1.5 版更改: 使用“locales”目录作为默认值。

gettext_compact

1.1 新版功能.

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

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

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

在 3.3 版更改: 字符串值现在被接受。

gettext_uuid

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

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

  • 计算新 msgids 和以前保存的旧 msgids 之间的相似性。这种计算需要很长时间。

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

默认为“False”。

1.3 新版功能.

gettext_location

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

默认值为真。

1.3 新版功能.

gettext_auto_build

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

默认值为真。

1.3 新版功能.

gettext_additional_targets

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

索引

索引条款

文字块

文字块(“::”注释和“代码块”指令)。

doctest块

doctest块

原始

原始内容

图片

图像/图的uri

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

默认是“[]”。

1.3 新版功能.

在 4.0 版更改: 默认情况下,图像的alt文本被翻译。

figure_language_filename

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

  • “{root}”- 文件名,包括任何路径组件,没有文件扩展名,例如“dirname/filename”

  • “{path}”- 文件名的目录路径组件,如果非空,则带有斜杠,例如“dirname/”

  • “{docpath}” - 当前文档的目录路径组件,如果非空,尾部有一个斜杠。

  • “{basename}”- 没有目录路径或文件扩展名组件的文件名,例如“filename”

  • “{ext}”- 文件扩展名,例如 .png

  • “{language}”- 翻译语言,例如“en”。

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

1.4 新版功能.

在 1.5 版更改: 添加了“{path}”和“{basename}”标记。

在 3.2 版更改: 添加“{docpath}”标记。

数学选项

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

math_number_all

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

math_eqref_format

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

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

math_numfig

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

1.7 新版功能.

HTML输出选项

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

html_theme

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

0.6 新版功能.

html_theme_options

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

0.6 新版功能.

html_theme_path

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

0.6 新版功能.

html_style

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

html_title

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

html_short_title

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

0.4 新版功能.

html_baseurl

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

1.8 新版功能.

html_codeblock_linenos_style

代码块的行号样式。

  • 'table' – display line numbers using <table> tag

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

3.2 新版功能.

在 4.0 版更改: It defaults to 'inline'.

4.0 版后已移除.

html_context

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

0.5 新版功能.

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

0.4.1 新版功能: 图像文件将被复制到输出HTML的“_static”目录中,但前提是该文件尚不存在。

在 4.0 版更改: Also accepts the URL for the logo file.

html_favicon

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

0.4 新版功能: 图像文件将被复制到输出HTML的“_static”目录中,但前提是该文件尚不存在。

在 4.0 版更改: Also accepts the URL for the favicon.

html_css_files

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

例如:

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

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

1.8 新版功能.

在 3.5 版更改: Support priority attribute

html_js_files

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

例如:

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

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

1.8 新版功能.

在 3.5 版更改: Support priority attribute

html_static_path

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

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

注解

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

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

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

在 0.4 版更改: 以下路径 html_static_path 现在可以包含子目录。

在 1.0 版更改: 以下条目 html_static_path 现在可以单目录。

在 1.8 版更改: 从源文件中排除:confval:`html_static_path`下的文件。

html_extra_path

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

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

1.2 新版功能.

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

html_last_updated_fmt

如果这不是None, 则使用给定的 strftime() format格式在每个页面底部插入‘Last updated on:’ 时间戳。空字符串相当于“’%b%d, %Y’”(或依赖于语言环境的等价物)。

html_use_smartypants

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

1.6 版后已移除: 要禁用智能引号, 请使用:confval:smartquotes

Sphinx将为每个标题和描述环境添加“永久链接”,作为段落标记,当鼠标悬停在它们上面时,它们就会显示出来。

该值确定永久墨水的文本;它默认为“¶”。将其设置为“None”或空字符串来禁用永久链接。

0.6 新版功能: 以前, 这总是被激活。

在 1.1 版更改: 现在可以是一个字符串来选择链接的实际文本。以前, 只接受布尔值。

3.5 版后已移除: This has been replaced by html_permalinks

If true, Sphinx will add “permalinks” for each heading and description environment. Default: True.

3.5 新版功能.

A text for permalinks for each heading and description environment. HTML tags are allowed. Default: a paragraph sign;

3.5 新版功能.

html_sidebars

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

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

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

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

    默认侧边栏(适用于与任何模式不匹配的文档)由主题本身定义。内置主题默认使用这些模板:“[‘localtoc.html’, ‘relations.html’, ‘sourcelink.html’, ‘searchbox.html’]。

  • 如果值是单个字符串, 则它指定要在“‘sourcelink.html’”和“‘searchbox.html’”条目之间添加的自定义侧边栏。这是为了与1.0之前的 Sphinx 版本兼容。

1.7 版后已移除: “html_侧边栏”的单个字符串值将在2.0中被删除

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

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

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

  • relations.html– 两个指向上一个和下一个文档的链接

  • sourcelink.html– 指向当前文档源的链接, 如果在 :confval:`html_show_sourcelink`中启用

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

例如:

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

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

1.0 新版功能: 能够使用通配键并指定多个侧边栏。

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

html_additional_pages

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

例如:

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

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

html_domain_indices

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

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

1.0 新版功能.

html_use_index

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

0.4 新版功能.

html_split_index

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

0.4 新版功能.

html_copy_source

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

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

0.6 新版功能.

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

1.5 新版功能.

html_use_opensearch

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

html_file_suffix

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

0.4 新版功能.

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

0.6 新版功能.

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

1.0 新版功能.

html_show_sphinx

如果为true,"使用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全文搜索索引的语言。默认使用:confval:`语言`选择的全局语言。如果不支持该语言,则使用“"en"”选择英语语言。

支持这些语言:

  • “da” – 丹麦语

  • “nl” – 荷兰语

  • “en” – 英语

  • “fi” – 芬兰语

  • “fr” – 法语

  • “de” – 德语

  • “hu” – 匈牙利语

  • “id” – 印度尼西亚语

  • “ja” – 日语

  • “no” – 挪威语

  • “pt” – 葡萄牙语

  • “ro” – 罗马尼亚语

  • “ru” – 俄语

  • “es” – 西班牙语

  • “sv” – 瑞典语

  • “tr” – 土耳其语

  • “zh” – 中文

加快生成速度

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

1.1 新版功能: 支持“en”和“ja”。

在 1.3 版更改: 添加了其他语言。

html_search_options

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

英语支持没有选择。

日本的支持有这些选择:

类型

type 是点模块路径字符串, 用于指定应该从以下派生的 Splitter 实现 sphinx.search.ja.BaseSplitter 。如果未指定或指定None, 将使用 “’sphinx.search.ja.DefaultSplitter’”。

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

‘sphinx.search.ja.DefaultSplitter’

TinySegmenter algorithm. 这是默认分割器。

‘sphinx.search.ja.MecabSplitter’

要使用这个拆分器, 需要 ‘mecab’ python绑定或动态链接库( ‘libmecab.so’ 用于linux, ‘libmecab.dll’ 用于windows)。

‘sphinx.search.ja.JanomeSplitter’

Janome绑定。要使用这个分离器, 需要`Janome <https://pypi.org/project/Janome/>`_。

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

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

“’mecab’”的选项:
dic_enc

dic_enc option 是MeCab算法的编码。

字典

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

lib

lib option 是用于在未安装Python绑定的情况下通过ctypes查找MeCab库的库名。

例如:

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

user_dic option 是Janome的用户词典文件路径。

user_dic_enc

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

1.1 新版功能.

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

中文的支持有这些选择:

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

html_search_scorer

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

1.2 新版功能.

如果为true, 则图像本身会链接到原始图像(如果它没有 ‘target’ 选项或缩放相关选项: ‘scale’ , ‘width’ , ‘height’ 。默认为“True”。

文档作者可以手动提供“无尺度链接”类的图像:

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

1.3 新版功能.

在 3.0 版更改: 禁用有“no-scaled-link”类的图像。

html_math_renderer

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

1.8 新版功能.

html_experimental_html5_writer

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

1.6 新版功能.

2.0 版后已移除.

html4_writer

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

单个HTML输出的选项

singlehtml_sidebars

自定义侧边栏模板必须是将文档名称映射到模板名称的字典。它只允许一个名为 ‘index’`的键。所有其他键都被忽略。有关更多信息, 请参阅:confval:`html_sidebars。默认情况下, 它与 :confval:`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 Help输出仅适用于Mac OS X 10.6及更高版本, 因为它需要 hiutilcodesign 命令行工具, 两者都不是开源的。

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

applehelp_bundle_name

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

applehelp_bundle_id

帮助手册包的软件包ID。

警告

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

applehelp_dev_region

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

applehelp_bundle_version

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

applehelp_icon

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

applehelp_kb_product

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

applehelp_kb_url

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

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

applehelp_remote_url

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

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

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

applehelp_index_anchors

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

applehelp_min_term_length

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

applehelp_stopwords

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

语言

代码

英语

en

德语

de

西班牙语

es

法语

fr

瑞典语

sv

匈牙利语

hu

意大利语

it

默认为 language, 或者如果没有设置, 则为 en 。

applehelp_locale

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

默认为 language, 或者如果没有设置, 则为 en 。

applehelp_title

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

applehelp_codesign_identity

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

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

applehelp_codesign_flags

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

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

applehelp_indexer_path

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

applehelp_codesign_path

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

applehelp_disable_external_tools

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

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

默认为“False”。

epub输出的选项

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

epub_basename

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

epub_theme

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

epub_theme_options

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

1.2 新版功能.

epub_title

文件的标题。它默认为 html_title`选项, 但可以为epub创建独立设置。它默认为:confval:`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 选项。

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

epub_identifier

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

epub_scheme

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

epub_uid

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

epub_cover

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

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

默认值为“()”。

1.1 新版功能.

epub_css_files

CSS文件列表。该条目必须是 filename 字符串或包含 filename 字符串和*attributes* 字典的元组。有关更多信息, 请参阅:confval:html_css_files

1.8 新版功能.

epub_guide

指南元素的元数据 content.opf 。这是一系列元组, 包含可选指南信息的*type*, uri*和*title。有关详细信息, 请参阅 http://idpf.org/epub 的OPF文档。如果可能, 将自动插入*cover*和*toc*类型的默认条目。但是, 如果默认条目不合适, 则可以显式覆盖类型。例:

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

默认值为“()”。

epub_pre_files

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

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

默认值为“[]”。

epub_post_files

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

epub_exclude_files

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

epub_tocdepth

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

epub_tocdup

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

epub_tocscope

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

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

  • “’includehidden’” - 包括所有toc条目

1.2 新版功能.

epub_fix_images

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

1.2 新版功能.

epub_max_image_width

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

1.2 新版功能.

epub_show_urls

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

  • “’inline’” - 在括号中显示内联网址(默认)

  • “’footnote’” - 在脚注中显示网址

  • “‘不’” - 不显示网址

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

1.2 新版功能.

epub_use_index

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

1.2 新版功能.

epub_writing_mode

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

“epub_writing_mode”

“’horizontal’”

'vertical'

writing-mode 2

horizontal-tb

vertical-rl

page progression

left to right

right to left

iBook’s 滚动主题支持

scroll-axis 是垂直的。

scroll-axis 是水平的。

2

https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode

LaTeX输出的选项

这些选项会影响LaTeX输出。

latex_engine

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

  • 'pdflatex' – PDFLaTeX (default)

  • 'xelatex' – XeLaTeX

  • 'lualatex' – LuaLaTeX

  • 'platex' – pLaTeX

  • 'uplatex' – upLaTeX (default if language is 'ja')

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

注解

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

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

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

在 2.2.1 版更改: 希腊文档默认使用“xelatex”。

在 2.3 版更改: 添加“uplatex”支持

在 4.0 版更改: uplatex becomes the default setting of Japanese documents.

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

latex_documents

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

startdocname

String that specifies the document name of the LaTeX file’s master document. All documents referenced by the startdoc document in TOC trees will be included in the LaTeX file. (If you want to use the default root document for your LaTeX build, provide your root_doc here.)

targetname

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

title

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

author

LaTeX文档的作者。相同的LaTeX标记警告 标题 适用。使用“\\and”来分隔多个作者, 例如:“’John \\and Sarah”(反斜杠必须由Python转义才能到达LaTeX)。

theme

LaTeX主题。参见:confval:latex_theme

toctree_only

必须是 True 或 False 。如果为true, 则 startdoc 文档本身不包含在输出中, 只包含通过TOC树引用的文档。使用此选项, 您可以在主文档中添加额外的内容, 这些内容显示在HTML中, 而不是LaTeX输出中。

1.2 新版功能: 过去,包含自己的文档类需要在文档类名前加上字符串“sphinx”。现在这已经没有必要了。

0.3 新版功能: 第6项“toctree only”。包含5个条目的元组仍然被接受。

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

latex_toplevel_sectioning

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

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

1.4 新版功能.

latex_appendices

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

latex_domain_indices

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

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

1.0 新版功能.

latex_show_pagerefs

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

1.0 新版功能.

latex_show_urls

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

  • “’不’” - 不显示网址(默认)

  • “’footnote’” - 在脚注中显示网址

  • “’inline’” - 在括号中内嵌显示网址

1.0 新版功能.

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

latex_use_latex_multicolumn

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

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

1.6 新版功能.

latex_use_xindy

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

  • 如果:confval:latex_engine 是“’platex’”(日语文档;mendex 替换 :program:`makeindex`则)。

  • 默认是“True”“’xelatex’”或“’lualatex’” makeindex,如果任何索引术语以非ascii字符开始,创建“.ind”。在UTF-8编码中包含无效字节的文件。“’lualatex’”这样就破坏了PDF的构建。

  • 对于“’pdflatex’”,默认为“False”,但是对于非英语文档,只要一些索引术语使用语言脚本中的非ascii字符,建议使用“True”。

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

1.8 新版功能.

latex_elements

0.5 新版功能.

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

latex_docclass

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

1.0 新版功能.

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

latex_additional_files

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

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

0.6 新版功能.

在 1.2 版更改: 这将覆盖Sphinx提供的文件,比如“Sphinx .sty”。

latex_theme

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

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

manual

用于编写手册的LaTeX主题。它导入“报告”文档类(日本文档使用“jsbook”)。

howto

用于写文章的LaTeX主题。它导入“文章”文档类(日本文档使用“jreport”’)。latex_appendices 仅用于此主题。

默认是“’manual’”。

3.0 新版功能.

latex_theme_options

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

3.1 新版功能.

latex_theme_path

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

3.0 新版功能.

文本输出选项

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

text_newlines

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

  • “’unix’”:使用Unix风格的行结尾(“n”)

  • “’windows’”:使用Windows风格的行结尾(“rn”)

  • “’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

String that specifies the document name of the manual page’s master document. All documents referenced by the startdoc document in TOC trees will be included in the manual file. (If you want to use the default root document for your manual pages build, use your root_doc here.)

name

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

description

手册页的说明。这在NAME部分中使用。

authors

包含作者或单个字符串的字符串列表。如果您不想在手册页中自动生成AUTHORS部分,则可以是空字符串或列表。

section

手册页部分。用于输出文件名以及手册页头。

1.0 新版功能.

man_show_urls

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

1.1 新版功能.

man_make_section_directory

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

3.3 新版功能.

在 4.0 版更改: The default is changed to False from True.

在 4.0.2 版更改: The default is changed to True from False again.

Texinfo输出的选项

这些选项会影响Texinfo输出。

texinfo_documents

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

startdocname

String that specifies the document name of the the Texinfo file’s master document. All documents referenced by the startdoc document in TOC trees will be included in the Texinfo file. (If you want to use the default master document for your Texinfo build, provide your root_doc here.)

targetname

输出目录中Texinfo文件的文件名(无扩展名)。

title

Texinfo文档标题。可以为空以使用*startdoc*文档的标题。作为Texinfo标记插入, 所以需要转义像“@” 和 “{}”这样的特殊字符。

author

Texinfo文档的作者。插入为Texinfo标记。使用“@*”来分隔多个作者, 如:“’John@*Sarah’”。

dir_entry

将出现在顶级“DIR”菜单文件中的名称。

description

描述性文本出现在顶级“DIR”菜单文件中。

category

指定此条目将出现在顶级“DIR”菜单文件中的部分。

toctree_only

必须是 True 或 False 。如果为true, 则 startdoc 文档本身不包含在输出中, 只包含通过TOC树引用的文档。使用此选项, 您可以在主文档中添加额外的内容, 这些内容显示在HTML中, 而不是Texinfo输出中。

1.1 新版功能.

texinfo_appendices

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

1.1 新版功能.

texinfo_domain_indices

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

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

1.1 新版功能.

texinfo_show_urls

控制如何显示URL地址。

  • “’footnote’”—在脚注中显示网址(默认)

  • “‘不’” - 不显示网址

  • “’inline’” - 在括号中内嵌显示网址

1.1 新版功能.

texinfo_no_detailmenu

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

1.2 新版功能.

texinfo_elements

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

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

    'paragraphindent'

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

    'exampleindent'

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

    “序言”

    Texinfo标记插入文件的开头附近。

    'copying'

    Texinfo标记插入“@copying”块并显示在标题之后。默认值包含标识项目的简单标题页。

  • 由其他选项设置且因此不应重写的键包括:

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

1.1 新版功能.

QtHelp输出的选项

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

qthelp_basename

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

qthelp_namespace

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

qthelp_theme

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

qthelp_theme_options

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

linkcheck生成器的选项

linkcheck_ignore

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

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

1.1 新版功能.

linkcheck_request_headers

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

关键字是一个URL基字符串,如“”https://sphinx-doc.org/”。要指定其他主机的头,可以使用””*”。它只在URL与其他设置不匹配时匹配所有主机。

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

举例如下:

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

3.1 新版功能.

linkcheck_retries

linkcheck生成器在声明URL之前尝试检查URL的次数。默认为1次尝试。

1.4 新版功能.

linkcheck_timeout

linkcheck生成器的超时值(以秒为单位)。默认是使用Python的全局套接字超时。

1.1 新版功能.

linkcheck_workers

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

1.1 新版功能.

linkcheck_anchors

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

1.2 新版功能.

linkcheck_anchors_ignore

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

注解

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

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

1.5 新版功能.

linkcheck_auth

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

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

regex_pattern

匹配URI的正则表达式。

auth_info

用于该URI的身份验证信息。该值可以是“请求”库所理解的任何值(参见 `请求身份验证 <requests-auth>`_了解详细信息)。

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

例如:

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

2.3 新版功能.

linkcheck_rate_limit_timeout

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

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

Otherwise, linkcheck waits for a minute before to retry and keeps doubling the wait time between attempts until it succeeds or exceeds the linkcheck_rate_limit_timeout. By default, the timeout is 5 minutes.

3.4 新版功能.

XML生成器的选项

xml_pretty

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

1.2 新版功能.

脚注

1(1,2)

关于可用的globbing语法的一点说明:您可以使用标准的shell结构``*``,`[…]``和`[!。。。]``这些都不匹配斜杠。双星“**”可用于匹配任何字符序列*包括*斜杠。

C域选项

c_id_attributes

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

3.0 新版功能.

c_paren_attributes

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

3.0 新版功能.

c_allow_pre_v3

一个布尔值(默认为“False”),控制是否解析和转换v3之前的样式类型指令和类型角色。

3.2 新版功能.

3.2 版后已移除: 使用v3中添加的指令和角色。

c_warn_on_allowed_pre_v3

一个布尔值(默认为“True”),用于控制在解析和转换v3之前的样式类型指令/角色时是否发出警告。

3.2 新版功能.

3.2 版后已移除: 使用v3中添加的指令和角色。

C++ 域选项

cpp_index_common_prefix

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

1.5 新版功能.

cpp_id_attributes

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

1.5 新版功能.

cpp_paren_attributes

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

1.5 新版功能.

Options for the Python domain

python_use_unqualified_type_names

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

4.0 新版功能.

注解

This configuration is still in experimental

配置文件示例

# test documentation build configuration file, created by
# sphinx-quickstart on Sun Jun 26 00:00:43 2016.
#
# This file is execfile()d 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 = u'test'
copyright = u'2016, test'
author = u'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 = u'test'
# The full version, including alpha/beta/rc tags.
release = u'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 = u'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', u'test Documentation',
     u'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', u'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', u'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

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