Add sphinx.ext.imgconverter

.travis.yml

@@ -43,6 +43,7 @@ addons:
     - texlive-xetex
     - lmodern
     - latex-xcolor
+    - imagemagick
 install:
   - pip install -U pip setuptools
   - pip install docutils==$DOCUTILS

CHANGES

@@ -117,6 +117,8 @@ Features added
 * #3641: Epub theme supports HTML structures that are generated by HTML5 writer.
 * #3644 autodoc uses inspect instead of checking types. Thanks to
   Jeroen Demeyer.
+* Add a new extension; ``sphinx.ext.imgconverter``. It converts images in the
+  document to appropriate format for builders
 
 Bugs fixed
 ----------

doc/ext/builtins.rst

@@ -15,6 +15,7 @@ These extensions are built in and can be activated by respective entries in the
    githubpages
    graphviz
    ifconfig
+   imgconverter
    inheritance
    intersphinx
    linkcode

doc/ext/imgconverter.rst

@@ -0,0 +1,25 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.imgconverter` -- Convert images to appropriate format for builders
+===================================================================================
+
+.. module:: sphinx.ext.imgconverter
+   :synopsis: Convert images to appropriate format for builders
+
+.. versionadded:: 1.6
+
+This extension converts images in your document to appropriate format for builders.
+For example, it allows you to use SVG images with LaTeX builder.
+As a result, you don't mind what image format the builder supports.
+
+Internally, this extension uses Imagemagick_ to convert images.
+
+.. _Imagemagick: https://www.imagemagick.org/script/index.php
+
+Configuration
+-------------
+
+.. confval:: image_converter
+
+   A path to :command:`convert` command.  By default, the imgconverter uses
+   the command from search paths.

sphinx/ext/imgconverter.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinx.ext.imgconverter
+    ~~~~~~~~~~~~~~~~~~~~~~~
+
+    Image converter extension for Sphinx
+
+    :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+import subprocess
+
+from sphinx.errors import ExtensionError
+from sphinx.locale import _
+from sphinx.transforms.post_transforms.images import ImageConverter
+from sphinx.util import logging
+from sphinx.util.osutil import ENOENT, EPIPE, EINVAL
+
+if False:
+    # For type annotation
+    from typing import Any, Dict  # NOQA
+    from sphinx.application import Sphinx  # NOQA
+
+
+logger = logging.getLogger(__name__)
+
+
+class ImagemagickConverter(ImageConverter):
+    conversion_rules = [
+        ('image/svg+xml', 'image/png'),
+        ('application/pdf', 'image/png'),
+    ]
+
+    def is_available(self):
+        # type: () -> bool
+        """Confirms the converter is available or not."""
+        try:
+            ret = subprocess.call([self.config.image_converter, '-version'],
+                                  stdin=subprocess.PIPE, stdout=subprocess.PIPE)
+            if ret == 0:
+                return True
+            else:
+                return False
+        except (OSError, IOError):
+            logger.warning(_('convert command %r cannot be run.'
+                             'check the image_converter setting'),
+                           self.config.image_converter)
+            return False
+
+    def convert(self, _from, _to):
+        # type: (unicode, unicode) -> None
+        """Converts the image to expected one."""
+        try:
+            p = subprocess.Popen([self.config.image_converter, _from, _to],
+                                 stdin=subprocess.PIPE, stdout=subprocess.PIPE)
+        except OSError as err:
+            if err.errno != ENOENT:  # No such file or directory
+                raise
+            logger.warning(_('convert command %r cannot be run.'
+                             'check the image_converter setting'),
+                           self.config.image_converter)
+            return False
+
+        try:
+            stdout, stderr = p.communicate()
+        except (OSError, IOError) as err:
+            if err.errno not in (EPIPE, EINVAL):
+                raise
+            stdout, stderr = p.stdout.read(), p.stderr.read()
+            p.wait()
+        if p.returncode != 0:
+            raise ExtensionError(_('convert exited with error:\n'
+                                   '[stderr]\n%s\n[stdout]\n%s') %
+                                 (stderr, stdout))
+
+        return True
+
+
+def setup(app):
+    # type: (Sphinx) -> Dict[unicode, Any]
+    app.add_post_transform(ImagemagickConverter)
+    app.add_config_value('image_converter', 'convert', 'env')
+
+    return {
+        'version': 'builtin',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

sphinx/transforms/post_transforms/images.py

@@ -136,6 +136,105 @@ class DataURIExtractor(BaseImageConverter):
         self.app.env.images.add_file(self.env.docname, path)
 
 
+def get_filename_for(filename, mimetype):
+    # type: (unicode, unicode) -> unicode
+    basename = os.path.basename(filename)
+    return os.path.splitext(basename)[0] + get_image_extension(mimetype)
+
+
+class ImageConverter(BaseImageConverter):
+    """A base class images converter.
+
+    The concrete image converters should derive this class and
+    overrides the following methods and attributes:
+
+    * default_priority (if needed)
+    * conversion_rules
+    * is_available()
+    * convert()
+    """
+    default_priority = 200
+
+    #: A conversion rules between two mimetypes which this converters supports
+    conversion_rules = []
+
+    def __init__(self, *args, **kwargs):
+        # type: (Any, Any) -> None
+        self.available = None  # not checked yet
+        BaseImageConverter.__init__(self, *args, **kwargs)
+
+    def match(self, node):
+        # type: (nodes.Node) -> bool
+        if self.available is None:
+            self.available = self.is_available()
+
+        if not self.available:
+            return False
+        elif set(node['candidates']) & set(self.app.builder.supported_image_types):
+            # builder supports the image; no need to convert
+            return False
+        else:
+            rule = self.get_conversion_rule(node)
+            if rule:
+                return True
+            else:
+                return False
+
+    def get_conversion_rule(self, node):
+        # type: (nodes.Node) -> Tuple[unicode, unicode]
+        for candidate in self.guess_mimetypes(node):
+            for supported in self.app.builder.supported_image_types:
+                rule = (candidate, supported)
+                if rule in self.conversion_rules:
+                    return rule
+
+        return None
+
+    def is_available(self):
+        # type: () -> bool
+        """Confirms the converter is available or not."""
+        raise NotImplemented
+
+    def guess_mimetypes(self, node):
+        # type: (nodes.Node) -> unicode
+        if '?' in node['candidates']:
+            return []
+        elif '*' in node['candidates']:
+            from sphinx.util.images import guess_mimetype
+            return [guess_mimetype(node['uri'])]
+        else:
+            return node['candidates'].keys()
+
+    def handle(self, node):
+        # type: (nodes.Node) -> None
+        _from, _to = self.get_conversion_rule(node)
+
+        if _from in node['candidates']:
+            srcpath = node['candidates'][_from]
+        else:
+            srcpath = node['candidates']['*']
+
+        filename = get_filename_for(srcpath, _to)
+        ensuredir(self.imagedir)
+        destpath = os.path.join(self.imagedir, filename)
+
+        abs_srcpath = os.path.join(self.app.srcdir, srcpath)
+        if self.convert(abs_srcpath, destpath):
+            if '*' in node['candidates']:
+                node['candidates']['*'] = destpath
+            else:
+                node['candidates'][_to] = destpath
+            node['uri'] = destpath
+
+            self.env.original_image_uri[destpath] = srcpath
+            self.env.images.add_file(self.env.docname, destpath)
+
+    def convert(self, _from, _to):
+        # type: (unicode, unicode) -> None
+        """Converts the image to expected one."""
+        raise NotImplemented
+
+
 def setup(app):
     # type: (Sphinx) -> Dict[unicode, Any]
     app.add_post_transform(ImageDownloader)

tests/roots/test-ext-imgconverter/conf.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+master_doc = 'index'
+extensions = ['sphinx.ext.imgconverter']

tests/roots/test-ext-imgconverter/index.rst

@@ -0,0 +1,4 @@
+test-ext-imgconverter
+=====================
+
+.. image:: svgimg.svg

tests/roots/test-ext-imgconverter/svgimg.svg

@@ -0,0 +1,158 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:xlink="http://www.w3.org/1999/xlink"
+   xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   height="60"
+   width="60"
+   _SVGFile__filename="oldscale/apps/warning.svg"
+   version="1.0"
+   y="0"
+   x="0"
+   id="svg1"
+   sodipodi:version="0.32"
+   inkscape:version="0.41"
+   sodipodi:docname="exclamation.svg"
+   sodipodi:docbase="/home/danny/work/icons/primary/scalable/actions">
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0000000"
+     inkscape:pageshadow="2"
+     inkscape:zoom="7.5136000"
+     inkscape:cx="42.825186"
+     inkscape:cy="24.316071"
+     inkscape:window-width="1020"
+     inkscape:window-height="691"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:current-layer="svg1" />
+  <defs
+     id="defs3">
+    <linearGradient
+       id="linearGradient1160">
+      <stop
+         style="stop-color: #000000;stop-opacity: 1.0;"
+         id="stop1161"
+         offset="0" />
+      <stop
+         style="stop-color:#ffffff;stop-opacity:1;"
+         id="stop1162"
+         offset="1" />
+    </linearGradient>
+    <linearGradient
+       xlink:href="#linearGradient1160"
+       id="linearGradient1163" />
+  </defs>
+  <metadata
+     id="metadata12">
+    <RDF
+       id="RDF13">
+      <Work
+         about=""
+         id="Work14">
+        <title
+           id="title15">Part of the Flat Icon Collection (Thu Aug 26 14:31:40 2004)</title>
+        <description
+           id="description17" />
+        <subject
+           id="subject18">
+          <Bag
+             id="Bag19">
+            <li
+               id="li20" />
+          </Bag>
+        </subject>
+        <publisher
+           id="publisher21">
+          <Agent
+             about=""
+             id="Agent22">
+            <title
+               id="title23" />
+          </Agent>
+        </publisher>
+        <creator
+           id="creator24">
+          <Agent
+             about=""
+             id="Agent25">
+            <title
+               id="title26">Danny Allen</title>
+          </Agent>
+        </creator>
+        <rights
+           id="rights28">
+          <Agent
+             about=""
+             id="Agent29">
+            <title
+               id="title30">Danny Allen</title>
+          </Agent>
+        </rights>
+        <date
+           id="date32" />
+        <format
+           id="format33">image/svg+xml</format>
+        <type
+           id="type35"
+           resource="http://purl.org/dc/dcmitype/StillImage" />
+        <license
+           id="license36"
+           resource="http://creativecommons.org/licenses/LGPL/2.1/">
+          <date
+             id="date37" />
+        </license>
+        <language
+           id="language38">en</language>
+      </Work>
+    </RDF>
+    <rdf:RDF
+       id="RDF40">
+      <cc:Work
+         rdf:about=""
+         id="Work41">
+        <dc:format
+           id="format42">image/svg+xml</dc:format>
+        <dc:type
+           id="type44"
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     id="g2099">
+    <path
+       style="color:#000000;fill:none;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#ffffff;stroke-width:8.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;marker:none;marker-start:none;marker-mid:none;marker-end:none"
+       d="M 55.311891,51.920745 L 4.6880989,51.920744 L 29.999995,8.0792542 L 55.311891,51.920745 z "
+       id="path1724" />
+    <path
+       style="color:#000000;fill:#ffe940;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#000000;stroke-width:3.1250010;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;marker:none;marker-start:none;marker-mid:none;marker-end:none"
+       d="M 55.311891,51.920745 L 4.6880989,51.920744 L 29.999995,8.0792542 L 55.311891,51.920745 z "
+       id="path1722" />
+    <path
+       style="font-size:12.000000;font-weight:900;fill:none;fill-opacity:1.0000000;stroke:#ffffff;stroke-width:8.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-opacity:1.0000000"
+       d="M 34.944960,10.779626 L 34.944960,33.186510 C 34.944960,34.752415 34.501979,36.081368 33.616007,37.173380 C 32.750636,38.265402 31.545298,38.811408 29.999995,38.811408 C 28.475302,38.811408 27.269965,38.265402 26.383993,37.173380 C 25.498020,36.060767 25.055030,34.731804 25.055030,33.186510 L 25.055030,10.779626 C 25.055030,9.1931155 25.498020,7.8641562 26.383993,6.7927462 C 27.269965,5.7007332 28.475302,5.1547262 29.999995,5.1547262 C 31.009593,5.1547262 31.885265,5.4019740 32.627010,5.8964706 C 33.389356,6.3909681 33.966274,7.0709005 34.357752,7.9362696 C 34.749221,8.7810349 34.944960,9.7288200 34.944960,10.779626 z "
+       id="path1099" />
+    <path
+       style="font-size:12.000000;font-weight:900;fill:#e71c02;fill-opacity:1.0000000;stroke:none;stroke-width:3.1249981;stroke-linecap:round;stroke-linejoin:round;stroke-opacity:1.0000000"
+       d="M 29.999995,3.5986440 C 28.102272,3.5986440 26.318514,4.3848272 25.156245,5.8173940 C 24.028906,7.1806889 23.499995,8.9087770 23.499995,10.786144 L 23.499995,33.192394 C 23.499995,35.036302 24.050685,36.772771 25.156245,38.161144 C 26.318514,39.593721 28.102273,40.379893 29.999995,40.379894 C 31.913354,40.379894 33.697195,39.576736 34.843745,38.129894 C 35.959941,36.754118 36.499995,35.052976 36.499995,33.192394 L 36.499995,10.786144 C 36.499995,9.5413010 36.276626,8.3551469 35.781245,7.2861440 C 35.278844,6.1755772 34.477762,5.2531440 33.468745,4.5986440 C 32.454761,3.9226545 31.264694,3.5986439 29.999995,3.5986440 z "
+       id="path835"
+       sodipodi:nodetypes="cccccccccccc" />
+    <path
+       style="color:#000000;fill:none;fill-opacity:1.0000000;fill-rule:evenodd;stroke:#ffffff;stroke-width:5.0000000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;marker:none;marker-start:none;marker-mid:none;marker-end:none"
+       d="M 36.506243,49.901522 C 36.506243,53.492972 33.591442,56.407773 29.999991,56.407773 C 26.408541,56.407773 23.493739,53.492972 23.493739,49.901522 C 23.493739,46.310071 26.408541,43.395270 29.999991,43.395270 C 33.591442,43.395270 36.506243,46.310071 36.506243,49.901522 z "
+       id="path1727" />
+    <path
+       style="color:#000000;fill:#e71c02;fill-opacity:1.0000000;fill-rule:evenodd;stroke:none;stroke-width:3.1250000;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4.0000000;stroke-dashoffset:0.0000000;stroke-opacity:1.0000000;marker:none;marker-start:none;marker-mid:none;marker-end:none"
+       d="M 36.506243,49.901522 C 36.506243,53.492972 33.591442,56.407773 29.999991,56.407773 C 26.408541,56.407773 23.493739,53.492972 23.493739,49.901522 C 23.493739,46.310071 26.408541,43.395270 29.999991,43.395270 C 33.591442,43.395270 36.506243,46.310071 36.506243,49.901522 z "
+       id="path1725" />
+  </g>
+</svg>

tests/test_ext_imgconverter.py

@@ -0,0 +1,22 @@
+# -*- coding: utf-8 -*-
+"""
+    test_ext_imgconverter
+    ~~~~~~~~~~~~~~~~~~~~~
+
+    Test sphinx.ext.imgconverter extension.
+
+    :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import pytest
+
+
+@pytest.mark.sphinx('latex', testroot='ext-imgconverter')
+def test_ext_imgconverter(app, status, warning):
+    app.builder.build_all()
+
+    content = (app.outdir / 'Python.tex').text()
+    assert '\sphinxincludegraphics{{svgimg}.png}' in content
+    assert not (app.outdir / 'svgimg.svg').exists()
+    assert (app.outdir / 'svgimg.png').exists()