配置

The configuration directory must contain a file named conf.py. This file (containing Python code) is called the “build configuration file” and contains (almost) all configuration needed to customize Sphinx input and output behavior.

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

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

重点要注意:

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

  • The term “fully-qualified name” refers to a string that names an importable Python object inside a module; for example, the FQN "sphinx.builders.Builder" means the Builder class in the sphinx.builders module.

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

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

  • 挑选config命名空间的内容(以便Sphinx可以在配置更改时找到), 因此它可能不包含不可删除的值 - 如果合适, 可以使用 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 风格的版权声明.

version

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

release

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

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

一般配置项

extensions

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

请注意, 如果扩展名位于另一个目录中, 则可以在conf文件中扩展 sys.path - 但请确保使用绝对路径。 如果您的扩展路径是相对于 configuration directory , 请使用 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'} .

注解

文件扩展名必须以点开头 (e.g. .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

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

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

exclude_patterns

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

示例模式:

  • 'library/xml.rst' – 忽略 library/xml.rst 文件(替换条目 unused_docs)

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

  • 'library/xml*' – 忽略以 library/xml 开头的所有文件和目录

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

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

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

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

1.0 新版功能.

default_role

The name of a reST role (builtin or Sphinx extension) to use as the default role, that is, for text marked up `like this`. This can be set to 'py:obj' to make `filter` a cross-reference to the Python function “filter”. The default is None, which doesn’t reassign the default role.

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

0.4 新版功能.

keep_warnings

If true, keep warnings as “system message” paragraphs in the built documents. Regardless of this setting, warnings are always written to the standard error stream when sphinx-build is run.

默认为 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.secnum

  • epub.unknown_project_files

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

现在, 这个选项应该被视为 experimental。

1.4 新版功能.

在 1.5 版更改: 添加 misc.highlighting_failure

在 1.5.1 版更改: 添加 epub.unknown_project_files

在 1.6 版更改: 添加 ref.footnote

needs_sphinx

如果设置为 major.minor 版本字符串, 如 '1.1' , Sphinx会将其与版本进行比较, 如果它太旧则拒绝构建。 默认是没有要求的。

1.0 新版功能.

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

needs_extensions

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

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

1.3 新版功能.

manpages_url

交叉引用的URL manpage 指令。如果将其定义为 https://manpages.debian.org/{path} , 则 :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 命令行开关。

1.0 新版功能.

nitpick_ignore

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

1.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 表示数字将是 xy1 , xy2 , …如果位于子区域(但仍然是 x.1 , x.2 , … 如果直接位于一个部分和 1 , 2 , … 如果不在任何顶级部分。)

  • 等等…

1.3 新版功能.

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

smartquotes

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

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

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

smartquotes_action

This string, for use with Docutils 0.14 or later, 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

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

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

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

注解

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.

1.6.6 新版功能.

tls_verify

如果为true, Sphinx将验证服务器认证。默认为 True 。

1.5 新版功能.

tls_cacerts

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

1.5 新版功能.

小技巧

Sphinx在内部使用 requests 作为HTTP库。因此, 如果未设置 tls_cacerts , 则Sphinx会在指向 REQUESTS_CA_BUNDLE 环境变量的目录中引用认证文件。

today
today_fmt

这些值决定了如何格式化当前日期, 用作 |today| 的替换。

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

  • 否则, 使用 time.strftime() 格式化当前时间, 格式为 today_fmt 。

现在的默认值是 today 和 a today_fmt 的 '％B％d, ％Y' (或者, 如果使用 language 启用翻译, 则为等效格式对于选定的区域设置)。

highlight_language

用于突出显示源代码的默认语言。默认语言为 'python3' 。该值应该是有效的Pygments词法分析器名称, 请参阅 代码高亮 以获取更多详细信息。

0.5 新版功能.

在 1.4 版更改: 默认为现在 'default' 。它类似于 'python3' ;它主要是 'python' 的超集, 但是如果失败则它会在没有警告的情况下回退到 'none' 。如果失败, 'python3' 和其他语言会发出警告。如果您只想要Python 2高亮显示, 可以将其设置回 'python' 。

highlight_options

修改由以下内容指定词法分析器的方式的选项字典 highlight_language 生成突出显示的源代码。这些是特定于词法分析器的;对于每个人理解的选项, 请参阅 Pygments documentation 。

1.3 新版功能.

pygments_style

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

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

add_function_parentheses

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

一个布尔值, 决定 codeauthor 和 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的更多可能性, 请参阅扩展名 doctest 。

1.0 新版功能.

在 1.1 版更改: 现在也删除了 <BLANKLINE>.

国际化选项

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

language

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

0.5 新版功能.

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

目前Sphinx支持的语言是:

  • bn – 孟加拉语

  • ca – 加泰罗尼亚语

  • cs – 捷克语

  • da – 丹麦语

  • de – 德语

  • en – 英语

  • es – 西班牙语

  • et – 爱沙尼亚语

  • eu – 巴斯克语

  • fa – 伊朗语

  • fi – 芬兰语

  • fr – 法语

  • he – 希伯来语

  • hr – 克罗地亚语

  • hu – 匈牙利语

  • id – 印度尼西亚语

  • it – 意大利语

  • ja – 日语

  • ko – 朝鲜语

  • lt – 立陶宛语

  • lv – 拉脱维亚语

  • mk – 马其顿语

  • nb_NO – 挪威博克马尔语

  • ne – 尼泊尔语

  • nl – 荷兰语

  • pl – 波兰语

  • pt_BR – 巴西葡萄牙语

  • pt_PT – 欧洲葡萄牙语

  • ru – 俄语

  • si – 僧伽罗语

  • sk – 斯洛伐克语

  • sl – 斯洛文尼亚语

  • sv – 瑞典语

  • tr – 土耳其语

  • uk_UA – 乌克兰语

  • vi – 越南语

  • zh_CN – 简体中文

  • zh_TW – 繁体中文

locale_dirs

0.5 新版功能.

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

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

默认是 ['locales'].

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

gettext_compact

1.1 新版功能.

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

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

gettext_uuid

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

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

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

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

默认是 False.

1.3 新版功能.

gettext_location

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

默认是 True.

1.3 新版功能.

gettext_auto_build

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

默认是 True.

1.3 新版功能.

gettext_additional_targets

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

索引

索引条款

Literal-block

文字块: :: 和 code-block.

Doctest-block

doctest块

Raw

原始内容

图片

image/figure uri 和 alt

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

默认是 [].

1.3 新版功能.

figure_language_filename

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

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

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

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

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

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

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

1.4 新版功能.

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

数学的选项

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

math_number_all

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

math_eqref_format

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

例: 'Eq.{number}' 被渲染为, 例如, Eq.10.

math_numfig

如果为 True , 则在以下情况下显示的数学公式在页面中编号 numfig 已启用。 numfig_secnum_depth 设置受到尊重。 eq , not numref , 角色必须用于引用方程式数字。默认为 True 。

1.7 新版功能.

HTML输出选项

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

html_theme

The “theme” that the HTML output should use. See the section about theming. The default is 'alabaster'.

0.6 新版功能.

html_theme_options

影响所选主题外观的选项字典。这些是针对主题的。有关内置主题所理解的选项, 请参阅 this section 。

0.6 新版功能.

html_theme_path

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

0.6 新版功能.

html_style

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

html_title

The “title” for HTML documentation generated with Sphinx’s own templates. This is appended to the <title> tag of individual pages, and used in the navigation bar as the “topmost” element. It defaults to '<project> v<revision> documentation'.

html_short_title

A shorter “title” for the HTML docs. This is used in for links in the header and in the HTML Help docs. If not given, it defaults to the value of html_title.

0.4 新版功能.

html_baseurl

指向HTML文档根目录的URL。它用于表示文档的位置, 如 canonical_url 。

1.8 新版功能.

html_context

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

0.5 新版功能.

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

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

html_favicon

如果给定, 则必须是图像文件的名称(相对于 configuration directory 的路径), 它是文档的favicon。现代浏览器使用它作为标签, 窗口和书签的图标。它应该是一个Windows风格的图标文件(.ico), 大小为16x16或32x32像素。默认值: None 。

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

html_css_files

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

例:

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

1.8 新版功能.

html_js_files

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

例:

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

1.8 新版功能.

html_static_path

包含自定义静态文件(例如样式表或脚本文件)的路径列表。相对路径被视为相对于配置目录。它们被复制到主题的静态文件之后的输出的 _ 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' (或依赖于语言环境的等价物)。

html_use_smartypants

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

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

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 新版功能: 以前, 这总是被激活。

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

html_sidebars

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

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

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

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

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

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

1.7 版后已移除: a single string value for html_sidebars will be removed in 2.0

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

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

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

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

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

  • searchbox.html – the “quick search” box

例:

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构建中 _sources/name 。默认为 True 。

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

0.6 新版功能.

附加到源链接的后缀(参见 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

This is the file name suffix for generated HTML files. The default is ".html".

0.4 新版功能.

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

0.6 新版功能.

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

1.0 新版功能.

html_show_sphinx

If true, “Created using Sphinx” is shown in the HTML footer. Default is 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

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.

支持这些语言:

  • da – 丹麦语

  • nl – 荷兰语

  • en – 英语

  • fi – 芬兰语

  • fr – 法语

  • de – 德语

  • hu – 匈牙利语

  • it – 意大利语

  • ja – 日语

  • no – 挪威语

  • pt – 葡萄牙语

  • ro – 罗马尼亚语

  • ru – 俄语

  • es – 西班牙语

  • sv – 瑞典语

  • tr – 土耳其语

  • zh – 中文

加快构建速度

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

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

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

html_search_options

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

英语支持没有选择。

日本的支持有这些选择:

Type

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

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

‘sphinx.search.ja.DefaultSplitter’

TinySegmenter algorithm. 这是默认分割器。

‘sphinx.search.ja.MecabSplitter’

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

‘sphinx.search.ja.JanomeSplitter’

Janome绑定。要使用这个分离器, 需要 Janome 。

1.6 版后已移除: 'mecab', 'janome' and 'default' 已弃用. 为了保持兼容性, 'mecab', 'janome' and '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 。

1.3 新版功能.

html_math_renderer

HTML输出的math_renderer扩展名。默认为 'mathjax' 。

1.8 新版功能.

html_experimental_html5_writer

使用HTML5编写器处理输出。此功能需要0.1或更高版本的文档。默认为 False 。

1.6 新版功能.

2.0 版后已移除.

html4_writer

使用HTML4编写器处理输出。默认为 False 。

单个HTML输出的选项

singlehtml_sidebars

自定义侧边栏模板必须是将文档名称映射到模板名称的字典。它只允许一个名为 ‘’index’’ 的键。所有其他键都被忽略。有关更多信息, 请参阅 html_sidebars 。默认情况下, 它与 html_sidebars 相同。

HTML帮助输出选项

htmlhelp_basename

HTML帮助构建器的输出文件基名。默认是 'pydoc' 。

htmlhelp_file_suffix

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

2.0 新版功能.

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

2.0 新版功能.

Apple帮助输出选项

1.3 新版功能.

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

注解

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

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

applehelp_bundle_name

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

applehelp_bundle_id

帮助手册包的软件包ID。

警告

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

applehelp_dev_region

发展区域。默认为 'en-us' , 这是Apple的推荐设置。

applehelp_bundle_version

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

applehelp_icon

帮助包图标文件, 或 None 图标没有图标。根据Apple的文档, 这应该是应用程序图标的16 x 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' 。帮助查看器将在运行时使用以下内容替换值 'product' , 'query' 和 'lang' applehelp_kb_product , 用户输入的文本搜索框和用户的系统语言。

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

applehelp_remote_url

远程内容的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

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

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

applehelp_indexer_path

hiutil 程序的路径。默认为 '/usr/bin/hiutil' 。

applehelp_codesign_path

codesign 程序的路径。默认为 '/usr/bin/codesign' 。

applehelp_disable_external_tools

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

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

默认为 False.

epub输出的选项

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

epub_basename

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

epub_theme

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

epub_theme_options

影响所选主题外观的选项字典。这些是针对主题的。有关内置主题所理解的选项, 请参阅 this section 。

1.2 新版功能.

epub_title

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

在 2.0 版更改: 它默认为 project 选项。

epub_description

文件的描述。 默认值为 'unknown' 。

1.4 新版功能.

在 1.5 版更改: 从 epub3_description 重命名

epub_author

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

epub_contributor

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

1.4 新版功能.

在 1.5 版更改: Renamed from epub3_contributor

epub_language

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

epub_publisher

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

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

epub_identifier

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

epub_scheme

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

epub_uid

文档的唯一标识符。这是在都柏林核心元数据中。您可以使用 XML的名称格式 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 字典的元组。有关更多信息, 请参阅 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'),
]

The default value is [].

epub_post_files

在Sphinx生成的文本之后应插入的其他文件。它是包含文件名和标题的元组列表。此选项可用于添加附录。如果标题为空, 则不会向 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(Python Image Library)才能使用此选项。默认值为 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

页面进展

左到右

右到左

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 (如果 language 为 'ja' 则为默认值)

'pdflatex'’s 对Unicode字符的支持是有限的。

注解

2.0增加了 'pdflatex' 支持拉丁语文档中偶尔的西里尔字母或希腊字母或单词。这不是自动的, 请参阅讨论 latex_elements 'fontenc' 键。

如果你的项目使用Unicode字符, 将引擎设置为 'xelatex' 或 'lualatex' 并确保使用具有足够宽的字形覆盖范围的OpenType字体通常比尝试制作更容易 'pdflatex' 使用额外的Unicode字符。由于Sphinx 2.0默认是GNU FreeFont, 它涵盖了拉丁语, 西里尔语和希腊语。

相反 MathJaX数学渲染在HTML输出 , LaTeX需要一些额外的配置来支持Unicode文字 math: 唯一全面的解决方案(据我们所知)是使用 'xelatex' 或 'lualatex' 和 来添加 r'\usepackage {unicode-math}' (例如通过 latex_elements 'preamble' 键)。您可能更喜欢 r'\usepackage [math-style = literal] {unicode-math}' 来保持Unicode文字, 例如 α (U + 03B1) , 例如在输出中, 而不是而不是呈现为 \(\alpha\) 。

latex_documents

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

startdocname

用于指定LaTeX文件主文档的 document name 的字符串。 TOC树中 startdoc 文档引用的所有文档都将包含在LaTeX文件中。 (如果要使用LaTeX构建的默认主文档, 请在此处提供 master_doc 。)

targetname

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

title

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

author

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

documentclass

Normally, one of 'manual' or 'howto' (provided by Sphinx and based on 'report', resp. 'article'; Japanese documents use 'jsbook', resp. 'jreport'.) “howto” (non-Japanese) documents will not get appendices. Also they have a simpler title page. Other document classes can be given. Independently of the document class, the “sphinx” package is always loaded in order to define Sphinx’s custom LaTeX commands.

toctree_only

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

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 新版功能: 第6项 toctree_only 。仍然接受5件物品的元组。

如果给定, 则必须是图像文件的名称(相对于配置目录), 该文件是文档的徽标。它位于标题页的顶部。默认值: 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或应生成的索引名称列表, 例如 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 用法)。这意味着具有UTF-8字符的单词将正确地为 language 排序。

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

  • 对于 'xelatex' 或 'lualatex' , 默认是 True makeindex , 如果任何索引术语以非ascii字符开头, 则创建 .ind 包含UTF-8编码的无效字节的文件。使用 'lualatex' 这会打破PDF版本。

  • 对于 'pdflatex' , 默认是 False , 但是一旦索引的术语使用语言脚本中的非ascii字符, 建议对非英语文档使用 True 。

Sphinx增加 xindy 基础分发一些专门支持使用 'pdflatex' 引擎和西里尔文脚本。无论是使用 'pdflatex' 还是Unicode引擎, 西里尔文档都能正确处理拉丁文名称的索引, 即使是变音符号也是如此。

1.8 新版功能.

latex_elements

0.5 新版功能.

它的 documentation 已移至 LaTeX 定制 。

latex_docclass

将 'howto' 和 'manual' 的字典映射到真实文档类的名称, 这些名称将用作两个Sphinx类的基础。默认是对 'howto' 使用 'article' 和 'manual' 使用 'report'.

1.0 新版功能.

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

latex_additional_files

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

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

0.6 新版功能.

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

文本输出选项

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

text_newlines

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

  • 'unix': 使用Unix风格的行结尾(\n)

  • 'windows': 使用Windows风格的行结尾(\r\n)

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

默认值: 'unix' 。

1.1 新版功能.

text_sectionchars

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

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

1.1 新版功能.

text_add_secnumbers

一个布尔值, 用于决定文本输出中是否包含节号。默认为 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 新版功能.

手动页面输出选项

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

man_pages

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

startdocname

字符串, 指定手册页主文档的 document name 。 TOC树中 startdoc 文档引用的所有文档都将包含在手册文件中。 (如果要为手册页构建使用默认主文档, 请在此处使用 master_doc 。)

name

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

description

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

authors

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

section

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

1.0 新版功能.

man_show_urls

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

1.1 新版功能.

Texinfo输出的选项

这些选项会影响Texinfo输出。

texinfo_documents

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

startdocname

字符串, 指定Texinfo文件主文档的 document name。 TOC树中 startdoc 文档引用的所有文档都将包含在Texinfo文件中。 (如果要为Texinfo构建使用默认主文档, 请在此处提供 master_doc 。)

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或应生成的索引名称列表, 例如 html_domain_indices 。

1.1 新版功能.

texinfo_show_urls

控制如何显示URL地址。

  • 'footnote' – 在脚注中显示网址(默认)

  • '不' - 不显示网址

  • 'inline' - 在括号中内嵌显示网址

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

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

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

    'paragraphindent'

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

    'exampleindent'

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

    'preamble'

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

    'copying'

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

  • 由其他选项设置但因此不应被覆盖的键是:

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

1.1 新版功能.

QtHelp输出的选项

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

qthelp_basename

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

qthelp_namespace

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

qthelp_theme

qthelp输出的HTML主题。这默认为 'nonav' 。

qthelp_theme_options

影响所选主题外观的选项字典。这些是针对主题的。有关内置主题所理解的选项, 请参阅 this section 。

linkcheck构建器的选项

linkcheck_ignore

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

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

1.1 新版功能.

linkcheck_retries

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

1.4 新版功能.

linkcheck_timeout

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

1.1 新版功能.

linkcheck_workers

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

1.1 新版功能.

linkcheck_anchors

如果为true, 请检查链接中 ＃anchors 的有效性。由于这需要下载整个文档, 因此启用时会相当慢。默认为 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 ["^!"].

注解

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

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

1.5 新版功能.

XML构建器的选项

xml_pretty

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

1.2 新版功能.

脚注

1(1,2)

关于可用的globbing语法的注释:你可以使用标准shell构造 * , ? , [...] 和 [！...] 这些都不匹配斜杠。双星 ** 可用于匹配任何字符序列 包括 斜杠。

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

配置文件示例

# 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.
master_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 = [
    (master_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 = [
    (master_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 = [
    (master_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']