Merged in rolmei/sphinx-epub (pull request #148)

new predefined tags; epub fixes.

doc/builders.rst

@@ -84,11 +84,6 @@ The builder's "name" must be given to the **-b** command-line option of
    `<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
-   of the URLs can be customized by adding CSS rules for the class
-   ``link-target``.
-
    Its name is ``epub``.
 
 .. module:: sphinx.builders.latex

doc/conf.py

@@ -44,6 +44,7 @@ epub_fix_images = False
 epub_max_image_width = 0
 epub_show_urls = 'inline'
 epub_use_index = False
+epub_guide = (('toc', 'contents.html', u'Table of Contents'),)
 
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual', 1)]

doc/config.rst

@@ -956,6 +956,9 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    * ``'footnote'`` -- display URLs in footnotes
    * ``'no'`` -- do not display URLs
 
+   The display of inline URLs can be customized by adding CSS rules for the
+   class ``link-target``.
+
    .. versionadded:: 1.2
 
 .. confval:: epub_use_index

doc/faq.rst

@@ -126,9 +126,7 @@ Google Analytics
 Epub info
 ---------
 
-The epub builder is currently in an experimental stage.  It has only been tested
+The following list gives some hints for the creation of epub files:
-with the Sphinx documentation itself.  If you want to create epubs, here are
-some notes:
 
 * Split the text into several files. The longer the individual HTML files are,
   the longer it takes the ebook reader to render them.  In extreme cases, the
@@ -162,6 +160,12 @@ some notes:
   included. This sometimes applies to appendixes, e.g. the glossary or
   the indices.  You can add them with the :confval:`epub_post_files` option.
 
+* The handling of the epub cover page differs from the reStructuredText
+  procedure which automatically resolves image paths and puts the images
+  into the ``_images`` directory.  For the epub cover page put the image in the
+  :confval:`html_static_path` directory and reference it with its full path in
+  the :confval:`epub_cover` config option.
+
 .. _Epubcheck: http://code.google.com/p/epubcheck/
 .. _Calibre: http://calibre-ebook.com/
 .. _FBreader: http://www.fbreader.org/

doc/markup/misc.rst

@@ -179,10 +179,15 @@ Including content based on tags
    within :file:`conf.py`) are true.  Boolean expressions, also using
    parentheses (like ``html and (latex or draft)``) are supported.
 
-   The format of the current builder (``html``, ``latex`` or ``text``) is always
+   The *format* and the *name* of the current builder (``html``, ``latex`` or
-   set as a tag.
+   ``text``) are always set as a tag [#]_.  To make the distinction between
+   format and name explicit, they are also added with the prefix ``format_`` and
+   ``builder_``, e.g. the epub builder defines the tags  ``html``, ``epub``,
+   ``format_html`` and ``builder_epub``.
 
    .. versionadded:: 0.6
+   .. versionchanged:: 1.2
+      Added the name of the builder and the prefixes.
 
 
 Tables
@@ -238,3 +243,9 @@ following directive exists:
    means that by default, Sphinx generates such column specs for such tables.
    Use the :rst:dir:`tabularcolumns` directive to get finer control over such
    tables.
+
+.. rubric:: Footnotes
+
+.. [#] For most builders name and format are the same. At the moment only
+       builders derived from the html builder distinguish between the builder
+       format and the builder name.

sphinx/builders/__init__.py

@@ -58,6 +58,9 @@ class Builder(object):
         self.config = app.config
         self.tags = app.tags
         self.tags.add(self.format)
+        self.tags.add(self.name)
+        self.tags.add("format_%s" % self.format)
+        self.tags.add("builder_%s" % self.name)
 
         # images that need to be copied over (source -> dest)
         self.images = {}

sphinx/builders/epub.py

@@ -140,7 +140,7 @@ _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'
+    'cover': u'Cover'
 }
 
 _media_types = {
@@ -188,14 +188,20 @@ class EpubBuilder(StandaloneHTMLBuilder):
         # the output files for epub must be .html only
         self.out_suffix = '.html'
         self.playorder = 0
+        self.tocid = 0
 
     def get_theme_config(self):
         return self.config.epub_theme, self.config.epub_theme_options
 
     # generic support functions
-    def make_id(self, name):
+    def make_id(self, name, id_cache={}):
-        """Replace all characters not allowed for (X)HTML ids."""
+        # id_cache is intentionally mutable
-        return name.replace('/', '_').replace(' ', '')
+        """Return a unique id for name."""
+        id = id_cache.get(name)
+        if not id:
+            id = 'epub-%d' % self.env.new_serialno('epub')
+            id_cache[name] = id
+        return id
 
     def esc(self, name):
         """Replace all characters not allowed in text an attribute values."""
@@ -629,8 +635,9 @@ class EpubBuilder(StandaloneHTMLBuilder):
         # XXX Modifies the node
         if incr:
             self.playorder += 1
+        self.tocid += 1
         node['indent'] = _navpoint_indent * level
-        node['navpoint'] = self.esc(_navPoint_template % self.playorder)
+        node['navpoint'] = self.esc(_navPoint_template % self.tocid)
         node['playorder'] = self.playorder
         return _navpoint_template % node
 

sphinx/ext/todo.py

@@ -60,11 +60,13 @@ def process_todos(app, doctree):
                 raise IndexError
         except IndexError:
             targetnode = None
+        newnode = node.deepcopy()
+        del newnode['ids']
         env.todo_all_todos.append({
             'docname': env.docname,
             'source': node.source or env.doc2path(env.docname),
             'lineno': node.line,
-            'todo': node.deepcopy(),
+            'todo': newnode,
             'target': targetnode,
         })
 

sphinx/themes/epub/layout.html

@@ -9,6 +9,10 @@
 #}
 {%- extends "basic/layout.html" %}
 
+{%- block doctype -%}
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+  "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
+{%- endblock -%}
 {# add only basic navigation links #}
 {% block sidebar1 %}{% endblock %}
 {% block sidebar2 %}{% endblock %}