应用程序API¶
每个Sphinx扩展模块都是一个至少具有 setup()
功能。此函数在初始化时使用一个参数调用,即表示Sphinx进程的应用程序对象。
扩展设置¶
这些方法通常在扩展的 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, 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: 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
注册 callback 在下列情况下调用 event 会被排放出去。
有关可用核心事件和回调函数的参数的详细信息,请参阅 事件回调API 。
- 参数:
event -- 目标事件的名称
callback -- 事件的回调函数
priority -- 回调的优先级。将按以下顺序调用回调 priority (升序)。
- 返回:
监听器ID,可用于
disconnect()
。
在 3.0 版本发生变更: 支持 priority
- Sphinx.disconnect(listener_id: int) None [源代码]¶
取消注册回调的方式 listener_id 。
- 参数:
listener_id -- 一个监听者ID,
connect()
退货
- Sphinx.add_builder(builder: type[Builder], override: bool = False) None [源代码]¶
注册一个新的构建器。
- 参数:
builder -- 建造者班级
override -- 如果为True,则强制安装构建器,即使已经安装了同名的其他构建器
在 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'
if a change in the setting only takes effect when a document is parsed -- this means that the whole environment must be rebuilt. *'html'
如果设置中的更改需要完全重新生成HTML文档。*''
如果更改设置将不需要任何特殊重建。types -- 配置值的类型。可以指定类型列表。例如,
[str]
用于描述接受字符串值的配置。description -- 配置值的简短说明。
在 0.4 版本发生变更: 如果 default 值是可调用的,则将使用配置对象作为其参数来调用它,以获取默认值。这可用于实现其默认值取决于其他值的配置值。
在 0.6 版本发生变更: 变化 rebuild 从简单的布尔值(等效于
''
或'env'
)转换为字符串。然而,布尔值在内部仍被接受和转换。Added in version 7.4: 的 description 参数.
- Sphinx.set_translator(name: str, translator_class: type[nodes.NodeVisitor], override: bool = False) None [源代码]¶
注册或重写Docutils转换器类。
这用于注册自定义输出翻译器或替换内置翻译器。这允许扩展模块使用自定义翻译程序并为该翻译程序定义自定义节点(请参见
add_node()
)。- 参数:
name -- 翻译器的生成器的名称
translator_class -- 翻译员班
override -- 如果为True,则强制安装转换器,即使已经安装了相同名称的另一个转换器
Added in version 1.3.
在 1.8 版本发生变更: 增列 override 关键字。
- Sphinx.add_node(node: type[Element], override: bool = False, **kwargs: _NodeHandlerPair) None [源代码]¶
注册Docutils节点类。
这对于Docutils内部来说是必要的。将来还可以使用它来验证已解析文档中的节点。
- 参数:
node -- 一个节点类
kwargs -- 每个构建器的访问函数(见下文)
override -- 如果为True,则强制安装该节点,即使已经安装了同名的另一个节点
Sphinx HTML、LaTeX、文本和手册页编写器的节点访问器函数可以作为关键字参数给出:关键字应该是以下一个或多个
'html'
,'latex'
,'text'
,'man'
,'texinfo'
或任何其他受支持的翻译器,其值为(visit, depart)
方法:研究方法。depart
可None
如果visit
函数提升docutils.nodes.SkipNode
。示例: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节点类注册为数字图目标。
Sphinx会自动为节点编号。然后用户可以使用它来引用它
numref
。- 参数:
node -- 一个节点类
figtype -- 可枚举节点的类型。每个图形类型都有单独的编号序列。作为系统的图形类型,
figure
,table
和code-block
都是定义的。可以向这些默认地物类型添加自定义节点。如果给出了新的图形类型,也可以定义新的定制图形类型。title_getter -- 获取节点标题的getter函数。它接受可枚举节点的实例,并且必须以字符串形式返回其标题。标题用于引用的默认标题
ref
。默认情况下,Sphinx搜索docutils.nodes.caption
或docutils.nodes.title
从节点作为标题。kwargs -- 每个构建器的访问者函数(与
add_node()
)override -- 如果为True,则强制安装该节点,即使已经安装了同名的另一个节点
Added in version 1.4.
- Sphinx.add_directive(name: str, cls: type[Directive], override: bool = False) None [源代码]¶
注册Docutils指令。
- 参数:
name -- 指令的名称
cls -- 指令性类
override -- 如果为False,则如果已经安装了同名的另一个指令,则不要安装该指令。如果为True,则无条件地安装该指令。
例如,名为的自定义指令
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 -- 如果为False,则如果已经安装了同名的另一个角色,则不要安装该角色。如果为True,则无条件安装该角色。
有关角色函数的更多详细信息,请参见 the Docutils docs 。
在 1.8 版本发生变更: 增列 override 关键字。
- Sphinx.add_generic_role(name: str, nodeclass: type[Node], override: bool = False) None [源代码]¶
注册通用Docutils角色。
注册一个Docutils角色,该角色除了将其内容包装在 nodeclass 。
- 参数:
override -- 如果为False,则如果已经安装了同名的另一个角色,则不要安装该角色。如果为True,则无条件安装该角色。
Added in version 0.6.
在 1.8 版本发生变更: 增列 override 关键字。
- Sphinx.add_domain(domain: type[Domain], override: bool = False) None [源代码]¶
注册域。
- 参数:
domain -- A域类
override -- 如果为False,则如果另一个域已安装为相同名称,则不要安装它。如果为True,则无条件地安装域。
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 -- 如果为False,则如果已经安装了同名的另一个指令,则不要安装该指令。如果为True,则无条件地安装该指令。
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 -- 如果为False,则如果已经安装了同名的另一个角色,则不要安装该角色。如果为True,则无条件安装该角色。
Added in version 1.0.
在 1.8 版本发生变更: 增列 override 关键字。
- Sphinx.add_index_to_domain(domain: str, index: type[Index], _override: bool = False) None [源代码]¶
注册域的自定义索引。
添加自定义 index 类初始化为名为的域 domain 。
- 参数:
domain -- 目标域的名称
index -- 索引类
override -- 如果为False,则如果已经安装了同名的另一个索引,则不要安装该索引。如果为True,则无条件地安装该索引。
Added in version 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,则即使已安装具有相同名称的对象类型,也会强制安装给定的对象类型。
在 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 [源代码]¶
注册新的CrossRef对象类型。
这种方法非常类似于
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修复无效节点。翻译文档树。
100-299
制备
300-399
早些时候
400-699
主干道
700-799
后处理。修改文本和引用的截止日期。
800-899
收集引用和引用的节点。域处理。
900-999
最后敲定并清理。
- 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
当扩展调用此方法时,可以将JavaScript文件添加到特定的HTML页面
html-page-context
事件。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
当扩展调用此方法时,可以将CSS文件添加到特定的HTML页面
html-page-context
事件。Added in version 1.0.
在 1.6 版本发生变更: 任选
alternate
and/ortitle
attributes can be supplied with the arguments alternate (a Boolean) and title (a string). The default is no title and alternate =False
. For more information, refer to the documentation 。在 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 版本发生变更: 将lexer类作为参数。
在 4.0 版本发生变更: 删除了对词法分析器实例作为参数的支持。
- Sphinx.add_autodocumenter(cls: type[Documenter], override: bool = False) None [源代码]¶
为AutoDoc扩展注册新的Documenter类。
增列 cls 作为新的文档生成器类
sphinx.ext.autodoc
分机。它必须是的子类sphinx.ext.autodoc.Documenter
。这允许自动记录新类型的对象。有关如何子类化的示例,请参阅AutoDoc模块的源代码Documenter
。如果 override 是真的吗,给定的 cls 即使已经安装了同名的文档管理器,也会强制安装。
看见 开发autodoc扩展 。
Added in version 0.6.
在 2.2 版本发生变更: 增列 override 关键字。
- Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str, Any], Any]) None [源代码]¶
注册一个新的
getattr
-AutoDoc扩展的类似功能。增列 getter ,它必须是一个具有与
getattr()
作为作为实例的对象的AutoDoc属性getter typ 。AutoDoc需要获取类型属性的所有情况都由此函数处理,而不是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 -- 如果为FALSE,则不要安装已安装的相同后缀。如果为True,则无条件安装后缀。
Added in version 1.8.
- Sphinx.add_source_parser(parser: type[Parser], override: bool = False) None [源代码]¶
注册一个解析器类。
- 参数:
override -- 如果为False,则如果已经为相同后缀安装了另一个解析器,则不要安装它。如果为True,则无条件安装解析器。
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 | os.PathLike[str]) None [源代码]¶
注册一个HTML主题。
这个 name 是一个主题名称,并且 theme_path 是主题的完整路径(参考: 将主题作为Python包分发 )。
Added in version 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编写器的访问函数:前者用于内联数学节点 (
nodes.math
),后者用于块数学节点 (nodes.math_block
)。有关访问者函数,请参见add_node()
了解更多细节。Added in version 1.8.
- Sphinx.add_message_catalog(catalog: str, locale_dir: str | os.PathLike[str]) None [源代码]¶
注册消息目录。
- 参数:
catalog -- 目录的名称
locale_dir -- 消息目录的基本路径
有关更多详细信息,请参阅
sphinx.locale.get_translation()
。Added in version 1.8.
- Sphinx.set_html_assets_policy(policy: Literal['always', 'per_page']) None [源代码]¶
设置策略以将资产包含在HTML页面中。
始终:将资产包含在所有页面中
per_page:仅在使用资产的页面中包含资产
- exception sphinx.application.ExtensionError¶
如果扩展API出现问题,所有这些方法都会引发此异常。
正在发出事件¶
- class sphinx.application.Sphinx[源代码]
Sphinx运行时信息¶
应用程序对象还将运行时信息作为属性提供。
- Sphinx.srcdir¶
源目录。
- Sphinx.confdir¶
包含以下内容的目录
conf.py
。
- Sphinx.doctreedir¶
用于存储腌制文档树的目录。
- Sphinx.outdir¶
用于存储生成的文档的目录。
- Sphinx.fresh_env_used¶
是否为此构建创建了新环境是真/假,或者如果环境尚未初始化,则为无。
Sphinx核心事件¶
备注
搬到 事件回调API .
检查Sphinx版本¶
使用它使您的扩展适应Sphinx中的API更改。
- sphinx.version_info: Final = (8, 3, 0, 'beta', 0)¶
版本信息,以便更好地编程使用。
五个元素的元组;对于Sphinx版本1.2.1测试版3,这将是
(1, 2, 1, 'beta', 3)
。第四个元素可以是以下元素之一:alpha
,beta
,rc
,final
。final
始终将0作为最后一个元素。Added in version 1.2: 在1.2版之前,请检查字符串
sphinx.__version__
。
配置对象¶
模板桥¶
- 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
对象或无;在后一种情况下, dirs 可以在固定目录列表中查找模板。
例外情况¶
- exception sphinx.errors.SphinxError[源代码]¶
Sphinx错误的基类。
这是“好的”异常的基类。当引发此类异常时,Sphinx将中止构建,并向用户显示异常类别和消息。
鼓励扩展从该异常派生其自定义错误。
例外情况 not 派生自
SphinxError
被视为意外,并向用户显示部分回溯(以及保存在临时文件中的完整回溯)。- category¶
异常类别的描述,用于将异常转换为字符串(“CATEGORY:MESSAGE”)。应该在子类中相应地设置。