应用程序 API¶

每个 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 版本,当其过旧时,终止构建.

参数:: version – 所需的版本形式为 major.minor 或 (major, minor) .

Added in version 1.0.

在 7.1 版本发生变更: version 的类型现在允许使用 (major, minor) 形式.

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, list[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: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], Sequence[str]], None], priority: int = 500) → int

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

Sphinx.connect(event: Literal['autodoc-process-signature'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], str | None, str | None], tuple[str | None, str | None] | None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-process-bases'], callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None], priority: int = 500) → int

Sphinx.connect(event: Literal['autodoc-skip-member'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, bool, dict[str, bool]], bool], 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

注册回调以便在事件被触发时调用.

有关可用核心事件及回调函数参数的详细信息,请参见事件回调 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 版本发生变更: 如果*默认*值是一个可调用对象,它将在调用时以配置对象作为参数,以获取默认值.这可以用于实现默认值依赖于其他值的配置值.

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

Added in version 7.4: 描述参数.

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 – 如果为真,即使已经安装了同名的其他翻译器,也强制安装该翻译器

Added in version 1.3.

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

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

注册一个 Docutils 节点类.

这是Docutils内部所必要的.它在未来也可能用于验证解析文档中的节点.

参数:

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

Sphinx的HTML、LaTeX、文本和手册页写入器的节点访问函数可以作为关键字参数提供:关键字应该是 'html' 、 'latex' 、 'text' 、 'man' 、 'texinfo' 或任何其他支持的翻译器,值是一个 (visit, depart) 方法的二元组. depart 可以为 None ,如果 visit 函数抛出:exc:docutils.nodes.SkipNode . 例:

class math(docutils.nodes.Element): pass

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[Callable, Callable]) → None[源代码]¶

注册一个 Docutils 节点类作为 numfig 目标.

Sphinx会自动为节点编号.然后用户可以使用 numref 来引用它.

参数:

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

Added in version 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):
        ...

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

有关更多详情,请参见 Docutils文档 .

在 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 – 如果为假,则如果已经安装了同名的其他角色,则不安装它.如果为真,则无条件安装该角色.

有关角色功能的更多详细信息,请参见 Docutils 文档 .

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

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

注册一个通用的Docutils角色.

注册一个Docutils角色,该角色仅将其内容包装在由*nodeclass*给定的节点中.

参数:: override – 如果为假,则如果已经安装了同名的其他角色,则不安装它.如果为真,则无条件安装该角色.

Added in version 0.6.

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

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

注册一个域名.

参数:

domain – 一个域类
override – 如果为假,则在同名的其他域已经安装的情况下不进行安装;如果为真,则无条件安装该域.

Added in version 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 – 如果为假,则在同名的其他指令已经安装的情况下,不要安装它.如果为真,则无条件安装该指令.

Added in version 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 – 如果为假,则如果已经安装了同名的其他角色,则不安装它.如果为真,则无条件安装该角色.

Added in version 1.0.

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

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

为一个域注册一个自定义索引.

为名为 domain 的领域添加一个自定义的 index 类.

参数:

domain – 目标域名的名称
index – 索引类
override – 如果为假,则在已经安装了同名的其他索引时,不要安装它.如果为真,则无条件安装该索引.

Added in version 1.0.

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

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

注册一个新的对象类型.

这个方法是添加新的可互相引用的对象类型的一个非常方便的方式.它将执行以下操作:

为文档记录一个对象创建一个新的指令（称为 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() 非常相似,唯一不同的是它生成的指令必须为空,并且不会产生任何输出.

这意味着您可以将语义目标添加到您的源文件中,并使用自定义角色而不是通用角色（如 :rst :role:`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 – 如果为假,则如果已经安装了同名的其他交叉引用类型,则不安装它.如果为真,则无条件安装该交叉引用类型.

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

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

注册一个 Docutils 转换,在解析后应用.

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

参数:: transform – 一个变换类

Sphinx变换的优先级范围类别¶
优先级	主旨在Sphinx
0-99	修复由docutils产生的无效节点.翻译一个文档树.
100-299	准备
300-399	早期
400-699	主
700-799	后期处理.修改文本和参考文献的截止日期.
800-899	收集引用和被引用的节点.领域处理.
900-999	最终定稿并清理.

refs:变换优先级范围类别

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[源代码]¶

在HTML输出中注册一个JavaScript文件.

参数:

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 页面.

Added in version 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 页面.

Added in version 1.0.

在 1.6 版本发生变更: 可选的 alternate 和/或 title 属性可以通过参数 alternate （布尔值）和 title （字符串）进行提供.默认情况下没有标题,*alternate* = False .更多信息,请参阅文档.

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

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

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}

Added in version 1.3.

Added in version 3.1: after_hyperref 选项.

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

为源代码注册新的词法分析器.

使用 lexer 来高亮带有给定语言 alias 的代码块.

Added in version 0.6.

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

在 4.0 版本发生变更: 移除了将词法分析器实例作为参数的支持.

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

为autodoc扩展注册一个新的文档生成器类.

添加 cls 作为 sphinx.ext.autodoc 扩展的一个新文档生成类.它必须是 sphinx.ext.autodoc.Documenter 的子类.这允许自动记录新类型的对象.有关如何对子类 Documenter 进行子类化的示例,请参见 autodoc 模块的源代码.

如果*override*为True,即使已经安装了相同名称的文档生成器,也会强制安装给定的*cls*.

请参见开发autodoc扩展 .

Added in version 0.6.

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

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

为 autodoc 扩展注册一个新的 getattr -类似函数.

添加 getter,它必须是一个与内建的 getattr() 兼容接口的函数,作为 typ 类型实例的自动文档属性获取器.之后,所有需要为类型获取属性的自动文档情况都由这个函数而不是 getattr() 处理.

Added in version 0.6.

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

注册一种新的语言用于 HTML 搜索索引.

添加 cls,该类必须是 sphinx.search.SearchLanguage 的子类,作为构建 HTML 全文搜索索引的支持语言.该类必须具有一个 lang 属性,用于指示应使用的语言.请参见 html_search_language .

Added in version 1.1.

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

注册源文件的后缀.

与 source_suffix 相同.用户可以通过配置设置覆盖此选项.

参数:: override – 如果为假,则在相同后缀已安装时,不要安装它.如果为真,则无条件安装该后缀.

Added in version 1.8.

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

注册一个解析器类.

参数:: override – 如果为假,则在已有其他解析器安装的情况下,不要安装该解析器.如果为真,则无条件安装该解析器.

Added in version 1.4.

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

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

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

注册一个环境收集器类.

请参阅环境收集器 API .

Added in version 1.6.

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

注册一个 HTML 主题.

name 是主题的名称,*theme_path* 是主题的完整路径（参考:将您的主题作为Python包分发）.

Added in version 1.6.

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

注册一个用于 HTML 的数学渲染器.

name 是一个数学渲染器的名称.*inline_renderers* 和 block_renderers 用作 HTML 写入器的访问者函数:前者用于行内数学节点 ( nodes.math ),后者用于块数学节点 ( nodes.math_block ).关于访问者函数的更多细节,请参见 add_node() .

Added in version 1.8.

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

注册消息目录.

参数:

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

有关更多详细信息,请参阅 sphinx.locale.get_translation() .

Added in version 1.8.

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

检查是否允许并行处理.

参数:: typ – 处理的一种类型; 'read' 或 'write' .

exception sphinx.application.ExtensionError¶: 如果扩展 API 出现问题,所有这些方法都会引发此异常.

发出事件¶

class sphinx.application.Sphinx[源代码]

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

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

返回所有回调的返回值列表. 在扩展中不要发出核心 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 – 允许在回调中使用的异常列表

Added in version 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 API 更改.

sphinx.version_info = (8, 1, 0, 'beta', 0)¶

版本信息以便于更好的程序化使用.

五个元素的元组;对于 Sphinx 版本 1.2.1 beta 3,这将是 (1, 2, 1, 'beta', 3) .第四个元素可以是以下之一: alpha 、 beta 、 rc 、 final . final 的最后一个元素总是 0.

Added in version 1.2: 在版本 1.2 之前,请检查字符串 sphinx.__version__ .

The Config object¶

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.config.templates_path 的值.

theme 是一个 sphinx.theming.Theme 对象或 None;在后者情况下,*dirs* 可以是一个固定目录的列表,用于寻找模板.

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

render(template: str, context: dict) → None[源代码]¶: 被构建器调用,以使用给定文件名和指定上下文（一个Python字典）渲染模板.

render_string(template: str, context: dict) → str[源代码]¶: 由构建器调用,以使用指定上下文（一个 Python 字典）呈现作为字符串给定的模板.

异常¶

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

Sphinx错误的基类.

这是”友好”异常的基类.当抛出此类异常时,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版本错误.