sphinxcontrib-imagehelper 1.1.1

sphinxcontrib-imagehelper

sphinxcontrib-imagehelper 是创建图像Sphinx扩展的帮助程序。

将新的图像格式支持添加到Sphinx过于无聊。这个助手可以帮助您创建图像Sphinx扩展。

它提供以下功能

• 缓存转换后的图像

• 隐藏Sphinx目录结构；自动确定图像路径

• 支持图像指令的常用选项（例如：:height:、:scale:、:align:等）

• 增强标准图像指令；image和figure能够嵌入新的图像格式

使用，您只需将新的图像格式转换为已知图像格式即可。

安装

$ pip install sphinxcontrib-imagehelper

示例

from sphinxcontrib.imagehelper import (
    add_image_type, add_image_directive, add_figure_directive, ImageConverter
)

# Declare converter class inherits ImageConverter
class MyImageConverter(ImageConverter):
    # Override `get_filename_for()` to determine filename
    def get_filename_for(self, node):
        # filename is came from its URI and configuration
        hashed = sha1((node['uri'] + self.app.config.some_convert_settings).encode('utf-8')).hexdigest()
        return 'myimage-%s.png' % hashed

    # Override `convert()` to convert new image format to well known image formats (PNG, JPG and so on)
    def convert(self, node, filename, to):
        # Hint: you can refer self.app.builder.format to switch conversion behavior
        succeeded = convert_myimage_to_png(filename, to,
                                           option1=node['option'],
                                           option2=self.app.config.some_convert_settings)
        if succeeded:
            return True  # return True if conversion succeeded
        else:
            return False

def setup(app)
    # Register new image type: myimage
    add_image_type(app, 'my', 'img', MyImageConverter)

    # Register my-image directive
    add_image_directive(app, 'my')

    # Register my-figure directive
    add_figure_directive(app, 'my')

助手

sphinxcontrib.imagehelper.add_image_type(app, name, ext, handler)

使用文件扩展名< cite>ext注册新的图像类型。 handler用于转换图像格式。

sphinxcontrib.imagehelper.ImageConverter

用于转换图像格式的处理程序类。它用于 add_image_type()。sphinx-extensions的开发者应创建一个继承自ImageConverter的处理程序类，并覆盖以下两个方法

ImageConverter.option_spec

额外选项的定义。默认为空字典。

ImageConverter.get_last_modified_for(self, node)

确定目标图像的最后修改时间。默认情况下，此方法返回图像文件的时间戳。

ImageConverter.get_filename_for(self, node)

确定转换后图像的文件名。默认情况下，此方法返回将扩展名替换为‘.png’的文件名。

def get_filename_for(self, node):
    return os.path.splitext(node['uri'])[0] + '.png'

ImageConverter.convert(self, node, filename, to)

将图像转换为可嵌入的格式。默认情况下，此方法不执行任何操作。

sphinxcontrib.imagehelper.add_image_directive(app, name, option_spec={})

将自定义图像指令添加到Sphinx。指令名称为name-image（参见图astah-image）。

如果提供了option_spec，则新指令接受自定义选项。

sphinxcontrib.imagehelper.add_figure_directive(app, name, option_spec={})

将自定义图指令添加到Sphinx。指令名称为name-figure（参见图astah-figure）。

如果提供了option_spec，则新指令接受自定义选项。

sphinxcontrib.imagehelper.generate_image_directive(name, option_spec={})

生成自定义图像指令类。该类未注册到Sphinx。您可以通过子类化增强指令类。

sphinxcontrib.imagehelper.generate_figure_directive(name, option_spec={})

生成自定义图指令类。该类未注册到Sphinx。您可以通过子类化增强指令类。