实用工具

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

组件的基类

这些基类有助于您的扩展轻松获取Sphinx组件(例如 Config, BuildEnvironment 等)。

注解

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

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

变换的基类。

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

app

引用 Sphinx 对象。

config

引用 Config 对象。

env

引用 BuildEnvironment 对象。

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

A base class of post-transforms.

Post transforms are invoked to modify the document to restructure it for outputting. They do resolving references, convert images, special transformation for each output formats and so on. This class helps to implement these post transforms.

apply(**kwargs)

Override to apply the transform to the document tree.

is_supported()

Check this transform working for current builder.

run(**kwargs)

main method of post transforms.

Subclasses should override this method instead of apply().

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

Sphinx指令的基类。

该类为Sphinx指令提供了辅助方法。

注解

此类的子类可能不适用于docutils。这个类与Sphinx强烈结合。

set_source_info(node)

Set source and line number to the node.

config

引用 Config 对象。

env

引用 BuildEnvironment 对象。

class sphinx.util.docutils.SphinxRole

Sphinx角色的基类。

此类为Sphinx角色提供帮助方法。

注解

此类的子类可能不适用于docutils。这个类与Sphinx强烈结合。

config

引用 Config 对象。

content = None

字符串列表，用于自定义的指令内容

env

引用 BuildEnvironment 对象。

inliner = None

The docutils.parsers.rst.states.Inliner object.

lineno = None

解释文本开始的行号。

name = None

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

options = None

用于自定义的指令选项字典

rawtext = None

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

text = None

解释的文本内容。

class sphinx.util.docutils.ReferenceRole

参考角色的基类。

引用角色可以接受 link title <target> style 作为角色的文本。 解析后的结果;链接标题和目标将存储到 self.title 和 self.target 。

has_explicit_title = None

布尔值表示角色具有明确的标题。

target = None

解释文本的链接目标。

title = None

解释文本的链接标题。

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

图像转换器的基类。

图像转换器是一种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, _to)

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

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

is_available()

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

conversion_rules = []

图像转换器支持的转换规则。它表示为源图像格式(mimetype)和目标图像对的列表:

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