Metadata-Version: 1.1
Name: sphinxcontrib-imagehelper
Version: 1.1.1
Summary: Sphinx extension helper about images
Home-page: https://github.com/tk0miya/sphinxcontrib-imagehelper
Author: Takeshi KOMIYA
Author-email: i.tkomiya@gmail.com
License: BSD
Description: sphinxcontrib-imagehelper
        ==========================
        
        .. image:: https://travis-ci.org/tk0miya/sphinxcontrib-imagehelper.svg?branch=master
           :target: https://travis-ci.org/tk0miya/sphinxcontrib-imagehelper
        
        .. image:: https://coveralls.io/repos/tk0miya/sphinxcontrib-imagehelper/badge.png?branch=master
           :target: https://coveralls.io/r/tk0miya/sphinxcontrib-imagehelper?branch=master
        
        .. image:: https://codeclimate.com/github/tk0miya/sphinxcontrib-imagehelper/badges/gpa.svg
           :target: https://codeclimate.com/github/tk0miya/sphinxcontrib-imagehelper
        
        `sphinxcontrib-imagehelper` is helpers for creating image Sphinx extensions.
        
        Adding new image format support to Sphinx is too boring.
        This helper helps you to create image sphinx extensions.
        
        It provides these features:
        
        * Caching converted images
        * Conseal sphinx directory structure; determine path of images automatically
        * Support common options for image directive (cf. `:height:`, `:scale:`, `:align:`, and so on)
        * Enhance standard imaging directives; `image` and `figure` get capability to embed new image format
        
        With `sphinxcontrib-imagehelper`, all you have to do is only convert new image format to
        well known image formats.
        
        Install
        =======
        
        ::
        
           $ pip install sphinxcontrib-imagehelper
        
        Example
        =======
        
        ::
        
            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')
        
        Helpers
        =======
        
        `sphinxcontrib.imagehelper.add_image_type(app, name, ext, handler)`
            Register a new image type which is identified with file extension `ext`.
            The `handler` is used to convert image formats.
        
        `sphinxcontrib.imagehelper.ImageConverter`
            A handler class for converting image formats. It is used at `add_image_type()`.
            The developers of sphinx-extensions should create a handler class which inherits `ImageConverter`,
            and should override two following methods:
        
            `ImageConverter.option_spec`
                A definition of additional options.
                By default, it is empty dict.
        
            `ImageConverter.get_last_modified_for(self, node)`
                Determine last modified time of target image.
                By default, this method returns the timestamp of the image file.
        
            `ImageConverter.get_filename_for(self, node)`
                Determine a filename of converted image.
                By default, this method returns the filename replaced its extension with '.png'::
        
                    def get_filename_for(self, node):
                        return os.path.splitext(node['uri'])[0] + '.png'
        
            `ImageConverter.convert(self, node, filename, to)`
                Convert image to embedable format.
                By default, this method does nothing.
        
        `sphinxcontrib.imagehelper.add_image_directive(app, name, option_spec={})`
            Add a custom image directive to Sphinx.
            The directive is named as `name`-image (cf. astah-image).
        
            If `option_spec` is given, the new directive accepts custom options.
        
        `sphinxcontrib.imagehelper.add_figure_directive(app, name, option_spec={})`
            Add a custom figure directive to Sphinx.
            The directive is named as `name`-figure (cf. astah-figure).
        
            If `option_spec` is given, the new directive accepts custom options.
        
        `sphinxcontrib.imagehelper.generate_image_directive(name, option_spec={})`
            Generate a custom image directive class. The class is not registered to Sphinx.
            You can enhance the directive class with subclassing.
        
        `sphinxcontrib.imagehelper.generate_figure_directive(name, option_spec={})`
            Generate a custom figure directive class. The class is not registered to Sphinx.
            You can enhance the directive class with subclassing.
        
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Topic :: Documentation
Classifier: Topic :: Documentation :: Sphinx
