Anonymous avatar Anonymous committed 6c8807e

Added epub_fix_images configuration option

Comments (0)

Files changed (5)

 epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
     '_static/jquery.js', '_static/searchtools.js', '_static/underscore.js',
     '_static/basic.css', 'search.html']
+epub_fix_images = False
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual', 1)]
    a chapter, but can be confusing because it mixes entries of differnet
    depth in one list.  The default value is ``True``.
+.. confval:: epub_fix_images
+   This flag determines if sphinx should try to fix image formats that are not
+   supported by some epub readers.  At the moment palette images with a small
+   color table are upgraded.  You need the Python Image Library (PIL) installed
+   to use this option.  The default value is ``False`` because the automatic
+   conversion may loose information.
 .. _latex-options:
 Options for LaTeX output


 import zipfile
 from os import path
+    from PIL import Image
+except ImportError:
+    try:
+        import Image
+    except ImportError:
+        Image = None
 from docutils import nodes
 from sphinx import addnodes
 from import StandaloneHTMLBuilder
-from sphinx.util.osutil import EEXIST
+from sphinx.util.osutil import ensuredir, EEXIST
 from sphinx.util.smartypants import sphinx_smarty_pants as ssp
+from sphinx.util.console import brown
 # (Fragment) templates from which the metainfo files content.opf, toc.ncx,
                             subentrylinks[i] = \
+    def copy_image_files_pil(self):
+        """Copy images using the PIL.
+        The method tries to read and write the files with the PIL,
+        converting the format if necessary/possible.
+        """
+        ensuredir(path.join(self.outdir, '_images'))
+        for src in self.status_iterator(self.images, 'copying images... ',
+                                        brown, len(self.images)):
+            dest = self.images[src]
+            try:
+                img =, src))
+            except IOError:
+                self.warn('cannot read image file %r: copying it instead' %
+                          (path.join(self.srcdir, src), ))
+                try:
+                    copyfile(path.join(self.srcdir, src),
+                             path.join(self.outdir, '_images', dest))
+                except Exception, err:
+                    self.warn('cannot copy image file %r: %s' %
+                              (path.join(self.srcdir, src), err))
+                continue
+            if img.mode in ('P',):
+                # See PIL documentation for Image.convert()
+                img = img.convert()
+            try:
+      , '_images', dest))
+            except IOError, err:
+                self.warn('cannot write image file %r: %s' %
+                          (path.join(self.srcdir, src), err))
+    def copy_image_files(self):
+        """Copy image files to destination directory.
+        This overwritten method can use the PIL to convert image files.
+        """
+        if self.images:
+            if self.config.epub_fix_images:
+                if not Image:
+                    self.warn('PIL not found - copying image files')
+                    super(EpubBuilder, self).copy_image_files()
+                else:
+                    self.copy_image_files_pil()
+            else:
+                super(EpubBuilder, self).copy_image_files()
     def handle_page(self, pagename, addctx, templatename='page.html',
                     outfilename=None, event_arg=None):
         """Create a rendered page.
         epub_exclude_files = ([], 'env'),
         epub_tocdepth = (3, 'env'),
         epub_tocdup = (True, 'env'),
+        epub_fix_images = (False, 'html'),
         # LaTeX options
         latex_documents = ([], None),


 # Allow duplicate toc entries.
 #epub_tocdup = True
+# Fix unsupported image types using the PIL.
+#epub_fix_images = False
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.