Commits

Anonymous committed b83b386

Add documentation and automatic entries for the guide element

  • Participants
  • Parent commits 4243d9a

Comments (0)

Files changed (4)

    This builder produces the same output as the standalone HTML builder, but
    also generates an *epub* file for ebook readers.  See :ref:`epub-faq` for
    details about it.  For definition of the epub format, have a look at
-   `<http://www.idpf.org/specs.htm>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_.
+   `<http://idpf.org/epub>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_.
+   The builder creates *EPUB 2* files.
 
    Some ebook readers do not show the link targets of references.  Therefore
    this builder adds the targets after the link when necessary.  The display
 
    .. versionadded:: 1.1
 
+.. confval:: epub_guide
+
+   Meta data for the guide element of :file:`content.opf`. This is a
+   sequence of tuples containing the *type*, the *uri* and the *title* of
+   the optional guide information. See the OPF documentation
+   at `<http://idpf.org/epub>`_ for details. If possible, default entries
+   for the *cover* and *toc* types are automatically inserted. However,
+   the types can be explicitely overwritten if the default entries are not
+   appropriate. Example::
+
+      epub_guide = (('cover', 'cover.html', u'Cover Page'),)
+
+   The default value is ``()``.
+
 .. confval:: epub_pre_files
 
    Additional files that should be inserted before the text generated by

sphinx/builders/epub.py

 
 _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',
 
         # 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:
                     })
                 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)

sphinx/quickstart.py

 # 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 = []