配置¶

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

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

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

需要注意的重要事项：

如果没有其他文档，值必须是字符串，其默认值是空字符串。
术语 “完全限定名”（fully-qualified name）指的是字符串，它命名了模块中可导入的 Python 对象；例如，FQN "sphinx.builders.Builder" 意味着 sphinx.builders 模块中的 Builder 类。
记住，文件名使用 / 作为路径分隔符，不包含文件名的扩展名。
由于 conf.py 是作为 Python 文件被读取的，通常的规则适用于编码和 Unicode 支持。
config 命名空间的内容是 pickled（这样 Sphinx 可以在配置改变时发现），所以它可能不包含 unpickleable 值 —— 如果合适的话用 del 从命名空间中删除它们。模块会被自动删除，所以你不需要在使用后 del 你的导入。
在配置文件中，有名为 tags 的特殊对象可用。它可以用来查询和改变 tags（见包含基于标记的内容）。使用 tags.has('tag') 来查询，tags.add('tag') 和 tags.remove('tag') 来改变。只有通过 -t 命令行选项或 tags.add('tag') 设置的标签可以使用 tags.has('tag') 进行查询。注意，当前的构建器 tag 在 conf.py 中是不可用的，因为它是在构建器被初始化之后创建的。

项目信息¶

project¶: 记录的项目名称。

author¶: 该文档的作者姓名。默认值是 'unknown'。

copyright¶: 风格为 '2008, Author Name' 的版权声明。

project_copyright¶: copyright 的别名。

3.5 新版功能.

version¶: 项目的主版本，用来替代 |version|。例如，对于 Python 文档，这可能是 2.6 之类的。

release¶

项目的完整版本，用来替代 |release|，例如在 HTML 模板中。例如，对于 Python 文档，这可能是 2.6.0rc1。

如果你不需要在 version 和 release 之间提供分离，只需将它们都设置为相同的值。

通用配置¶

extensions¶

一个字符串的列表，是插件的模块名称。这些可以是 Sphinx 自带的扩展（命名为 sphinx.ext.*）或自定义的。

注意，如果你的插件在另一个目录中，你可以在 conf 文件中扩展 sys.path – 但要确保你使用绝对路径。如果你的扩展路径是相对于配置目录，请使用 os.path.abspath()，像这样

import sys, os

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

extensions = ['extname']

这样，你就可以从 sphinxext 子目录中加载名为 extname 的扩展。

配置文件本身可以是插件；为此，你只需要在其中提供 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.Parser 或 sphinx.parsers.Parser。后缀不在字典中的文件将用默认的 reStructuredText 解析器进行解析。

例如

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

备注

参考 Markdown，了解更多关于在 Sphinx 中使用 Markdown 的信息。

1.3 新版功能.

1.8 版后已移除: 现在 Sphinx 提供了一个API Sphinx.add_source_parser() 来注册一个源解析器。请用它来代替。

master_doc¶: 与 root_doc 相同。

在 4.0 版更改: 将 master_doc 重命名为 root_doc。

root_doc¶: “根” 文件的文件名，即包含根 toctree 指令的文件。默认为 'index'。

在 2.0 版更改: 默认值从 'contents' 改为 'index'。

在 4.0 版更改: 从 root_doc 重命名为 master_doc。

exclude_patterns¶

在寻找源文件时应排除的 glob-style 模式的列表。1 它们与相对于源文件目录的源文件名相匹配，在所有平台上使用斜线作为目录分隔符。

模式的示例：

'library/xml.rst' – 忽略 library/xml.rst 文件（替换 unused_docs 中的条目）
'library/xml' – 忽略 library/xml 目录
'library/xml*' – 忽略所有以 library/xml 开头的文件和目录
'**/.svn' – 忽略全部的 .svn 目录

exclude_patterns 在寻找 html_static_path 和 html_extra_path 中的静态文件时也被参考。

1.0 新版功能.

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

在 1.3 版更改: 由于这些文件不是为了被构建，它们被自动添加到 exclude_patterns 中。

template_bridge¶: 一个字符串，包含一个可调用（或简单的类）的全限定名称，它返回一个 TemplateBridge 的实例。这个实例然后被用来渲染 HTML 文档，可能还有其他构建器的输出（目前是变化构建器）。（注意，如果要使用 HTML 主题，模板桥必须具有主题感知功能。）

rst_epilog¶

一串 reStructuredText，它将被包含在每个被读取的源文件的末尾。这是一个可以添加替换的地方，应该在每个文件中都有（另一个是 rst_prolog）。一个例子：

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

0.6 新版功能.

rst_prolog¶

一个 reStructuredText 的字符串，它将被包含在每个被读取的源文件的开头。这是一个可以添加替换的地方，应该在每个文件中都有（另一个是 rst_epilog）。一个例子：

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

1.0 新版功能.

primary_domain¶: 默认的域的名称。也可以是 None，以停用默认域。默认是 'py'。那些在其他域中的对象（无论域名是明确给出的，还是由 default-domain 指令选择的），在命名时都会明确预留域名（例如，当默认域是 C 时，Python 函数将被命名为 “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
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.excluded
toc.not_readable
toc.secnum
epub.unknown_project_files
epub.duplicated_toc_entry
autosectionlabel.*

你可以从这些类型中选择。

现在，这个选项应该被认为是 实验性的。

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 版更改: Added toc.excluded and toc.not_readable

needs_sphinx¶: 如果设置为一个 major.minor 的版本字符串，如 '1.1'，Sphinx 将与它的版本进行比较，如果它太旧，就拒绝构建。默认是没有要求。

1.0 新版功能.

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

needs_extensions¶

这个值可以是一个字典，指定 extensions 中的扩展的版本要求，例如 needs_extensions = {'sphinxcontrib.something': '1.5'}。版本字符串应该是 “major.minor” 的形式。不需要为所有扩展指定要求，只需要为那些你想检查的扩展指定。

这需要扩展向 Sphinx 指定它的版本（如何做到这一点，见为 Sphinx 开发插件）。

1.3 新版功能.

manpages_url¶

一个用于交叉引用 manpage 角色的 URL。如果这个定义为 https://manpages.debian.org/{path}，那么 :manpage:`man(1)` 角色将链接到 <https://manpages.debian.org/man(1)>。可用的模式有：

page - 手册页面（man）

章节 - 手册章节（1）

path - 原有手册中指定的页面和章节（man(1)）

这也支持指定为 man.1 的手册页。

备注

目前这只影响到 HTML 写作者，但将来可能会扩大。

1.7 新版功能.

nitpicky¶: 如果是真的，Sphinx 会对所有找不到目标的引用发出警告。默认是 False。你可以用 -n 命令行开关暂时激活这个模式。

1.0 新版功能.

nitpick_ignore¶: 一个 (type, target) 元组的列表（默认为空），在 “nitpicky mode” 下生成警告的时候应该被忽略。请注意，type 如果存在，应该包括域名。例子是 ('py:func', 'int') 或 ('envvar', 'LD_LIBRARY_PATH')。

1.1 新版功能.

nitpick_ignore_regex¶

nitpick_ignore 的扩展版本，它将 type 和 target 字符串解释为正则表达式。注意，正则表达式必须匹配整个字符串（就像插入了 ^ 和 $ 标记）。

例如，(r'py:.*', r'foo.*bar\.B.*') 将忽略所有以 'foo' 开头且有 'bar.B' 的 python 实体的挑剔警告，例如 ('py:const', 'foo_package.bar.BAZ_VALUE') 或 ('py:class', 'food.bar.Barman')。

4.1 新版功能.

numfig¶: 如果是 true，数字、表格和代码块如果有标题就会自动编号。numref 角色被启用。到目前为止，只被 HTML 和 LaTeX 生成器所服从。默认是 False。

备注

The LaTeX builder always assigns numbers whether this option is enabled or not.

1.3 新版功能.

numfig_format¶

A dictionary mapping 'figure', 'table', 'code-block' and 'section' to strings that are used for format of figure numbers. As a special character, %s will be replaced to figure number.

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

1.3 新版功能.

numfig_secnum_depth¶

if set to 0, figures, tables and code-blocks are continuously numbered starting at 1.
if 1 (default) numbers will be x.1, x.2, … with x the section number (top level sectioning; no x. if no section). This naturally applies only if section numbering has been activated via the :numbered: option of the toctree directive.
2 means that numbers will be x.y.1, x.y.2, … if located in a sub-section (but still x.1, x.2, … if located directly under a section and 1, 2, … if not in any top level section.)
etc…

1.3 新版功能.

在 1.7 版更改: The LaTeX builder obeys this setting (if numfig is set to True).

smartquotes¶

If true, the Docutils Smart Quotes transform, originally based on SmartyPants (limited to English) and currently applying to many languages, will be used to convert quotes and dashes to typographically correct entities. Default: True.

1.6.6 新版功能: It replaces deprecated html_use_smartypants. It applies by default to all builders except man and text (see 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. But if it activates them, then smartquotes does prevail.

smartquotes_action¶: This string customizes the Smart Quotes transform. See the file smartquotes.py at the Docutils repository for details. The default 'qDe' educates normal quote characters ", ', em- and en-Dashes ---, --, and ellipses ....

1.6.6 新版功能.

smartquotes_excludes¶

This is a dict whose default is:

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

Each entry gives a sufficient condition to ignore the smartquotes setting and deactivate the Smart Quotes transform. Accepted keys are as above 'builders' or 'languages'. The values are lists.

备注

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

提示

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

make latex O="-D smartquotes_action="

This can follow some make html with no problem, in contrast to the situation from the prior note. It requires Docutils 0.14 or later.

1.6.6 新版功能.

user_agent¶: A User-Agent of Sphinx. It is used for a header on HTTP access (ex. linkcheck, intersphinx and so on). Default is "Sphinx/X.Y.Z requests/X.Y.Z python/X.Y.Z".

2.3 新版功能.

tls_verify¶: If true, Sphinx verifies server certifications. Default is True.

1.5 新版功能.

tls_cacerts¶: A path to a certification file of CA or a path to directory which contains the certificates. This also allows a dictionary mapping hostname to the path to certificate file. The certificates are used to verify server certifications.

1.5 新版功能.

小技巧

Sphinx uses requests as a HTTP library internally. Therefore, Sphinx refers a certification file on the directory pointed REQUESTS_CA_BUNDLE environment variable if tls_cacerts not set.

today¶

today_fmt¶

These values determine how to format the current date, used as the replacement for |today|.

If you set today to a non-empty value, it is used.
Otherwise, the current time is formatted using time.strftime() and the format given in 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.

Example:

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¶: The style name to use for Pygments highlighting of source code. If not set, either the theme’s default style or 'sphinx' is selected for HTML output.

在 0.3 版更改: If the value is a fully-qualified name of a custom Pygments style class, this is then used as custom style.

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

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

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

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

0.6 新版功能.

trim_footnote_reference_space¶: Trim spaces before footnote references that are necessary for the reST parser to recognize the footnote, but do not look too nice in the output.

0.6 新版功能.

trim_doctest_flags¶: If true, doctest flags (comments looking like # doctest: FLAG, ...) at the ends of lines and <BLANKLINE> markers are removed for all code blocks showing interactive Python sessions (i.e. doctests). Default is True. See the extension doctest for more possibilities of including doctests.

1.0 新版功能.

在 1.1 版更改: Now also removes <BLANKLINE>.

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

3.0 新版功能.

Options for internationalization¶

These options influence Sphinx’s Native Language Support. See the documentation on 国际化 for details.

language¶

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

0.5 新版功能.

在 1.4 版更改: Support figure substitution

Currently supported languages by Sphinx are:

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

locale_dirs¶

0.5 新版功能.

Directories in which to search for additional message catalogs (see language), relative to the source directory. The directories on this path are searched by the standard gettext module.

Internal messages are fetched from a text domain of sphinx; so if you add the directory ./locale to this setting, the message catalogs (compiled from .po format using msgfmt) must be in ./locale/language/LC_MESSAGES/sphinx.mo. The text domain of individual documents depends on gettext_compact.

The default is ['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 版更改: Use locales directory as a default value

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

4.3 新版功能.

gettext_compact¶

1.1 新版功能.

If true, a document’s text domain is its docname if it is a top-level project file and its very base directory otherwise.

If set to string, all document’s text domain is this string, making all documents use single text domain.

By default, the document markup/code.rst ends up in the markup text domain. With this option set to False, it is markup/code.

在 3.3 版更改: The string value is now accepted.

gettext_uuid¶

If true, Sphinx generates uuid information for version tracking in message catalogs. It is used for:

Add uid line for each msgids in .pot files.
Calculate similarity between new msgids and previously saved old msgids. This calculation takes a long time.

If you want to accelerate the calculation, you can use python-levenshtein 3rd-party package written in C by using pip install python-levenshtein.

The default is False.

1.3 新版功能.

gettext_location¶

If true, Sphinx generates location information for messages in message catalogs.

The default is True.

1.3 新版功能.

gettext_auto_build¶

If true, Sphinx builds mo file for each translation catalog files.

The default is True.

1.3 新版功能.

gettext_additional_targets¶

To specify names to enable gettext extracting and translation applying for i18n additionally. You can specify below names:

Index: index terms
Literal-block: literal blocks (:: annotation and code-block directive)
Doctest-block: doctest block
Raw: raw content
Image: image/figure uri

For example: gettext_additional_targets = ['literal-block', 'image'].

The default is [].

1.3 新版功能.

在 4.0 版更改: The alt text for image is translated by default.

figure_language_filename¶

The filename format for language-specific figures. The default value is {root}.{language}{ext}. It will be expanded to dirname/filename.en.png from .. image:: dirname/filename.png. The available format tokens are:

{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} - the directory path component for the current document, with a trailing slash if non-empty.
{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

For example, setting this to {path}{language}/{basename}{ext} will expand to dirname/en/filename.png instead.

1.4 新版功能.

在 1.5 版更改: Added {path} and {basename} tokens.

在 3.2 版更改: Added {docpath} token.

Options for Math¶

These options influence Math notations.

math_number_all¶: Set this option to True if you want all displayed math to be numbered. The default is False.

math_eqref_format¶

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

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

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

1.7 新版功能.

HTML 输出选项¶

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

html_theme¶: HTML 输出应该使用的 “theme”。参见关于主题部分。默认值是 'alabaster'。

0.6 新版功能.

html_theme_options¶: 影响选定主题的外观和感觉的选项字典。这些都是主题特定的。关于内置主题所理解的选项，请参见这部分。

0.6 新版功能.

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

0.6 新版功能.

html_style¶: 用于 HTML 页面的样式表。该名称的文件必须存在于 Sphinx 的 static/ 路径中，或在 html_static_path 中给出的自定义路径之一中。默认是所选主题给出的样式表。如果你只想添加或覆盖一些与主题样式表相比较的东西，使用 CSS @import 来导入主题的样式表。

html_title¶: “title” 用于使用 Sphinx 自己的模板生成的 HTML 文档。它被附加到单个页面的 <title> tag 上，并在导航栏中作为 “topmost” 元素使用。它默认为 '<project> v<revision> documentation'。

html_short_title¶: 更短的 “title” 用于 HTML 文档。这用于 header 和 HTML 帮助文档中的链接。如果没有给出，它的默认值为 html_title。

0.4 新版功能.

html_baseurl¶: 指向 HTML 文档根部的 base URL。它用于使用 The Canonical Link Relation 来表示文档的位置。默认值：''。

1.8 新版功能.

html_codeblock_linenos_style¶

代码块的行号样式。

'table' – 使用 <table> tag 显示行号
'inline' – 使用 <span> tag 显示行号

3.2 新版功能.

在 4.0 版更改: 默认为 'inline'。

4.0 版后已移除.

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

0.5 新版功能.

html_logo¶: 如果给定，这必须是图像文件的名称（相对于 configuration directory 的路径），也就是 docs 的 logo，或者指向 logo 的图像文件的 URL。它被放置在侧边栏的顶部；因此，它的宽度不应超过 200 像素。默认值：None。

0.4.1 新版功能: 图像文件将被复制到输出 HTML 的 _static 目录，但只有在该文件不存在的情况下。

在 4.0 版更改: 也接受 logo 文件的 URL。

html_favicon¶: 如果给定，这必须是图像文件的名称（相对于 configuration directory 的路径），即文档的 favicon，或指向 favicon 的图像文件的 URL。现代浏览器使用它作为标签、窗口和书签的图标。它应该是 Windows 风格的图标文件（.ico），大小为 16x16 或 32x32 像素。默认值：None。

0.4 新版功能: 图像文件将被复制到输出 HTML 的 _static 目录，但只有在该文件不存在的情况下。

在 4.0 版更改: 也接受 favicon 的 URL。

html_css_files¶

CSS 文件列表。条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典的元组。filename 必须相对于 html_static_path，或者完整的 URI，例如 https://example.org/style.css。这些 attributes 用于 <link> tag 的属性。它默认为空列表。

Example:

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

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

1.8 新版功能.

在 3.5 版更改: 支持 priority 属性

html_js_files¶

JavaScript filename 列表。条目必须是 filename 字符串或包含 filename 字符串和 attributes 字典的元组。filename 必须相对于 html_static_path，或者完整的 URI，例如 https://example.org/script.js。这些 attributes 用于 <script> tag 的属性。它默认为空列表。

Example:

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

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

1.8 新版功能.

在 3.5 版更改: 支持 priority 属性

html_static_path¶

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

因为这些文件不是用来构建的，所以它们会被自动排除在源文件之外。

备注

出于安全原因，将不会复制 html_static_path 下的 dotfiles。如果你想故意复制它们，请将每个文件路径添加到这个设置

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

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

在 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 版更改: 额外目录中的 dotfiles 将被复制到输出目录中。它引用 exclude_patterns 来复制额外的文件和目录，如果路径匹配模式则忽略。

html_last_updated_fmt¶: 如果这不是 None，则使用给定的 strftime() 格式在每个页面底部插入 ‘Last updated on:’ 时间戳。空字符串相当于 '%b %d, %Y' （或 locale-dependent 的等效值）。

html_use_smartypants¶: 如果为 true，引号和破折号将被转换为排版正确的实体。默认值： True。

1.6 版后已移除: To disable smart quotes, use rather smartquotes.

html_add_permalinks¶

Sphinx will add “permalinks” for each heading and description environment as paragraph signs that become visible when the mouse hovers over them.

This value determines the text for the permalink; it defaults to "¶". Set it to None or the empty string to disable permalinks.

0.6 新版功能: Previously, this was always activated.

在 1.1 版更改: This can now be a string to select the actual text of the link. Previously, only boolean values were accepted.

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

html_permalinks¶: 如果为 true，Sphinx 将为每个标题和描述环境添加 “永久链接”。默认值： True。

3.5 新版功能.

html_permalinks_icon¶: 每个标题和描述环境的永久链接文本。允许使用 HTML 标记。默认值：段落符号; ¶

3.5 新版功能.

html_sidebars¶

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

键可以包含 glob-style 模式 1，在这种情况下，所有匹配的文档都会得到指定的侧边栏。（当任何文档有一个以上的 glob-style 模式匹配时，会发出一个警告。）

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

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

默认的侧边栏（对于不符合任何模式的文件）是由主题本身定义的。内置的主题是由默认使用的模板：['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']。
如果一个值是一个单一的字符串，它指定了一个自定义的侧边栏，将被添加到 'sourcelink.html' 和 'searchbox.html' 条目之间。这是为了与 1.0 之前的 Sphinx 版本兼容。

1.7 版后已移除: html_sidebars 的单一字符串值将在 2.0 中被删除。

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

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

Example:

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

这将呈现自定义模板 windowssidebar.html 和快速搜索框在给定文档的侧边栏内，并为所有其他页面呈现默认的侧边栏（除了本地 TOC 被全局 TOC 取代）。

1.0 新版功能: 能够使用 globbing 键和指定多个侧边栏。

请注意，只有在所选主题不具备侧边栏的情况下，这个值才没有影响，比如内置的 scrolls 和 haiku 主题。

html_additional_pages¶

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

Example:

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

This will render the template customdownload.html as the page download.html.

html_domain_indices¶

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

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

1.0 新版功能.

html_use_index¶: If true, add an index to the HTML documents. Default is True.

0.4 新版功能.

html_split_index¶: If true, the index is generated twice: once as a single page with all the entries, and once as one page per starting letter. Default is False.

0.4 新版功能.

html_copy_source¶: If true, the reST sources are included in the HTML build as _sources/name. The default is True.

html_show_sourcelink¶: If true (and html_copy_source is true as well), links to the reST sources will be added to the sidebar. The default is True.

0.6 新版功能.

html_sourcelink_suffix¶: Suffix to be appended to source links (see html_show_sourcelink), unless they have this suffix already. Default is '.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¶: This is the file name suffix for generated HTML files. The default is ".html".

0.4 新版功能.

html_link_suffix¶: Suffix for generated links to HTML files. The default is whatever html_file_suffix is set to; it can be set differently (e.g. to support different web server setups).

0.6 新版功能.

html_show_copyright¶: If true, “(C) Copyright …” is shown in the HTML footer. Default is True.

1.0 新版功能.

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

4.5 新版功能.

html_show_sphinx¶: If true, “Created using Sphinx” is shown in the HTML footer. Default is True.

0.4 新版功能.

html_output_encoding¶: Encoding of HTML output files. Default is 'utf-8'. Note that this encoding name must both be a valid Python encoding name and a valid HTML charset value.

1.0 新版功能.

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

1.0 新版功能.

html_secnumber_suffix¶: Suffix for section numbers. Default: ". ". Set to " " to suppress the final dot on section numbers.

1.0 新版功能.

html_search_language¶

Language to be used for generating the HTML full-text search index. This defaults to the global language selected with language. If there is no support for this language, "en" is used which selects the English language.

Support is present for these languages:

da – Danish
nl – Dutch
en – English
fi – Finnish
fr – French
de – German
hu – Hungarian
it – Italian
ja – Japanese
no – Norwegian
pt – Portuguese
ro – Romanian
ru – Russian
es – Spanish
sv – Swedish
tr – Turkish
zh – Chinese

Accelerating build speed

Each language (except Japanese) provides its own stemming algorithm. Sphinx uses a Python implementation by default. You can use a C implementation to accelerate building the index file.

PorterStemmer (en)
PyStemmer (all languages)

1.1 新版功能: With support for en and ja.

在 1.3 版更改: Added additional languages.

html_search_options¶

A dictionary with options for the search language support, empty by default. The meaning of these options depends on the language selected.

The English support has no options.

The Japanese support has these options:

Type

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

You can choose from these modules:

‘sphinx.search.ja.DefaultSplitter’: TinySegmenter algorithm. This is default splitter.
‘sphinx.search.ja.MecabSplitter’: MeCab binding. To use this splitter, ‘mecab’ python binding or dynamic link library (‘libmecab.so’ for linux, ‘libmecab.dll’ for windows) is required.
‘sphinx.search.ja.JanomeSplitter’: Janome binding. To use this splitter, Janome is required.

1.6 版后已移除: 'mecab', 'janome' and 'default' is deprecated. To keep compatibility, 'mecab', 'janome' and 'default' are also acceptable.

Other option values depend on splitter value which you choose.

Options for 'mecab':

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

例如

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

Options for 'janome':

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

1.1 新版功能.

在 1.4 版更改: html_search_options for Japanese is re-organized and any custom splitter can be used by type settings.

The Chinese support has these options:

dict – the jieba dictionary path if want to use custom dictionary.

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

1.2 新版功能.

html_scaled_image_link¶

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

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

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

1.3 新版功能.

在 3.0 版更改: It is disabled for images having no-scaled-link class

html_math_renderer¶: The name of math_renderer extension for HTML output. The default is 'mathjax'.

1.8 新版功能.

html_experimental_html5_writer¶: Output is processed with HTML5 writer. Default is False.

1.6 新版功能.

2.0 版后已移除.

html4_writer¶: Output is processed with HTML4 writer. Default is False.

Options for Single HTML output¶

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

Options for HTML help output¶

htmlhelp_basename¶: Output file base name for HTML help builder. Default is 'pydoc'.

htmlhelp_file_suffix¶: This is the file name suffix for generated HTML help files. The default is ".html".

2.0 新版功能.

htmlhelp_link_suffix¶: Suffix for generated links to HTML files. The default is ".html".

2.0 新版功能.

Options for Apple Help output¶

1.3 新版功能.

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

备注

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

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

applehelp_bundle_name¶: The basename for the Apple Help Book. Defaults to the project name.

applehelp_bundle_id¶: The bundle ID for the help book bundle.

警告

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

applehelp_dev_region¶: The development region. Defaults to 'en-us', which is Apple’s recommended setting.

applehelp_bundle_version¶: The bundle version (as a string). Defaults to '1'.

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

applehelp_kb_product¶: The product tag for use with applehelp_kb_url. Defaults to '<project>-<release>'.

applehelp_kb_url¶

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

Defaults to None for no remote search.

applehelp_remote_url¶

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

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

Defaults to None for no remote content.

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

applehelp_min_term_length¶: Controls the minimum term length for the help indexer. Defaults to None, which means the default will be used.

applehelp_stopwords¶

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

Language	Code
English	en
German	de
Spanish	es
French	fr
Swedish	sv
Hungarian	hu
Italian	it

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

applehelp_locale¶

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

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

applehelp_title¶: Specifies the help book title. Defaults to '<project> Help'.

applehelp_codesign_identity¶

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

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

applehelp_codesign_flags¶

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

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

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

applehelp_codesign_path¶: The path to the codesign program. Defaults to '/usr/bin/codesign'.

applehelp_disable_external_tools¶

If True, the builder will not run the indexer or the code signing tool, no matter what other settings are specified.

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

Defaults to False.

Options for epub output¶

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¶: The basename for the epub file. It defaults to the project name.

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

epub_theme_options¶: 影响选定主题的外观和感觉的选项字典。这些都是主题特定的。关于内置主题所理解的选项，请参见这部分。

1.2 新版功能.

epub_title¶: The title of the document. It defaults to the html_title option but can be set independently for epub creation. It defaults to the project option.

在 2.0 版更改: It defaults to the project option.

epub_description¶: The description of the document. The default value is 'unknown'.

1.4 新版功能.

在 1.5 版更改: Renamed from epub3_description

epub_author¶: The author of the document. This is put in the Dublin Core metadata. It defaults to the author option.

epub_contributor¶: The name of a person, organization, etc. that played a secondary role in the creation of the content of an EPUB Publication. The default value is 'unknown'.

1.4 新版功能.

在 1.5 版更改: Renamed from epub3_contributor

epub_language¶: The language of the document. This is put in the Dublin Core metadata. The default is the language option or 'en' if unset.

epub_publisher¶: The publisher of the document. This is put in the Dublin Core metadata. You may use any sensible string, e.g. the project homepage. The defaults to the author option.

epub_copyright¶: The copyright of the document. It defaults to the copyright option but can be set independently for epub creation.

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

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

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

epub_cover¶

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

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

The default value is ().

1.1 新版功能.

epub_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. For more information, see html_css_files.

1.8 新版功能.

epub_guide¶

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

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

The default value is ().

epub_pre_files¶

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

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

The default value is [].

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

epub_exclude_files¶: A list of files that are generated/copied in the build directory but should not be included in the epub file. The default value is [].

epub_tocdepth¶: The depth of the table of contents in the file toc.ncx. It should be an integer greater than zero. The default value is 3. Note: A deeply nested table of contents may be difficult to navigate.

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

epub_tocscope¶

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

'default' – include all toc entries that are not hidden (default)
'includehidden' – include all toc entries

1.2 新版功能.

epub_fix_images¶: This flag determines if sphinx should try to fix image formats that are not supported by some epub readers. At the moment palette images with a small color table are upgraded. You need Pillow, the Python Image Library, installed to use this option. The default value is False because the automatic conversion may lose information.

1.2 新版功能.

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

1.2 新版功能.

epub_show_urls¶

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

'inline' – display URLs inline in parentheses (default)
'footnote' – display URLs in footnotes
'no' – do not display URLs

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

1.2 新版功能.

epub_use_index¶: If true, add an index to the epub document. It defaults to the html_use_index option but can be set independently for epub creation.

1.2 新版功能.

epub_writing_mode¶

It specifies writing direction. It can accept 'horizontal' (default) and 'vertical'

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

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

Options for LaTeX output¶

These options influence LaTeX output.

latex_engine¶

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

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

'pdflatex'‘s support for Unicode characters is limited.

备注

2.0 adds to 'pdflatex' support in Latin language document of occasional Cyrillic or Greek letters or words. This is not automatic, see the discussion of the latex_elements 'fontenc' key.

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

在 2.1.0 版更改: Use xelatex (and LaTeX package xeCJK) by default for Chinese documents.

在 2.2.1 版更改: Use xelatex by default for Greek documents.

在 2.3 版更改: Add uplatex support.

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

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¶

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

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

1.2 新版功能: In the past including your own document class required you to prepend the document class name with the string “sphinx”. This is not necessary anymore.

0.3 新版功能: The 6th item toctree_only. Tuples with 5 items are still accepted.

latex_logo¶: If given, this must be the name of an image file (relative to the configuration directory) that is the logo of the docs. It is placed at the top of the title page. Default: None.

latex_toplevel_sectioning¶

This value determines the topmost sectioning unit. It should be chosen from 'part', 'chapter' or 'section'. The default is None; the topmost sectioning unit is switched by documentclass: section is used if documentclass will be howto, otherwise chapter will be used.

Note that if LaTeX uses \part command, then the numbering of sectioning units one level deep gets off-sync with HTML numbering, because LaTeX numbers continuously \chapter (or \section for howto.)

1.4 新版功能.

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

latex_domain_indices¶

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

This value can be a bool or a list of index names that should be generated, like for html_domain_indices.

1.0 新版功能.

latex_show_pagerefs¶: If true, add page references after internal references. This is very useful for printed copies of the manual. Default is False.

1.0 新版功能.

latex_show_urls¶

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

'no' – do not display URLs (default)
'footnote' – display URLs in footnotes
'inline' – display URLs inline in parentheses

1.0 新版功能.

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

latex_use_latex_multicolumn¶

The default is False: it means that Sphinx’s own macros are used for merged cells from grid tables. They allow general contents (literal blocks, lists, blockquotes, …) but may have problems if the tabularcolumns directive was used to inject LaTeX mark-up of the type >{..}, <{..}, @{..} as column specification.

Setting to True means to use LaTeX’s standard \multicolumn; this is incompatible with literal blocks in the horizontally merged cell, and also with multiple paragraphs in such cell if the table is rendered using tabulary.

1.6 新版功能.

latex_use_xindy¶

If True, the PDF build from the LaTeX files created by Sphinx will use xindy (doc) rather than makeindex for preparing the index of general terms (from index usage). This means that words with UTF-8 characters will get ordered correctly for the language.

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

Sphinx adds to xindy base distribution some dedicated support for using 'pdflatex' engine with Cyrillic scripts. And whether with 'pdflatex' or Unicode engines, Cyrillic documents handle correctly the indexing of Latin names, even with diacritics.

1.8 新版功能.

latex_elements¶: 0.5 新版功能.

Its documentation has moved to LaTeX customization.

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

1.0 新版功能.

在 1.5 版更改: In Japanese docs (language is 'ja'), by default 'jreport' is used for 'howto' and 'jsbook' for 'manual'.

latex_additional_files¶

A list of file names, relative to the configuration directory, to copy to the build directory when building LaTeX output. This is useful to copy files that Sphinx doesn’t copy automatically, e.g. if they are referenced in custom LaTeX added in latex_elements. Image files that are referenced in source files (e.g. via .. image::) are copied automatically.

You have to make sure yourself that the filenames don’t collide with those of any automatically copied files.

0.6 新版功能.

在 1.2 版更改: This overrides the files which is provided from Sphinx such as sphinx.sty.

latex_theme¶

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

As a built-in LaTeX themes, manual and howto are bundled.

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

It defaults to 'manual'.

3.0 新版功能.

latex_theme_options¶: A dictionary of options that influence the look and feel of the selected theme.

3.1 新版功能.

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

3.0 新版功能.

Options for text output¶

These options influence text output.

text_newlines¶

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

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

Default: 'unix'.

1.1 新版功能.

text_sectionchars¶

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

The default is '*=-~"+`'.

1.1 新版功能.

text_add_secnumbers¶: A boolean that decides whether section numbers are included in text output. Default is True.

1.7 新版功能.

text_secnumber_suffix¶: Suffix for section numbers in text output. Default: ". ". Set to " " to suppress the final dot on section numbers.

1.7 新版功能.

Options for manual page output¶

These options influence manual page output.

man_pages¶

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

startdocname: String that specifies the document name of the manual page’s master document. All documents referenced by the startdoc document in TOC trees will be included in the manual file. (If you want to use the default root document for your manual pages build, use your root_doc here.)
name: Name of the manual page. This should be a short string without spaces or special characters. It is used to determine the file name as well as the name of the manual page (in the NAME section).
description: Description of the manual page. This is used in the NAME section. Can be an empty string if you do not want to automatically generate the NAME section.
authors: A list of strings with authors, or a single string. Can be an empty string or list if you do not want to automatically generate an AUTHORS section in the manual page.
section: The manual page section. Used for the output file name as well as in the manual page header.

1.0 新版功能.

man_show_urls¶: If true, add URL addresses after links. Default is 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.

Options for Texinfo output¶

These options influence Texinfo output.

texinfo_documents¶

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

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

1.1 新版功能.

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

1.1 新版功能.

texinfo_domain_indices¶

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

This value can be a bool or a list of index names that should be generated, like for html_domain_indices.

1.1 新版功能.

texinfo_show_urls¶

Control how to display URL addresses.

'footnote' – display URLs in footnotes (default)
'no' – do not display URLs
'inline' – display URLs inline in parentheses

1.1 新版功能.

texinfo_no_detailmenu¶: If true, do not generate a @detailmenu in the “Top” node’s menu containing entries for each sub-node in the document. Default is False.

1.2 新版功能.

texinfo_elements¶

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

Keys that you may want to override include:

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

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

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

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

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

1.1 新版功能.

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

4.4 新版功能.

Options for QtHelp output¶

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

qthelp_basename¶: The basename for the qthelp file. It defaults to the project name.

qthelp_namespace¶: The namespace for the qthelp file. It defaults to org.sphinx.<project_name>.<project_version>.

qthelp_theme¶: The HTML theme for the qthelp output. This defaults to 'nonav'.

qthelp_theme_options¶: 影响选定主题的外观和感觉的选项字典。这些都是主题特定的。关于内置主题所理解的选项，请参见这部分。

Options for the linkcheck builder¶

linkcheck_ignore¶

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

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

1.1 新版功能.

linkcheck_allowed_redirects¶

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

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

例如：

linkcheck_allowed_redirects = {
    # All HTTP redirections from the source URI to the canonical URI will be treated as "working".
    r'https://sphinx-doc\.org/.*': r'https://sphinx-doc\.org/en/master/.*'
}

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

4.1 新版功能.

linkcheck_request_headers¶

A dictionary that maps baseurls to HTTP request headers.

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

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

例如：

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

3.1 新版功能.

linkcheck_retries¶: The number of times the linkcheck builder will attempt to check a URL before declaring it broken. Defaults to 1 attempt.

1.4 新版功能.

linkcheck_timeout¶: A timeout value, in seconds, for the linkcheck builder. The default is to use Python’s global socket timeout.

1.1 新版功能.

linkcheck_workers¶: The number of worker threads to use when checking links. Default is 5 threads.

1.1 新版功能.

linkcheck_anchors¶: If true, check the validity of #anchors in links. Since this requires downloading the whole document, it’s considerably slower when enabled. Default is True.

1.2 新版功能.

linkcheck_anchors_ignore¶

A list of regular expressions that match anchors Sphinx should skip when checking the validity of anchors in links. This allows skipping anchors that a website’s JavaScript adds to control dynamic pages or when triggering an internal REST request. Default is ["^!"].

备注

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

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

1.5 新版功能.

linkcheck_auth¶

Pass authentication information when doing a linkcheck build.

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

regex_pattern: A regular expression that matches a URI.
auth_info: Authentication information to use for that URI. The value can be anything that is understood by the requests library (see requests Authentication for details).

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

Example:

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 新版功能.

linkcheck_exclude_documents¶

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

Example:

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

4.4 新版功能.

Options for the XML builder¶

xml_pretty¶: If true, pretty-print the XML. Default is True.

1.2 新版功能.

Footnotes

1(1,2): A note on available globbing syntax: you can use the standard shell constructs *, ?, [...] and [!...] with the feature that these all don’t match slashes. A double star ** can be used to match any sequence of characters including slashes.

Options for the C domain¶

c_id_attributes¶: A list of strings that the parser additionally should accept as attributes. This can for example be used when attributes have been #define d for portability.

3.0 新版功能.

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

3.0 新版功能.

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

4.0.3 新版功能.

c_allow_pre_v3¶: A boolean (default False) controlling whether to parse and try to convert pre-v3 style type directives and type roles.

3.2 新版功能.

3.2 版后已移除: Use the directives and roles added in v3.

c_warn_on_allowed_pre_v3¶: A boolean (default True) controlling whether to warn when a pre-v3 style type directive/role is parsed and converted.

3.2 新版功能.

3.2 版后已移除: Use the directives and roles added in v3.

Options for the C++ domain¶

cpp_index_common_prefix¶: A list of prefixes that will be ignored when sorting C++ objects in the global index. For example ['awesome_lib::'].

1.5 新版功能.

cpp_id_attributes¶: A list of strings that the parser additionally should accept as attributes. This can for example be used when attributes have been #define d for portability.

1.5 新版功能.

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

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

Example of configuration file¶

# 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 = 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

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

目录

上一个主题

下一个主题

本页

配置¶

项目信息¶

通用配置¶

Options for internationalization¶

Options for Math¶

HTML 输出选项¶

Options for Single HTML output¶

Options for HTML help output¶

Options for Apple Help output¶

Options for epub output¶

Options for LaTeX output¶

Options for text output¶

Options for manual page output¶

Options for Texinfo output¶

Options for QtHelp output¶

Options for the linkcheck builder¶

Options for the XML builder¶

Options for the C domain¶

Options for the C++ domain¶

Options for the Python domain¶

Example of configuration file¶