Review of epub builder. Add a separate "epub_theme" config value for selecting a different theme.

6 files changed, 81 insertions, 90 deletions

diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
index e41b68b1..60d217df 100644
--- a/doc/_templates/layout.html
+++ b/doc/_templates/layout.html
@@ -1,12 +1,13 @@
 {% extends "!layout.html" %}
 
 {% block extrahead %}
+{{ super() }}
 {%- if not embedded %}
 <style type="text/css">
   table.right { float: right; margin-left: 20px; }
   table.right td { border: 1px solid #ccc; }
 </style>
-{% endif %}
+{%- endif %}
 {% endblock %}
 
 {% block rootrellink %}
diff --git a/doc/builders.rst b/doc/builders.rst
index 3ce8f56a..23556fb1 100644
--- a/doc/builders.rst
+++ b/doc/builders.rst
@@ -67,11 +67,9 @@ The builder's "name" must be given to the **-b** command-line option of
 .. class:: EpubBuilder
 
    This builder produces the same output as the standalone HTML builder, but
-   also generates an *epub* file for ebook readers.
-   This builder is meant to be used together with the
-   :confval:`html_theme` ``'epub'``.
-   See `<http://www.idpf.org/specs.htm>`_ or
-   `<http://en.wikipedia.org/wiki/EPUB>`_ for the definition of epubs.
+   also generates an *epub* file for ebook readers.  See
+   `<http://www.idpf.org/specs.htm>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_
+   for the definition of the epub format.
 
    Its name is ``epub``.
 
diff --git a/doc/conf.py b/doc/conf.py
index 7393643a..de7fc59c 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -34,7 +34,7 @@ release = version
 show_authors = True
 
 # The HTML template theme.
-html_theme = 'epub'
+html_theme = 'sphinxdoc'
 
 # A list of ignored prefixes names for module index sorting.
 modindex_common_prefix = ['sphinx.']
@@ -65,12 +65,13 @@ html_use_opensearch = 'http://sphinx.pocoo.org'
 htmlhelp_basename = 'Sphinxdoc'
 
 # Epub fields
+epub_theme = 'epub'
 epub_basename = 'sphinx'
-epub_author = 'Georg  Brandl'
+epub_author = 'Georg Brandl'
 epub_publisher = 'http://sphinx.pocoo.org/'
 epub_scheme = 'url'
 epub_identifier = epub_publisher
-epub_pre_files = [ ('index', 'Welcome')]
+epub_pre_files = [('index', 'Welcome')]
 epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
     '_static/jquery.js', '_static/searchtools.js',
     '_static/basic.css', 'search.html']
diff --git a/doc/config.rst b/doc/config.rst
index 99b484c8..dbcf799c 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -554,92 +554,89 @@ that use Sphinx' HTMLWriter class.
 Options for epub output
 -----------------------
 
-These options influence the epub output. As this writer derives from the
-HTMLWriter the HTML options also apply where appropriate.
-The actual values for some of the options is not really important,
-they just have to be entered into
+These options influence the epub output.  As this builder derives from the HTML
+builder, the HTML options also apply where appropriate.  The actual values for
+some of the options is not really important, they just have to be entered into
 the `Dublin Core metadata <http://dublincore.org/>`_.
 
 .. confval:: epub_basename
 
-  The basename for the epub file. It defaults to the :confval:`project` name.
+   The basename for the epub file.  It defaults to the :confval:`project` name.
+
+.. confval:: epub_theme
+
+   The HTML theme for the epub output.  Since the default themes are not
+   optimized for small screen space, using the same theme for HTML and epub
+   output is usually not wise.  This defaults to ``'epub'``, a theme designed to
+   save visual space.
 
 .. confval:: epub_title
 
-  The title of the document.
-  It defaults to the :confval:`html_title` option
-  but can be set independently for epub creation.
+   The title of the document.  It defaults to the :confval:`html_title` option
+   but can be set independently for epub creation.
 
 .. confval:: epub_author
 
-  The author of the document.
-  This is put in the Dublin Core metadata.
-  The default value is ``'unknown'``.
+   The author of the document.  This is put in the Dublin Core metadata.  The
+   default value is ``'unknown'``.
 
 .. confval:: epub_language
 
-  The language of the document.
-  This is put in the Dublin Core metadata.
-  The default is the :confval:`language` option or ``'en'`` if unset.
+   The language of the document.  This is put in the Dublin Core metadata.  The
+   default is the :confval:`language` option or ``'en'`` if unset.
 
 .. confval:: epub_publisher
 
-  The publisher of the document.
-  This is put in the Dublin Core metadata.
-  You may use any sensible string, e.g. the project homepage.
-  The default value is ``'unknown'``.
+   The publisher of the document.  This is put in the Dublin Core metadata.  You
+   may use any sensible string, e.g. the project homepage.  The default value is
+   ``'unknown'``.
 
 .. confval:: epub_copyright
 
-  The copyright of the document.
-  It defaults to the :confval:`copyright` option
-  but can be set independently for epub creation.
+   The copyright of the document.  It defaults to the :confval:`copyright`
+   option but can be set independently for epub creation.
 
 .. confval:: epub_identifier
 
-  An identifier for the document.
-  This is put in the Dublin Core metadata.
-  For published documents this is the ISBN number, but you can
-  also use an alternative scheme, e.g. the project homepage.
-  The default value is ``'unknown'``.
+   An identifier for the document.  This is put in the Dublin Core metadata.
+   For published documents this is the ISBN number, but you can also use an
+   alternative scheme, e.g. the project homepage.  The default value is
+   ``'unknown'``.
 
 .. confval:: epub_scheme
 
-  The publication scheme for the :confval:`epub_identifier`.
-  This is put in the Dublin Core metadata.
-  For published books the scheme is ``'ISBN'``.
-  If you use the project homepage, ``'URL'`` seems reasonable.
+   The publication scheme for the :confval:`epub_identifier`.  This is put in
+   the Dublin Core metadata.  For published books the scheme is ``'ISBN'``.  If
+   you use the project homepage, ``'URL'`` seems reasonable.  The default value
+   is ``'unknown'``.
 
 .. confval:: epub_uid
 
-  A unique identifier for the document.
-  This is put in the Dublin Core metadata.
-  You may use a random string.
-  The default value is ``'unknown'``.
+   A unique identifier for the document.  This is put in the Dublin Core
+   metadata.  You may use a random string.  The default value is ``'unknown'``.
 
 .. confval:: epub_pre_files
 
-  Additional files that should be inserted before the text generated by
-  Sphinx. It is a list of tuples containing the file name and the title.
-  Example::
+   Additional files that should be inserted before the text generated by
+   Sphinx. It is a list of tuples containing the file name and the title.
+   Example::
 
       epub_pre_files = [
-         ('index.html', 'Welcome'),
+          ('index.html', 'Welcome'),
       ]
 
-  The default value is ``[]``.
+   The default value is ``[]``.
 
 .. confval:: epub_post_files
 
-  Additional files that should be inserted after the text generated by
-  Sphinx. It is a list of tuples containing the file name and the title.
-  The default value is ``[]``.
+   Additional files that should be inserted after the text generated by Sphinx.
+   It is a list of tuples containing the file name and the title.  The default
+   value is ``[]``.
 
 .. confval:: epub_exclude_files
 
-  A list of files that are generated/copied in the build directory
-  but should not be included in the epub file.
-  The default value is ``[]``.
+   A list of files that are generated/copied in the build directory but should
+   not be included in the epub file.  The default value is ``[]``.
 
 
 .. _latex-options:
diff --git a/doc/faq.rst b/doc/faq.rst
index 46a714dd..20b9b62c 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -54,46 +54,40 @@ github pages
    Sphinx HTML output.
 
 
+.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
+.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
+
+
 Epub
 ----
 
-The EpubBuilder 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 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:
 
-* 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 rendering can take up to one minute.
+* 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
+  rendering can take up to one minute.
 
-* Try to minimize the markup. This also pays in rendering time.
+* Try to minimize the markup.  This also pays in rendering time.
 
-* For some readers you can use embedded or external fonts
-  using the CSS ``@font-face`` directive.
-  This is *extremely* useful for code listings which are often cut
-  at the right margin. The default Courier font (or variant) is quite
-  wide and you can only display up to 60 characters on a line.
-  If you replace it with a narrower font, you can get more characters
-  on a line. You may even use
-  `fontforge <http://fontforge.sourceforge.net/>`_
-  and create narrow variants
-  of some free font. In my case I get up to 70 characters on a line.
+* For some readers you can use embedded or external fonts using the CSS
+  ``@font-face`` directive.  This is *extremely* useful for code listings which
+  are often cut at the right margin.  The default Courier font (or variant) is
+  quite wide and you can only display up to 60 characters on a line.  If you
+  replace it with a narrower font, you can get more characters on a line.  You
+  may even use `FontForge <http://fontforge.sourceforge.net/>`_ and create
+  narrow variants of some free font.  In my case I get up to 70 characters on a
+  line.
 
   You may have to experiment a little until you get reasonable results.
 
-* Test the created epubs. You can use several alternatives.
-  The ones I am aware of are
-  Epubcheck
-  (`http://code.google.com/p/epubcheck/
-  <http://code.google.com/p/epubcheck/>`_),
-  Calibre 
-  (`http://calibre-ebook.com/ <http://calibre-ebook.com/>`_),
-  FBreader (`http://www.fbreader.org/ <http://www.fbreader.org/>`_,
-  although it does not render the CSS), and
-  Bookworm (`http://bookworm.oreilly.com/ <http://bookworm.oreilly.com/>`_).
-  For bookworm you can download the source from
-  `http://code.google.com/p/threepress/ <http://code.google.com/p/threepress/>`_
-  and run you own local server.
+* Test the created epubs. You can use several alternatives.  The ones I am aware
+  of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS),
+  and Bookworm_.  For bookworm you can download the source from
+  http://code.google.com/p/threepress/ and run your own local server.
 
-
-.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
-.. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
+.. _Epubcheck: http://code.google.com/p/epubcheck/
+.. _Calibre: http://calibre-ebook.com/
+.. _FBreader: http://www.fbreader.org/
+.. _Bookworm: http://bookworm.oreilly.com/
diff --git a/doc/theming.rst b/doc/theming.rst
index 4f7cadd1..c73b4f45 100644
--- a/doc/theming.rst
+++ b/doc/theming.rst
@@ -160,9 +160,9 @@ These themes are:
 * **traditional** -- A theme resembling the old Python documentation.  There are
   currently no options beyond *nosidebar*.
 
-* **epub** -- A theme for the epub formatter. There are currently no
-  options. This theme tries to reduce visual space which is a sparse
-  resource on ebook readers.
+* **epub** -- A theme for the epub builder.  There are currently no options.
+  This theme tries to save visual space which is a sparse resource on ebook
+  readers.
 
 
 Creating themes