Takayuki Shimizukawa committed ae2a242 Merge

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

new predefined tags; epub fixes.

Comments (0)

Files changed (9)

    `<>`_ or `<>`_.
    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::
 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)]
    * ``'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
 Epub info
-The epub builder is currently in an experimental stage.  It has only been tested
-with the Sphinx documentation itself.  If you want to create epubs, here are
-some notes:
+The following list gives some hints for the creation of epub files:
 * 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
   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:
 .. _Calibre:
 .. _FBreader:


    within :file:``) 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
-   set as a tag.
+   The *format* and the *name* of the current builder (``html``, ``latex`` or
+   ``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.
    means that by default, Sphinx generates such column specs for such tables.
    Use the :rst:dir:`tabularcolumns` directive to get finer control over such
+.. 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.


         self.config = app.config
         self.tags = app.tags
+        self.tags.add(
+        self.tags.add("format_%s" % self.format)
+        self.tags.add("builder_%s" %
         # images that need to be copied over (source -> dest)
         self.images = {}


 # 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 = {
         # 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):
-        """Replace all characters not allowed for (X)HTML ids."""
-        return name.replace('/', '_').replace(' ', '')
+    def make_id(self, name, id_cache={}):
+        # id_cache is intentionally mutable
+        """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."""
         # 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


                 raise IndexError
         except IndexError:
             targetnode = None
+        newnode = node.deepcopy()
+        del newnode['ids']
             'docname': env.docname,
             'source': node.source or env.doc2path(env.docname),
             'lineno': node.line,
-            'todo': node.deepcopy(),
+            'todo': newnode,
             'target': targetnode,


 {%- extends "basic/layout.html" %}
+{%- block doctype -%}
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
+  "">
+{%- endblock -%}
 {# add only basic navigation links #}
 {% block sidebar1 %}{% endblock %}
 {% block sidebar2 %}{% endblock %}