公用事业

sphinx提供实用程序类和函数来开发扩展。

组件的基类

这些基类对于允许扩展获得sphinx组件（例如 Config ， BuildEnvironment 等等）很容易。

备注

它们的子类可能不适用于裸docutils，因为它们与Sphinx紧密耦合。

class sphinx.transforms.SphinxTransform(document, startnode=None)

转换的基类。

与之相比 docutils.transforms.Transform ，该类提高了对sphinx API的可访问性。

property app: Sphinx

参考 Sphinx 对象。

property config: Config

参考 Config 对象。

property env: BuildEnvironment

参考 BuildEnvironment 对象。

class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)

后转换的基类。

调用后期转换来修改文档以重新构造文档以进行输出。它们解析引用、转换图像、对每种输出格式进行特殊转换等等。这个类帮助实现这些POST转换。

apply(**kwargs: Any) → None

重写以将转换应用于文档树。

is_supported() → bool

检查当前生成器的此转换。

run(**kwargs: Any) → None

后置变换的主要方法。

子类应重写此方法，而不是 apply() .

class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Sphinx指令的基类。

此类为sphinx指令提供助手方法。

备注

此类的子类可能无法与docutils一起使用。这一类与Sphinx是强耦合的。

get_location() → str

获取用于记录的当前位置信息。

get_source_info() → tuple[str, int]

获取源和行号。

set_source_info(node: Node) → None

将源和行号设置为节点。

property config: Config

参考 Config 对象。

property env: BuildEnvironment

参考 BuildEnvironment 对象。

class sphinx.util.docutils.SphinxRole

Sphinx角色的基类。

这个类为sphinx角色提供帮助方法。

备注

此类的子类可能无法与docutils一起使用。这一类与Sphinx是强耦合的。

get_location() → str

获取用于记录的当前位置信息。

property config: Config

参考 Config 对象。

content: Sequence[str]

字符串列表，用于定制的指令内容(来自“Role”指令)。

property env: BuildEnvironment

参考 BuildEnvironment 对象。

inliner: Inliner

这个 docutils.parsers.rst.states.Inliner 对象。

lineno: int

解释文本开始的行号。

name: str

文档中实际使用的角色名。

options: dict[str, Any]

用于定制的指令选项词典(来自“角色”指令)。

rawtext: str

包含整个解释文本输入的字符串。

text: str

解释文本内容。

class sphinx.util.docutils.ReferenceRole

引用角色的基类。

参考角色可以接受 link title <target> 角色的文本样式。解析结果；链接标题和目标将存储到 self.title 和 self.target 。

disabled: bool

布尔值表示引用被禁用。

has_explicit_title: bool

布尔值表示角色是否具有显式标题。

target: str

解释文本的链接目标。

title: str

解释文本的链接标题。

class sphinx.transforms.post_transforms.images.ImageConverter(*args: Any, **kwargs: Any)

图像转换器的基类。

图像转换器是一种Docutils转换模块。它用于将构建器不支持的图像文件转换为该构建器的适当格式。

例如, LaTeX builder 支持PDF、PNG和JPEG作为图像格式。但是，它不支持SVG图像。对于这种情况，使用图像转换器可以将这些不受支持的图像嵌入到文档中。其中一个图像转换器； sphinx.ext.imgconverter 可以在内部使用Imagemagick将SVG图像转换为PNG格式。

制作自定义图像转换器有三个步骤：

1. 生成的子类 ImageConverter 班

2. 重写 conversion_rules ， is_available() 和 convert()

3. 使用将图像转换器注册到Sphinx Sphinx.add_post_transform()

convert(_from: str, _to: str) → bool

将图像文件转换为预期的格式。

_from 是源图像文件的路径，并且 _to 是目标文件的路径。

is_available() → bool

返回图像转换器是否可用。

available: bool | None = None

转换器是否可用。将在第一次调用生成时填充。结果在同一过程中共享。

待处理

应该对其进行重构，使其不存储没有类变量的状态。

conversion_rules: list[tuple[str, str]] = []

图像转换器支持的转换规则。它表示为一对源图像格式（mimetype）和目标图像格式的列表：

conversion_rules = [
    ('image/svg+xml', 'image/png'),
    ('image/gif', 'image/png'),
    ('application/pdf', 'image/png'),
]

default_priority = 200

此转换的数字优先级，从0到999(覆盖)。

公用设施组件

class sphinx.events.EventManager(app: Sphinx)

Sphinx的事件管理器。

add(name: str) → None

注册自定义Sphinx事件。

connect(name: str, callback: Callable, priority: int) → int

将处理程序连接到特定事件。

disconnect(listener_id: int) → None

断开处理程序。

emit(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list

触发一个 Sphinx 事件。

emit_firstresult(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any

发出sphinx事件并返回第一个结果。

这将返回第一个不返回的处理程序的结果 None .

实用程序类型

class sphinx.util.typing.ExtensionMetadata

由扩展的 setup() 功能。

看见 扩展元数据 。

env_version: int

一个整数，用于标识扩展添加的环境数据的版本。

parallel_read_safe: bool

指示扩展是否支持并行读取源文件。

parallel_write_safe: bool

指示扩展名是否支持并行写入输出文件(默认为： True )。

version: str

扩展版本(默认为： 'unknown version' )。