Commits

Anonymous committed b83b386

Add documentation and automatic entries for the guide element

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 = []
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 ProjectModifiedEvent.java.
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.