Added epub_cover configuration option.

doc/config.rst

@@ -753,6 +753,20 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    A unique identifier for the document.  This is put in the Dublin Core
    metadata.  You may use a random string.  The default value is ``'unknown'``.
 
+.. confval:: epub_cover
+
+   The cover page information.  This is a tuple containing the filenames of
+   the cover image and the html template.  The rendered html cover page is
+   inserted as the first item in the spine in :file:`content.opf`.  If the
+   template filename is empty, no html cover page is created.  No cover at all
+   is created if the tuple is empty.  Examples::
+
+      epub_cover = ('_static/cover.png', 'epub-cover.html')
+      epub_cover = ('_static/cover.png', '')
+      epub_cover = ()
+
+   The default value is ``()``.
+
 .. confval:: epub_pre_files
 
    Additional files that should be inserted before the text generated by

sphinx/builders/epub.py

@@ -97,6 +97,12 @@ _content_template = u'''\
 </package>
 '''
 
+_cover_template = u'''\
+    <meta name="cover" content="%(cover)s"/>
+'''
+
+_coverpage_name = 'epub-cover.html'
+
 _file_template = u'''\
     <item id="%(id)s"
           href="%(href)s"
@@ -388,7 +394,6 @@ class EpubBuilder(StandaloneHTMLBuilder):
                     'media_type': self.esc(_media_types[ext])
                 })
                 self.files.append(filename)
-        projectfiles = '\n'.join(projectfiles)
 
         # spine
         spine = []
@@ -400,12 +405,38 @@ class EpubBuilder(StandaloneHTMLBuilder):
             spine.append(_spine_template % {
                 'idref': self.esc(self.make_id(item['refuri']))
             })
+
+        # add the optional cover
+        content_tmpl = _content_template[:]
+        if self.config.epub_cover:
+            image, tmpl = self.config.epub_cover
+            mpos = content_tmpl.rfind('</metadata>')
+            cpos = content_tmpl.rfind('\n', 0 , mpos) + 1
+            content_tmpl = content_tmpl[:cpos] + \
+                _cover_template % {'cover': self.esc(self.make_id(image))} + \
+                content_tmpl[cpos:]
+            if tmpl:
+                spine.insert(0, _spine_template % {
+                    'idref': self.esc(self.make_id(_coverpage_name))})
+                if _coverpage_name not in self.files:
+                    ext = path.splitext(_coverpage_name)[-1]
+                    self.files.append(_coverpage_name)
+                    projectfiles.append(_file_template % {
+                        'href': self.esc(_coverpage_name),
+                        'id': self.esc(self.make_id(_coverpage_name)),
+                        'media_type': self.esc(_media_types[ext])
+                    })
+                ctx = {'image': self.esc(image), 'title': self.config.project}
+                self.handle_page(
+                        os.path.splitext(_coverpage_name)[0], ctx, tmpl)
+
+        projectfiles = '\n'.join(projectfiles)
         spine = '\n'.join(spine)
 
         # write the project file
         f = codecs.open(path.join(outdir, outname), 'w', 'utf-8')
         try:
-            f.write(_content_template % \
+            f.write(content_tmpl % \
                 self.content_metadata(projectfiles, spine))
         finally:
             f.close()

sphinx/config.py

@@ -120,6 +120,7 @@ class Config(object):
         epub_identifier = ('unknown', 'html'),
         epub_scheme = ('unknown', 'html'),
         epub_uid = ('unknown', 'env'),
+        epub_cover = ((), 'env'),
         epub_pre_files = ([], 'env'),
         epub_post_files = ([], 'env'),
         epub_exclude_files = ([], 'env'),

sphinx/quickstart.py

@@ -266,6 +266,9 @@ epub_copyright = u'%(copyright_str)s'
 # A unique identification for the text.
 #epub_uid = ''
 
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
 # HTML files that should be inserted before the pages created by sphinx.
 # The format is a list of tuples containing the path and title.
 #epub_pre_files = []

sphinx/themes/epub/epub-cover.html

@@ -0,0 +1,24 @@
+{#
+    epub/epub-cover.html
+    ~~~~~~~~~~~~~~~~~~~~
+
+    Sample template for the html cover page.
+
+    :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+#}
+{% extends "layout.html" %}
+{%- block rootrellink %}{% endblock %}
+{%- block relbaritems %}{% endblock %}
+{%- block sidebarlogo %}{% endblock %}
+{%- block linktags %}{% endblock %}
+{%- block relbar1 %}{% endblock %}
+{%- block sidebar1 %}{% endblock %}
+{%- block sidebar2 %}{% endblock %}
+{%- block footer %}{% endblock %}
+
+{% block content %}
+  <div class="epub-cover">
+    <img src="{{ image }}" alt="Cover image" />
+  </div>
+{% endblock %}