diff options
| -rw-r--r-- | doc/conf.py | 2 | ||||
| -rw-r--r-- | doc/config.rst | 17 | ||||
| -rw-r--r-- | sphinx/builders/epub.py | 62 | ||||
| -rw-r--r-- | sphinx/config.py | 2 | ||||
| -rw-r--r-- | sphinx/quickstart.py | 6 |
5 files changed, 88 insertions, 1 deletions
diff --git a/doc/conf.py b/doc/conf.py index a1d0e8ce..19b95294 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -37,6 +37,8 @@ epub_pre_files = [('index.html', 'Welcome')] 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 +epub_max_image_width = 0 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation', 'Georg Brandl', 'manual', 1)] diff --git a/doc/config.rst b/doc/config.rst index d8a07fa9..1260796a 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -869,6 +869,23 @@ the `Dublin Core metadata <http://dublincore.org/>`_. 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. + +.. confval:: epub_max_image_width + + This option specifies the maximum width of images. If it is set to a value + greater than zero, images with a width larger than the given value are + scaled accordingly. If it is zero, no scaling is performed. The default + value is ``0``. You need the Python Image Library (PIL) installed to use + this option. + + .. _latex-options: Options for LaTeX output diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index e946e0d3..3ee4de5f 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -18,12 +18,21 @@ import codecs import zipfile from os import path +try: + from PIL import Image +except ImportError: + try: + import Image + except ImportError: + Image = None + from docutils import nodes from sphinx import addnodes from sphinx.builders.html 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, @@ -301,6 +310,57 @@ class EpubBuilder(StandaloneHTMLBuilder): subentrylinks[i] = (ismain, self.fix_fragment(m.group(1), m.group(2))) + 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 and resizing the image 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 = Image.open(path.join(self.srcdir, 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 self.config.epub_fix_images: + if img.mode in ('P',): + # See PIL documentation for Image.convert() + img = img.convert() + if self.config.epub_max_image_width > 0: + (width, height) = img.size + nw = self.config.epub_max_image_width + if width > nw: + nh = (height * nw) / width + img = img.resize((nw, nh), Image.BICUBIC) + try: + img.save(path.join(self.outdir, '_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 or self.config.epub_max_image_width: + 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. diff --git a/sphinx/config.py b/sphinx/config.py index f4c0946b..d4aacb22 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -136,6 +136,8 @@ class Config(object): epub_exclude_files = ([], 'env'), epub_tocdepth = (3, 'env'), epub_tocdup = (True, 'env'), + epub_fix_images = (False, 'env'), + epub_max_image_width = (0, 'env'), # LaTeX options latex_documents = ([], None), diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 0818ad0a..d606e7ad 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -315,6 +315,12 @@ epub_copyright = u'%(copyright_str)s' # Allow duplicate toc entries. #epub_tocdup = True + +# Fix unsupported image types using the PIL. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 ''' INTERSPHINX_CONFIG = ''' |