应用接口¶

每个Sphinx扩展都是一个Python模块，其中至少有一个 setup() 函数。此函数在初始化时被调用，其参数是代表Sphinx进程的应用程序对象。

class sphinx.application.Sphinx[源代码]¶: 此应用程序对象具有下述的公共API接口。

扩展的设置¶

这些方法通常在扩展的 setup() 函数中调用。

使用Sphinx扩展API的例子可以在 sphinx.ext 包里找到。

Sphinx.setup_extension(extname: str) → None[源代码]¶

导入并设置Sphinx扩展模块。

加载由模块 name 指定的扩展。当您的扩展需要其他扩展提供的功能时调用。若调用两次则不做任何操作。

static Sphinx.require_sphinx(version: tuple[int, int] | str) → None[源代码]¶

按需检查sphinx版本。

将 version 与正在运行的Sphinx版本进行比较，如果Sphinx版本过旧则终止构建。

参数:: version -- 所需版本，格式为 major.minor 或 (major, minor) 。

在 1.0 版本加入.

在 7.1 版本发生变更: 现在允许 (major, minor) 形式的 version。

Sphinx.connect(event: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int = 500) → int[源代码]¶

Sphinx.connect(event: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-get-outdated'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]], priority: int = 500) → int

Sphinx.connect(event: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], priority: int = 500) → int

Sphinx.connect(event: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-merge-info'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], BuildEnvironment], None], priority: int = 500) → int

Sphinx.connect(event: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], priority: int = 500) → int

Sphinx.connect(event: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], priority: int = 500) → int

Sphinx.connect(event: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], priority: int = 500) → int

Sphinx.connect(event: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], priority: int = 500) → int

Sphinx.connect(event: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], priority: int = 500) → int

Sphinx.connect(event: Literal['missing-reference'], callback: Callable[[Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None], priority: int = 500) → int

Sphinx.connect(event: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], priority: int = 500) → int

Sphinx.connect(event: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], priority: int = 500) → int

Sphinx.connect(event: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], priority: int = 500) → int

Sphinx.connect(event: Literal['html-page-context'], callback: Callable[[Sphinx, str, str, dict[str, Any], nodes.document], str | None], priority: int = 500) → int

Sphinx.connect(event: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], priority: int = 500) → int

Sphinx.connect(event: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-docstring'], callback: _AutodocProcessDocstringListener, priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-before-process-signature'], callback: _AutodocBeforeProcessSignatureListener, priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-signature'], callback: _AutodocProcessSignatureListener, priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-bases'], callback: _AutodocProcessBasesListener, priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-skip-member'], callback: _AutodocSkipMemberListener, priority: int = 500) → int

Sphinx.connect(event: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int = 500) → int

Sphinx.connect(event: Literal['viewcode-find-source'], callback: Callable[[Sphinx, str], tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]]], priority: int = 500) → int

Sphinx.connect(event: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int = 500) → int

Sphinx.connect(event: str, callback: Callable[..., Any], priority: int = 500) → int

event 事件发生时要调用的、已注册的 callback 回调。

有关可用的核心事件和回调函数参数的详细信息，请参阅事件回调API。

参数:

event -- 目标事件的名称
callback -- 事件的回调函数
priority -- 回调的优先级。回调将按 优先级 （升序）顺序调用。

返回:

监听器ID。它可以用于 disconnect() 。

在 3.0 版本发生变更: 支持 优先级

Sphinx.disconnect(listener_id: int) → None[源代码]¶

按 listener_id 注销回调函数。

参数:: listener_id -- connect() 返回的 listener_id

Sphinx.add_builder(builder: type[Builder], override: bool = False) → None[源代码]¶

注册一个新的构建器。

参数:

builder -- 构建器类
override -- 如果为真，则强制安装构建器，即使另一个同名构建器已安装

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_config_value(name: str, default: Any, rebuild: _ConfigRebuild, types: type | Collection[type] | ENUM = (), description: str = '') → None[源代码]¶

注册配置值。

这对于Sphinx识别新值并相应地设置默认值是必需的。

参数:

name -- 配置值的名字。建议以扩展的名字为前缀（例如 html_logo ， epub_title ）
default -- 配置的默认值。
rebuild --
重新构建的条件。它必须是以下值之一：
- 'env' 如果设置中的更改仅在文档被解析时生效--这意味着必须重新构建整个环境。
- 'html' 如果更改设置需要完全重新生成html文档。
- '' 如果设置中的更改不需要任何特殊的重建。
types -- 配置值的类型。可以指定一个类型列表。例如， [str] 用于描述采用字符串值的配置。
description -- 对配置值的简短描述。

在 0.4 版本发生变更: 如果 default 值是可调用的，则将使用config对象作为其参数来调用它，以获取默认值。这可以用来实现默认值依赖于其他值的配置值。

在 0.6 版本发生变更: 将 rebuild 从一个简单的布尔值（相当于 '' 或 'env' ）更改为字符串。但是，布尔值仍然被接受并在内部转换。

在 1.4 版本加入: types 参数。

在 7.4 版本加入: description 参数。

Sphinx.add_event(name: str) → None[源代码]¶

注册一个名为 name 的事件。

这对于能够发出它是必需的。

参数:: name -- 事件的名称

Sphinx.set_translator(name: str, translator_class: type[nodes.NodeVisitor], override: bool = False) → None[源代码]¶

注册或重写Docutils转换器类。

这用于注册自定义输出转换器或替换内置转换器。这允许扩展使用自定义转换器并为转换器定义自定义节点（参见 add_node()）。

参数:

name -- 转换器的构建器名称
translator_class -- 转换器类
override -- 如果为真，则强制安装转换器，即使另一个同名转换器已安装

在 1.3 版本加入.

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_node(node: type[Element], override: bool = False, **kwargs: _NodeHandlerPair) → None[源代码]¶

注册Docutils节点类。

这对于Docutils内部构件是必需的。将来还可以使用它来验证已解析文档中的节点。

参数:

node -- 节点类
kwargs -- 每个构建器的访问者函数（见下文）
override -- 如果为真，则强制安装节点，即使另一个同名节点已安装

Sphinx HTML、LaTeX、text和manpage writer的节点访问者函数，可以作为关键字参数：关键字应该是一个或多个 'html', 'latex', 'text', 'man', 'texinfo' 或任何其他受支持的翻译器，值为方法二元组 (visit, depart) 。如果 visit 函数引发 docutils.nodes.SkipNode，则 depart 可以为 None。例子：

class math(docutils.nodes.Element): ...

def visit_math_html(self, node):
    self.body.append(self.starttag(node, 'math'))

def depart_math_html(self, node):
    self.body.append('</math>')

app.add_node(math, html=(visit_math_html, depart_math_html))

显然，当在要翻译的文档中遇到未指定访问者方法的转换器时，会在节点上卡住。

在 0.5 版本发生变更: 增加了对提供访问函数的关键字参数的支持。

Sphinx.add_enumerable_node(node: type[Element], figtype: str, title_getter: TitleGetter | None = None, override: bool = False, **kwargs: tuple[_NodeHandler, _NodeHandler]) → None[源代码]¶

将Docutils节点类注册为numfig目标。

Sphinx会自动为节点编号。然后用户可以使用 numref。

参数:

node -- 节点类
figtype -- 可枚举节点的类型。每个figtype都有单独的编号序列。作为系统figtypes，定义了 figure ， table 和 code-block 。可以将自定义节点添加到这些默认的figtypes中。如果给出了新的figtype，也可以定义新的自定义figtype。
title_getter -- 获取节点标题的getter函数。它接受一个可枚举节点的实例，并且必须返回其标题作为字符串。标题用于 ref 的引用的默认标题。默认情况下，Sphinx会从节点中搜索 docutils.nodes.caption 或 docutils.nodes.title 作为标题。
kwargs -- 每个构建器的访问者函数（与 add_node() 相同）
override -- 如果为真，则强制安装节点，即使另一个同名节点已安装

在 1.4 版本加入.

Sphinx.add_directive(name: str, cls: type[Directive], override: bool = False) → None[源代码]¶

注册Docutils指令。

参数:

name -- 指令的名称
cls -- 指令的类
override -- 如为假，则若同名指令已安装，则不安装它。如果为真，则无条件安装该指令。

例如，名为 my-directive 的自定义指令将被这样添加：

from docutils.parsers.rst import Directive, directives

class MyDirective(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,
    }

    def run(self):
        pass

def setup(app):
    app.add_directive('my-directive', MyDirective)

有关更多详细信息，请参阅 the Docutils docs 。

在 0.6 版本发生变更: 现在支持Docutils 0.5样式的指令类。

在 1.8 版本发生变更: 废弃了对Docutils 0.4样式（基于函数）指令的支持。

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_role(name: str, role: Any, override: bool = False) → None[源代码]¶

注册Docutils角色。

参数:

name -- 角色的名称
role -- 角色函数
override -- 如为假，则若同名角色已安装，则不安装它。如果为真，则无条件安装该角色。

有关角色函数的更多详细信息，请参阅 the Docutils docs 。

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_generic_role(name: str, nodeclass: type[Node], override: bool = False) → None[源代码]¶

注册通用Docutils角色。

注册一个Docutils角色，该角色只在 nodeclass 给定的节点中包装其内容。

参数:: override -- 如为假，则若同名角色已安装，则不安装它。如果为真，则无条件安装该角色。

在 0.6 版本加入.

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_domain(domain: type[Domain], override: bool = False) → None[源代码]¶

注册域。

参数:

domain -- 域类
override -- 如为假，则若同名域已安装，则不安装它。如果为真，则无条件安装该域。

在 1.0 版本加入.

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_directive_to_domain(domain: str, name: str, cls: type[Directive], override: bool = False) → None[源代码]¶

在域中注册Docutils指令。

例如 add_directive()，但该指令被添加到名为 domain 的域中。

参数:

domain -- 目标域的名称
name -- 指令的名称
cls -- 指令的类
override -- 如为假，则若同名指令已安装，则不安装它。如果为真，则无条件安装该指令。

在 1.0 版本加入.

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_role_to_domain(domain: str, name: str, role: RoleFunction | XRefRole, override: bool = False) → None[源代码]¶

在域中注册Docutils角色。

类似 add_role()，但是角色被添加到名为 domain 的域中。

参数:

domain -- 目标域的名称
name -- 角色的名称
role -- 角色函数
override -- 如为假，则若同名角色已安装，则不安装它。如果为真，则无条件安装该角色。

在 1.0 版本加入.

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_index_to_domain(domain: str, index: type[Index], _override: bool = False) → None[源代码]¶

注册域的自定义索引。

将自定义 index 类添加到名为 domain 的域中。

参数:

domain -- 目标域的名称
index -- 索引类
override -- 如为假，则若同名索引已安装，则不安装它。如果为真，则无条件安装该索引。

在 1.0 版本加入.

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Callable[[BuildEnvironment, str, addnodes.desc_signature], str] | None = None, ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', doc_field_types: Sequence[Field] = (), override: bool = False) → None[源代码]¶

注册一个新的对象类型。

此方法是添加一个新的 object 类型的非常方便的方法，可以交叉引用。它会：

创建一个新的指令（称为 directivename ），用于记录对象。如果 indextemplate 非空，它将自动添加索引项；如果给定，则它必须正好包含一个 %s 实例。有关如何解释模板，请参见下面的示例。
创建一个新角色（称为 rolename ），以交叉引用这些对象描述。
如果提供 parse_node，它必须是一个接受字符串和docutils节点的函数，并且必须使用从字符串解析的子节点填充节点。然后它必须返回要在交叉引用和索引项中使用的项的名称。请参见 conf.py 文件在源文件中的示例。
objname （如果未给定，将默认为 directivename ）命名对象的类型。在列出对象时使用，例如在搜索结果中。

例如，如果在自定义Sphinx插件中有此调用：

app.add_object_type('directive', 'dir', 'pair: %s; directive')

您可以在文档中使用此标记：

.. rst:directive:: function

   Document a function.

<...>

See also the :rst:dir:`function` directive.

对于该指令，将生成一个索引项，就像您预先添加了：

.. index:: pair: function; directive

引用节点将是 literal 类（因此它将以适合代码的比例字体呈现），除非提供 ref_nodeclass 参数，该参数必须是docutils节点类。最有用的是 docutils.nodes.emphasis 或者 docutils.nodes.strong --您也可以使用 docutils.nodes.generated 如果你不想进一步的文字装饰。如果文本应视为文字（例如，没有智能引号替换），但没有打字机样式，则使用 sphinx.addnodes.literal_emphasis 或者 sphinx.addnodes.literal_strong.

对于角色内容，您具有与标准Sphinx角色相同的语法可能性（请参见语法）。

如果 override 为True，则强制安装给定的object_type，即使已安装具有相同名称的object_type。

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_crossref_type(directivename: str, rolename: str, indextemplate: str = '', ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', override: bool = False) → None[源代码]¶

注册新的交叉引用对象类型。

此方法与 add_object_type() 非常相似，除了它生成的指令必须是空的，并且不会产生任何输出。

这意味着您可以将语义目标添加到源代码中，并使用自定义角色而不是通用角色来引用它们（例如 ref）。示例调用：

app.add_crossref_type(
    'topic', 'topic', 'single: %s', docutils.nodes.emphasis
)

用法示例：

.. topic:: application API

The application API
-------------------

Some random text here.

See also :topic:`this section <application API>`.

（当然，topic 指令后面的元素不必是节。）

参数:: override -- 如果为false，则如果另一个交叉引用类型已作为同名安装，则不安装它。如果为true，则无条件安装交叉引用类型。

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_transform(transform: type[Transform]) → None[源代码]¶

注册要在解析后应用的Docutils转换。

将标准的docutils Transform 子类 transform 添加到在Sphinx解析reST文档后应用的转换列表中。

参数:: transform -- 转换类

Sphinx变换的优先级范围类别¶
优先级	Sphinx的主要目标
0-99	用docutils修复无效节点。翻译doctree。
100-299	准备
300-399	早期的
400-699	主要的
700-799	后置处理。修改文本和引用的截止日期。
800-899	收集引用和引用节点。域处理。
900-999	完成并清理。

Transform Priority Range Categories

Sphinx.add_post_transform(transform: type[Transform]) → None[源代码]¶

在编写之前注册要应用的Docutils转换。

将标准的docutils Transform 子类 transform 添加到在Sphinx编写文档之前应用的转换列表中。

参数:: transform -- 转换类

Sphinx.add_js_file(filename: str | None, priority: int = 500, loading_method: str | None = None, **kwargs: Any) → None[源代码]¶

注册一个JavaScript文件以包含在HTML输出中。

参数:

filename -- 默认HTML模板将包含的JavaScript文件的名称。它必须相对于HTML静态路径，或者是带有方案的完整URI，或者是 None 。 None 值用于创建内联 <script> 标签。见下文 kwargs 的描述。
priority -- 文件按优先级升序包含。如果多个JavaScript文件具有相同的优先级，则这些文件将按注册顺序包含。见下文“JavaScript文件的优先级范围”列表。
loading_method -- JavaScript文件的加载方法。允许 'async' 或者 'defer' 。
kwargs -- 额外的关键字参数作为 <script> 标签的属性包含。如果给出了特殊的关键字参数 body ，其值将作为 <script> 标签的内容添加。

例如：

app.add_js_file('example.js')
# => <script src="_static/example.js"></script>

app.add_js_file('example.js', loading_method='async')
# => <script src="_static/example.js" async="async"></script>

app.add_js_file(None, body="var myVariable = 'foo';")
# => <script>var myVariable = 'foo';</script>

JavaScript文件的优先级范围¶
优先级	Sphinx的主要目标
200	内建JavaScript文件的默认优先级
500	扩展的默认优先级
800	`html_js_files` 的默认优先级

当扩展在 html-page-context 事件上调用此方法时，可以将JavaScript文件添加到特定的HTML页面。

参见

add_static_dir() for copying static files to the output directory

在 0.5 版本加入.

在 1.8 版本发生变更: 重命名自 app.add_javascript(). 它允许关键字参数作为脚本标记的属性。

在 3.5 版本发生变更: 接受优先级参数。允许将JavaScript文件添加到特定页面。

在 4.4 版本发生变更: 接受loading_method参数。允许更改JavaScript文件的加载方法。

Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any) → None[源代码]¶

注册要包含在HTML输出中的样式表。

参数:

filename -- 默认HTML模板将包含的CSS文件的名称。它必须相对于HTML静态路径，或者是带有方案的完整URI。
priority -- 文件按优先级升序包含。如果多个CSS文件具有相同的优先级，则这些文件将按注册顺序包含。见下文“CSS文件的优先级范围”列表。
kwargs -- 额外的关键字参数作为 <link> 标签的属性包含。

例如：

app.add_css_file('custom.css')
# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

app.add_css_file('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
#          type="text/css" media="print" />

app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
#          type="text/css" title="fancy" />

CSS文件的优先级范围¶
优先级	Sphinx的主要目标
200	内建CSS文件的默认优先级
500	扩展的默认优先级
800	`html_css_files` 的默认优先级

当扩展在 html-page-context 事件上调用此方法时，可以将CSS文件添加到特定的HTML页面。

参见

add_static_dir() for copying static files to the output directory

在 1.0 版本加入.

在 1.6 版本发生变更: 可以使用参数 alternate （布尔值）和 title （字符串）提供可选的 alternate 和/或 title 属性。默认情况下没有标题且 alternate = False 。有关更多信息，请参阅 documentation 。

在 1.8 版本发生变更: 重命名自 app.add_stylesheet(). 它允许关键字参数作为链接标记的属性。

在 3.5 版本发生变更: 接受优先级参数。允许将CSS文件添加到特定页面。

Sphinx.add_static_dir(path: str | os.PathLike[str]) → None[源代码]¶

Register a static directory to include in HTML output.

The given directory's contents will be copied to the _static directory during an HTML build. Files from extension static directories are copied after theme static files and before any directories from the user-configured html_static_path setting.

Sphinx has built-in support for static/ directories in themes; theme developers should only use this method to register further directories to be copied.

参数:: path -- The path to a directory containing static files. This is typically relative to the extension's package directory.

例如：

from pathlib import Path

def setup(app):
    # All files in this directory are copied to _static/,
    # preserving the subdirectory structure
    app.add_static_dir(Path(__file__).parent / 'static')

    # Add JavaScript and CSS files to HTML pages,
    # the paths are relative to _static/
    app.add_js_file('js/my_extension.js')
    app.add_css_file('css/my_extension.css')

在 9.1 版本加入.

Sphinx.add_latex_package(packagename: str, options: str | None = None, after_hyperref: bool = False) → None[源代码]¶

注册包，以包含在LaTeX源代码中。

将 packagename 添加到LaTeX源代码将包含的包列表中。如果提供 options ，它将被用于 usepackage 声明。如果将 after_hyperref 设置为真值，则该包将在 hyperref 包之后加载。

app.add_latex_package('mypackage')
# => \usepackage{mypackage}
app.add_latex_package('mypackage', 'foo,bar')
# => \usepackage[foo,bar]{mypackage}

在 1.3 版本加入.

在 3.1 版本加入: after_hyperref 选项。

Sphinx.add_lexer(alias: str, lexer: type[Lexer]) → None[源代码]¶

为源代码注册一个新的分析程序。

使用 lexer 突出显示具有给定语言 alias 的代码块。

在 0.6 版本加入.

在 2.1 版本发生变更: 将词法分析器类作为参数。

在 4.0 版本发生变更: 不再支持将词法分析器实例作为参数。

Sphinx.add_autodocumenter(cls: type[Documenter], override: bool = False) → None[源代码]¶

为自动文档插件注册一个新的documenter类。

将 cls 作为 sphinx.ext.autodoc 扩展的新documenter类添加。它必须是 sphinx.ext.autodoc.Documenter 的子类。这允许自动记录新类型的对象。有关如何子类化 Documenter 的示例，请参阅autodoc模块的源代码。

如果 override 为True，则即使已安装具有相同名称的documenter，也会强制安装给定的 cls 。

参见开发 autodoc 扩展。

在 0.6 版本加入.

在 2.2 版本发生变更: 添加 override 关键字。

Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str, Any], Any]) → None[源代码]¶

为自动文档插件注册一个类似“getattr”的新函数。

添加 getter，它必须是一个接口与 getattr() 内置函数兼容的函数，作为 typ 实例的对象的autodoc属性getter。自动文档需要获取某个类型属性的所有情况都由该函数处理，而不是 getattr()。

在 0.6 版本加入.

Sphinx.add_search_language(cls: type[SearchLanguage]) → None[源代码]¶

为HTML搜索索引注册一种新语言。

添加 cls，它必须是 sphinx.search.SearchLanguage，作为生成HTML全文搜索索引的支持语言。该类必须具有一个 lang 属性，该属性指示该类应用于的语言。请参阅 html_search_language。

在 1.1 版本加入.

Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool = False) → None[源代码]¶

注册源文件的后缀。

与 source_suffix 相同。用户可以使用配置设置覆盖此设置。

参数:: override -- 如果为false，则如果已安装相同的后缀，则不安装它。如果为true，则无条件安装该后缀。

在 1.8 版本加入.

Sphinx.add_source_parser(parser: type[Parser], override: bool = False) → None[源代码]¶

注册解析器类。

参数:: override -- 如果为false，则如果另一个解析器已为相同的后缀安装，则不安装它。如果为true，则无条件安装该解析器。

在 1.4 版本加入.

在 1.8 版本发生变更: suffix 参数已弃用。它只接受 parser 参数。使用 add_source_suffix() API来注册后缀。

在 1.8 版本发生变更: 添加 override 关键字。

Sphinx.add_env_collector(collector: type[EnvironmentCollector]) → None[源代码]¶

注册环境收集器类。

请参阅环境收集器 API。

在 1.6 版本加入.

Sphinx.add_html_theme(name: str, theme_path: str | os.PathLike[str]) → None[源代码]¶

注册HTML主题。

name 是主题的名称，theme_path 是主题的完整路径（引用：将主题作为Python包分发）。

在 1.6 版本加入.

Sphinx.add_html_math_renderer(name: str, inline_renderers: _MathsInlineRenderers | None = None, block_renderers: _MathsBlockRenderers | None = None) → None[源代码]¶

注册HTML渲染器。

name 是数学渲染器的名称。inline_renderers 和 block_renderers 都用作HTML编写器的访问者函数：前者用于inline math节点(node.math)，后者用于块数学节点(nodes.math_block). 关于访问者函数，请参见 add_node() 以获取详细信息。

在 1.8 版本加入.

Sphinx.add_message_catalog(catalog: str, locale_dir: str | os.PathLike[str]) → None[源代码]¶

注册邮件目录。

参数:

catalog -- catalog的名称
locale_dir -- 消息目录的基本路径

有关更多详细信息，请参见 sphinx.locale.get_translation() 函数。

在 1.8 版本加入.

Sphinx.is_parallel_allowed(typ: str) → bool[源代码]¶

检查是否允许并行处理。

参数:: typ -- 处理类型； 'read' 或者 'write'。

Sphinx.set_html_assets_policy(policy: Literal['always', 'per_page']) → None[源代码]¶

设置在HTML页面中包含资源的策略。

always: 在所有页面中包含资源
per_page: 仅在使用它们的页面中包含资源

exception sphinx.application.ExtensionError¶: 如果插件接口出现问题，所有这些方法都会引发此异常。

发射事件¶

注意

扩展开发人员应优先直接使用事件管理器（ events ）对象，通过 EventManager.emit() 和 EventManager.emit_firstresult()，它们与下面的方法具有相同的行为。

class sphinx.application.Sphinx[源代码]

emit(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list[Any][源代码]¶

发出事件并将参数传递给回调函数。

以列表形式返回所有回调的返回值。不要在扩展中发出核心Sphinx事件！

参数:

event -- 要发出的事件的名称
args -- 事件的参数
allowed_exceptions -- 回调中允许的异常列表

在 3.1 版本发生变更: 添加了 allowed_exceptions 来指定路径穿越异常

emit_firstresult(event: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any[源代码]¶

发出事件并将参数传递给回调函数。

返回第一个不返回 None 的回调的结果。

参数:

event -- 要发出的事件的名称
args -- 事件的参数
allowed_exceptions -- 回调中允许的异常列表

在 0.5 版本加入.

在 3.1 版本发生变更: 添加了 allowed_exceptions 来指定路径穿越异常

Sphinx运行时信息¶

应用程序对象还提供运行时信息作为属性。

Sphinx.project¶: 目标项目。参见： Project。

Sphinx.srcdir¶: 源目录

Sphinx.confdir¶: 目录包含 conf.py.

Sphinx.doctreedir¶: 用于存储文档树的目录。

Sphinx.outdir¶: 用于存储生成文档的目录。

Sphinx.fresh_env_used¶: True/False表示是否为此构建创建了新环境，如果环境尚未初始化，则为None。

Sphinx核心事件¶

备注

移动到了事件回调API。

检查Sphinx版本¶

使用此选项可使您的插件适应Sphinx中的接口更改。

sphinx.version_info: Final = (9, 1, 1, 'beta', 0)¶

版本信息，以便更好地编程使用。

一个由五个元素组成的元组；对于Sphinx版本1.2.1 beta 3，这将是 （1，2，1，'beta'，3）。第四个元素可以是：alpha、beta、rc、final 之一。 final 始终将0作为最后一个元素。

在 1.2 版本加入: 在版本1.2之前，请检查字符串 sphinx.__version__。

配置对象¶

class sphinx.config.Config(config: dict[str, Any] | None = None, overrides: dict[str, Any] | None = None)[源代码]¶

配置文件抽象。

Config对象使所有配置选项的值可用作属性。

它通过 Sphinx.config 和 sphinx.environment.BuildEnvironment.config 属性公开。例如，要获取 language 的值，请使用 app.config.language 或者 env.config.language 。

模板桥¶

class sphinx.application.TemplateBridge[源代码]¶

这个类定义了“模板桥”的接口，也就是说，一个提供了模板名称和上下文的模板的类。

init(builder: Builder, theme: Theme | None = None, dirs: list[str] | None = None) → None[源代码]¶

由生成器调用以初始化模板系统。

builder 是builder对象；您可能需要查看 builder.config.templates_path.

主题是 sphinx.theming.Theme 对象或无；在后一种情况下，dirs 可以是查找模板的固定目录列表。

newest_template_mtime() → float[源代码]¶: 由生成器调用以确定输出文件是否因模板更改而过期。返回已更改的最新模板文件的m时间。默认实现返回“0”。

render(template: str, context: dict[str, Any]) → None[源代码]¶: 由生成器调用，以呈现具有指定上下文（Python字典）的文件名形式给定的模板。

render_string(template: str, context: dict[str, Any]) → str[源代码]¶: 由生成器调用以呈现给定为字符串的模板，并具有指定的上下文（Python字典）。

例外¶

exception sphinx.errors.SphinxError[源代码]¶

Sphinx错误的基类。

这是“nice”异常的基类。当引发此类异常时，Sphinx将中止构建并向用户显示异常类别和消息。

鼓励插件从这个异常中派生出自定义错误。

异常不是派生自 SphinxError 将被视为意外的，并将回溯的一部分（以及保存在临时文件中的完整回溯）显示给用户。

category¶: 异常“category”的描述，用于将异常转换为字符串（“category:message”）。应该在子类中相应地设置。

exception sphinx.errors.ConfigError[源代码]¶: 配置错误。

exception sphinx.errors.ExtensionError(message: str, orig_exc: Exception | None = None, modname: str | None = None)[源代码]¶: 插件错误。

exception sphinx.errors.ThemeError[源代码]¶: 主题错误。

exception sphinx.errors.VersionRequirementError[源代码]¶: 不兼容的Sphinx版本错误。