From f879346cea94a9964b515ed981ff6e4518fe283d Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Thu, 25 Apr 2013 23:08:30 +0200 Subject: [PATCH 01/10] Add the builder name as predefined tag for the only directive. At the moment only the epub builder distinguishes between format and name. Explicit entries with format_ and builder_ prefix are also added. --- doc/markup/misc.rst | 14 ++++++++++++-- sphinx/builders/__init__.py | 3 +++ 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index f5eaac9ce..d0ace3fa7 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -179,10 +179,14 @@ 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``) is always set as a tag [#]_. To make the distinction between + format and name explicit, they are also added with the prefix ``format_`` and + ``builder_``. .. versionadded:: 0.6 + .. versionchanged:: 1.2 + Added the name of the builder and the prefixes. Tables @@ -238,3 +242,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 + +.. [#] At the moment only the epub builder distinguishes between the builder + format and the builder name. + diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 27a3be7a8..b23487767 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 = {} From 234a600e798dc6cb0c5ad6312f890e627bae64ef Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Mon, 29 Apr 2013 20:42:12 +0200 Subject: [PATCH 02/10] Added XHTML 1.1 document declaration to epub builder --- sphinx/themes/epub/layout.html | 4 ++++ 1 file changed, 4 insertions(+) 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 %} From f1e25afe259075988a1d5248968eb416b5e68d5c Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Mon, 29 Apr 2013 21:23:05 +0200 Subject: [PATCH 03/10] Make navPoint ids unique in toc.ncx --- sphinx/builders/epub.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index 2ddaf5c92..a35a72b56 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -188,6 +188,7 @@ 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 @@ -629,8 +630,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 From ce6b8fff700cd9fa2e473e438d51aad705656fd2 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Thu, 6 Jun 2013 21:23:16 +0200 Subject: [PATCH 04/10] Clarify docs for the format and builder tags --- doc/markup/misc.rst | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index d0ace3fa7..86b625dbc 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -179,10 +179,11 @@ 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 and the name of the current builder (``html``, ``latex`` or - ``text``) is always set as a tag [#]_. To make the distinction between + 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_``. + ``builder_``, e.g. the epub builder defines the tags ``html``, ``epub``, + ``format_html`` and ``builder_epub``. .. versionadded:: 0.6 .. versionchanged:: 1.2 @@ -245,6 +246,6 @@ following directive exists: .. rubric:: Footnotes -.. [#] At the moment only the epub builder distinguishes between the builder - format and the builder name. - +.. [#] 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. From bfc03b10adc029cfffa226eefacc0fda04fc4aeb Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Thu, 6 Jun 2013 21:27:53 +0200 Subject: [PATCH 05/10] Change algorithm for EpubBuilder.make_id The new algorithm no longer derives the id from the name (which may contain illegal characters for ids) but uses a cache to associate names to ids. --- sphinx/builders/epub.py | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index a35a72b56..e8e5f0813 100644 --- a/sphinx/builders/epub.py +++ b/sphinx/builders/epub.py @@ -194,9 +194,14 @@ class EpubBuilder(StandaloneHTMLBuilder): 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.""" From 2f5b7b8db1868e2e9aa57ef78f05e5867f8ce00d Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Thu, 6 Jun 2013 21:53:59 +0200 Subject: [PATCH 06/10] Adjust docs about inline URLs for the epub builder --- doc/builders.rst | 5 ----- doc/config.rst | 3 +++ 2 files changed, 3 insertions(+), 5 deletions(-) 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/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 From cc909ab2a9f32bf96a6b00322df324e375b610e3 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Fri, 7 Jun 2013 20:48:14 +0200 Subject: [PATCH 07/10] More docs cleanup; add hint for the epub cover page --- doc/faq.rst | 10 +++++++--- doc/markup/misc.rst | 4 ++-- 2 files changed, 9 insertions(+), 5 deletions(-) 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 86b625dbc..10ba491e9 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -180,10 +180,10 @@ Including content based on tags parentheses (like ``html and (latex or draft)``) are supported. The *format* and the *name* of the current builder (``html``, ``latex`` or - ``text``) are always set as a tag [#]_. To make the distinction between + ``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``. + ``format_html`` and ``builder_epub``. .. versionadded:: 0.6 .. versionchanged:: 1.2 From 812d5cc181111a7d940c58ae75caaf3ebc703910 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Wed, 19 Jun 2013 20:39:13 +0200 Subject: [PATCH 08/10] Remove ids from copied todo directives; they are no longer unique in the todolist --- sphinx/ext/todo.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) 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, }) From 46debd9f176fa3b840e5b874c847593bcff9e252 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Wed, 19 Jun 2013 20:56:48 +0200 Subject: [PATCH 09/10] Rename title of the epub cover guide Calibre needs the title "Cover" to show the cover image. --- sphinx/builders/epub.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/epub.py b/sphinx/builders/epub.py index e8e5f0813..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 = { From 73a1420cc6a54bee8fb9f75d2d83f38b0e66f413 Mon Sep 17 00:00:00 2001 From: Roland Meister Date: Wed, 19 Jun 2013 21:02:27 +0200 Subject: [PATCH 10/10] Add epub_guide entry to doc/conf.py The toc for the spinx documentation actually is in contents.rst. --- doc/conf.py | 1 + 1 file changed, 1 insertion(+) 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)]