Add documentation and automatic entries for the guide element

2 files changed, 34 insertions, 4 deletions

diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py
index acf79ec2..b4c3b277 100644
--- a/sphinx/builders/epub.py
+++ b/sphinx/builders/epub.py
@@ -133,6 +133,12 @@ _link_target_template = u' [%(uri)s]'
 
 _css_link_target_class = u'link-target'
 
+# XXX These strings should be localized according to epub_language
+_guide_titles = {
+    'toc': u'Table of Contents',
+    'cover': u'Cover Page'
+}
+
 _media_types = {
     '.html': 'application/xhtml+xml',
     '.css': 'text/css',
@@ -486,14 +492,15 @@ class EpubBuilder(StandaloneHTMLBuilder):
 
         # add the optional cover
         content_tmpl = _content_template
+        html_tmpl = None
         if self.config.epub_cover:
-            image, tmpl = self.config.epub_cover
+            image, html_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:
+            if html_tmpl:
                 spine.insert(0, _spine_template % {
                     'idref': self.esc(self.make_id(_coverpage_name))})
                 if _coverpage_name not in self.files:
@@ -506,17 +513,37 @@ class EpubBuilder(StandaloneHTMLBuilder):
                     })
                 ctx = {'image': self.esc(image), 'title': self.config.project}
                 self.handle_page(
-                        os.path.splitext(_coverpage_name)[0], ctx, tmpl)
+                        os.path.splitext(_coverpage_name)[0], ctx, html_tmpl)
 
         guide = []
+        auto_add_cover = True
+        auto_add_toc = True
         if self.config.epub_guide:
             for type, uri, title in self.config.epub_guide:
+                file = uri.split('#')[0]
+                if file not in self.files:
+                    self.files.append(file)
+                if type == 'cover':
+                    auto_add_cover = False
+                if type == 'toc':
+                    auto_add_toc = False
                 guide.append(_guide_template % {
                         'type': self.esc(type),
                         'title': self.esc(title),
                         'uri': self.esc(uri)
                         })
-
+        if auto_add_cover and html_tmpl:
+            guide.append(_guide_template % {
+                    'type': 'cover',
+                    'title': _guide_titles['cover'],
+                    'uri': self.esc(_coverpage_name)
+                    })
+        if auto_add_toc and self.refnodes:
+            guide.append(_guide_template % {
+                    'type': 'toc',
+                    'title': _guide_titles['toc'],
+                    'uri': self.esc(self.refnodes[0]['refuri'])
+                    })
         projectfiles = '\n'.join(projectfiles)
         spine = '\n'.join(spine)
         guide = '\n'.join(guide)
diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py
index 172382ad..c8dd2579 100644
--- a/sphinx/quickstart.py
+++ b/sphinx/quickstart.py
@@ -309,6 +309,9 @@ epub_copyright = u'%(copyright_str)s'
 # A tuple containing the cover image and cover page html template filenames.
 #epub_cover = ()
 
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
 # 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 = []