diff --git a/doc/builders.rst b/doc/builders.rst index 0075ad810..1297a08e4 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -84,11 +84,6 @@ The builder's "name" must be given to the **-b** command-line option of ``_ 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:: sphinx.builders.latex diff --git a/doc/conf.py b/doc/conf.py index 6e792b6a3..08149fba5 100644 --- a/doc/conf.py +++ b/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)] diff --git a/doc/config.rst b/doc/config.rst index 70adbfe0c..24334f363 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -956,6 +956,9 @@ the `Dublin Core metadata `_. * ``'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 diff --git a/doc/faq.rst b/doc/faq.rst index e1c95b08e..ff74be1c8 100644 --- a/doc/faq.rst +++ b/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 -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 @@ -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/ diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index f5eaac9ce..10ba491e9 100644 --- a/doc/markup/misc.rst +++ b/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 - 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. 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. diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 026cbdb77..15ac62c7a 100644 --- a/sphinx/builders/__init__.py +++ b/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 = {} diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 2ddaf5c92..035cec6ca 100644 --- a/sphinx/builders/epub.py +++ b/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): - """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.""" @@ -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 diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py index 32108b1e9..de5d2b9fe 100644 --- a/sphinx/ext/todo.py +++ b/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, }) diff --git a/sphinx/themes/epub/layout.html b/sphinx/themes/epub/layout.html index c2e2e0fd5..437133779 100644 --- a/sphinx/themes/epub/layout.html +++ b/sphinx/themes/epub/layout.html @@ -9,6 +9,10 @@ #} {%- extends "basic/layout.html" %} +{%- block doctype -%} + +{%- endblock -%} {# add only basic navigation links #} {% block sidebar1 %}{% endblock %} {% block sidebar2 %}{% endblock %}