merge with 0.6

26 files changed, 392 insertions, 11 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 07cee744..ffd51dc6 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -19,6 +19,7 @@ help:
 	@echo "  dirhtml   to make HTML files called index.html in directories"
 	@echo "  pickle    to make pickle files"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  epub      to make an epub file"
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
@@ -65,6 +66,11 @@ qthelp:
 	@echo "To view the help collection:"
 	@echo "# assistant -collectionFile _build/qthelp/Sphinx.qhc"
 
+epub:
+	mkdir -p _build/epub _build/doctrees
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) _build/epub
+	@echo
+	@echo "Build finished. The epub file is in _build/epub."
 latex:
 	mkdir -p _build/latex _build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
index 080c0935..60d217df 100644
--- a/doc/_templates/layout.html
+++ b/doc/_templates/layout.html
@@ -1,5 +1,15 @@
 {% 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 %}
+{% endblock %}
+
 {% block rootrellink %}
         <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|&nbsp;</li>
         <li><a href="{{ pathto('contents') }}">Documentation</a>&raquo;</li>
diff --git a/doc/builders.rst b/doc/builders.rst
index 9050eec9..e8dccc43 100644
--- a/doc/builders.rst
+++ b/doc/builders.rst
@@ -36,6 +36,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionadded:: 0.6
 
+.. module:: sphinx.builders.htmlhelp
 .. class:: HTMLHelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
@@ -44,6 +45,34 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``htmlhelp``.
 
+.. module:: sphinx.builders.qthelp
+.. class:: QtHelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates Qt help collection support files that allow
+   the Qt collection generator to compile them.
+
+   Its name is ``qthelp``.
+
+.. module:: sphinx.builders.devhelp
+.. class:: DevhelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates `GNOME Devhelp <http://live.gnome.org/devhelp>`__
+   support file that allows the GNOME Devhelp reader to view them.
+
+   Its name is ``devhelp``.
+
+.. module:: sphinx.builders.epub
+.. class:: EpubBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates an *epub* file for ebook readers.  See :ref:`epub-faq` for
+   details about it.  For definition of the epub format, have a look at
+   `<http://www.idpf.org/specs.htm>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_.
+
+   Its name is ``epub``.
+
 .. module:: sphinx.builders.latex
 .. class:: LaTeXBuilder
 
diff --git a/doc/concepts.rst b/doc/concepts.rst
index e6d5fa02..27767211 100644
--- a/doc/concepts.rst
+++ b/doc/concepts.rst
@@ -89,6 +89,15 @@ tables of contents.  The ``toctree`` directive is the central element.
    Numbering then starts at the heading of ``foo``.  Sub-toctrees are
    automatically numbered (don't give the ``numbered`` flag to those).
 
+   If you want only the titles of documents in the tree to show up, not other
+   headings of the same level, you can use the ``titlesonly`` option::
+
+      .. toctree::
+         :titlesonly:
+
+         foo
+         bar
+
    You can use "globbing" in toctree directives, by giving the ``glob`` flag
    option.  All entries are then matched against the list of available
    documents, and matches are inserted into the list alphabetically.  Example::
@@ -139,6 +148,9 @@ tables of contents.  The ``toctree`` directive is the central element.
       Added "numbered" and "hidden" options as well as external links and
       support for "self" references.
 
+   .. versionchanged:: 1.0
+      Added "titlesonly" option.
+
 
 Special names
 -------------
diff --git a/doc/conf.py b/doc/conf.py
index 415b0c8d..ce87c54e 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -62,6 +62,19 @@ html_use_opensearch = 'http://sphinx.pocoo.org'
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Sphinxdoc'
 
+# Epub fields
+epub_theme = 'epub'
+epub_basename = 'sphinx'
+epub_author = 'Georg Brandl'
+epub_publisher = 'http://sphinx.pocoo.org/'
+epub_scheme = 'url'
+epub_identifier = epub_publisher
+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']
+
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
@@ -72,7 +85,7 @@ latex_logo = '_static/sphinx.png'
 
 # Additional stuff for the LaTeX preamble.
 latex_elements = {
-    'fontpkg': '\\usepackage{palatino}'
+    'fontpkg': '\\usepackage{palatino}',
 }
 
 # Put TODOs into the output.
diff --git a/doc/config.rst b/doc/config.rst
index 2e96a749..dbcf799c 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -185,7 +185,6 @@ General configuration
 
    .. versionadded:: 0.5
 
-
 .. confval:: modindex_common_prefix
 
    A list of prefixes that are ignored for sorting the module index (e.g.,
@@ -195,6 +194,15 @@ General configuration
 
    .. versionadded:: 0.6
 
+.. confval:: trim_doctest_flags
+
+   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
+   the ends of lines are removed for all code blocks showing interactive Python
+   sessions (i.e. doctests).  Default is true.  See the extension
+   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
+
+   .. versionadded:: 1.0
+
 
 Project information
 -------------------
@@ -245,6 +253,7 @@ Project information
    * ``ru`` -- Russian
    * ``sl`` -- Slovenian
    * ``uk_UA`` -- Ukrainian
+   * ``zh_CN`` -- Simplified Chinese
    * ``zh_TW`` -- Traditional Chinese
 
 .. confval:: today
@@ -514,6 +523,12 @@ that use Sphinx' HTMLWriter class.
    to translate document trees to HTML.  Default is ``None`` (use the builtin
    translator).
 
+.. confval:: html_show_copyright
+
+   If true, "(C) Copyright ..." is shown in the HTML footer. Default is ``True``.
+
+   .. versionadded:: 1.0
+
 .. confval:: html_show_sphinx
 
    If true, "Created using Sphinx" is shown in the HTML footer.  Default is
@@ -521,11 +536,109 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 0.4
 
+.. confval:: html_output_encoding
+
+   Encoding of HTML output files. Default is ``'utf-8'``.  Note that this
+   encoding name must both be a valid Python encoding name and a valid HTML
+   ``charset`` value.
+
+   .. versionadded:: 1.0
+
 .. confval:: htmlhelp_basename
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.
 
 
+.. _epub-options:
+
+Options for epub output
+-----------------------
+
+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.
+
+.. 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.
+
+.. confval:: epub_author
+
+   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.
+
+.. 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'``.
+
+.. confval:: epub_copyright
+
+   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'``.
+
+.. 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 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'``.
+
+.. 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::
+
+      epub_pre_files = [
+          ('index.html', 'Welcome'),
+      ]
+
+   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 ``[]``.
+
+.. 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 ``[]``.
+
+
 .. _latex-options:
 
 Options for LaTeX output
@@ -653,6 +766,14 @@ These options influence LaTeX output.
      ``'shorthandoff'``
      ``'printmodindex'``
 
+.. confval:: latex_docclass
+
+   A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document
+   classes that will be used as the base for the two Sphinx classes.  Default
+   is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``.
+
+   .. versionadded:: 1.0
+
 .. confval:: latex_additional_files
 
    A list of file names, relative to the configuration directory, to copy to the
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 6864d6ba..0a3dae8f 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -205,6 +205,14 @@ the following public API:
 
    .. versionadded:: 0.5
 
+.. method:: Sphinx.add_stylesheet(filename)
+
+   Add *filename* to the list of CSS files that the default HTML template will
+   include.  Like for :meth:`add_javascript`, the filename must be relative to
+   the HTML static path.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_lexer(alias, lexer)
 
    Use *lexer*, which must be an instance of a Pygments lexer class, to
diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst
index 9d75cb0c..5a206dd5 100644
--- a/doc/ext/autosummary.rst
+++ b/doc/ext/autosummary.rst
@@ -130,7 +130,10 @@ also use this new config value:
 
 .. confval:: autosummary_generate
 
-   A list of documents for which stub pages should be generated.
+   Boolean indicating whether to scan all found documents for autosummary
+   directives, and to generate stub pages for each.
+
+   Can also be a list of documents for which stub pages should be generated.
 
    The new files will be placed in the directories specified in the
    ``:toctree:`` options of the directives.
diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst
index 0c64f17a..03d35e02 100644
--- a/doc/ext/doctest.rst
+++ b/doc/ext/doctest.rst
@@ -197,9 +197,9 @@ There are also these config values for customizing the doctest extension:
 
       Some more documentation text.
 
-   (Note that no special ``::`` is needed to introduce the block; docutils
-   recognizes it from the leading ``>>>``.  Also, no additional indentation is
-   necessary, though it doesn't hurt.)
+   (Note that no special ``::`` is used to introduce a doctest block; docutils
+   recognizes them from the leading ``>>>``.  Also, no additional indentation is
+   used, though it doesn't hurt.)
 
    If this value is left at its default value, the above snippet is interpreted
    by the doctest builder exactly like the following::
@@ -220,4 +220,5 @@ There are also these config values for customizing the doctest extension:
    Note though that you can't have blank lines in reST doctest blocks.  They
    will be interpreted as one block ending and another one starting.  Also,
    removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
-   :dir:`doctest` blocks.
+   :dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to
+   achieve the latter in all code blocks with Python console content.
diff --git a/doc/ext/extlinks.rst b/doc/ext/extlinks.rst
new file mode 100644
index 00000000..d4478c5b
--- /dev/null
+++ b/doc/ext/extlinks.rst
@@ -0,0 +1,54 @@
+:mod:`sphinx.ext.extlinks` -- Markup to shorten external links
+==============================================================
+
+.. module:: sphinx.ext.extlinks
+   :synopsis: Allow inserting external links with common base URLs easily.
+.. moduleauthor:: Georg Brandl
+
+.. versionadded:: 1.0
+
+
+This extension is meant to help with the common pattern of having many external
+links that point to URLs on one and the same site, e.g. links to bug trackers,
+version control web interfaces, or simply subpages in other websites.  It does
+so by providing aliases to base URLs, so that you only need to give the subpage
+name when creating a link.
+
+Let's assume that you want to include many links to issues at the Sphinx
+tracker, at :samp:`http://bitbucket.org/birkenfeld/sphinx/issue/{num}`.  Typing
+this URL again and again is tedious, so you can use :mod:`~sphinx.ext.extlinks`
+to avoid repeating yourself.
+
+The extension adds one new config value:
+
+.. confval:: extlinks
+
+   This config value must be a dictionary of external sites, mapping unique
+   short alias names to a base URL and a *prefix*.  For example, to create an
+   alias for the above mentioned issues, you would add ::
+
+      extlinks = {'issue': ('http://bitbucket.org/birkenfeld/sphinx/issue/%s',
+                            'issue ')}
+
+   Now, you can use the alias name as a new role, e.g. ``:issue:`123```.  This
+   then inserts a link to http://bitbucket.org/birkenfeld/sphinx/issue/123.
+   As you can see, the target given in the role is substituted in the base URL
+   in the place of ``%s``.
+
+   The link *caption* depends on the second item in the tuple, the *prefix*:
+
+   - If the prefix is ``None``, the link caption is the full URL.
+   - If the prefix is the empty string, the link caption is the partial URL
+     given in the role content (``123`` in this case.)
+   - If the prefix is a non-empty string, the link caption is the partial URL,
+     prepended by the prefix -- in the above example, the link caption would be
+     ``issue 123``.
+
+   You can also use the usual "explicit title" syntax supported by other roles
+   that generate links, i.e. ``:issue:`this issue <123>```.  In this case, the
+   *prefix* is not relevant.
+
+.. note::
+
+   Since links are generated from the role in the reading stage, they appear as
+   ordinary links to e.g. the ``linkcheck`` builder.
diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst
index d007bf25..77eae7d8 100644
--- a/doc/ext/graphviz.rst
+++ b/doc/ext/graphviz.rst
@@ -25,8 +25,9 @@ It adds these directives:
             "bar" -> "baz";
          }
 
-   In HTML output, the code will be rendered to a PNG image.  In LaTeX output,
-   the code will be rendered to an embeddable PDF file.
+   In HTML output, the code will be rendered to a PNG or SVG image (see
+   :confval:`graphviz_output_format`).  In LaTeX output, the code will be
+   rendered to an embeddable PDF file.
 
 
 .. directive:: graph
@@ -55,6 +56,12 @@ It adds these directives:
          "bar" -> "baz" -> "quux";
 
 
+.. versionadded:: 1.0
+   All three directives support an ``alt`` option that determines the image's
+   alternate text for HTML output.  If not given, the alternate text defaults to
+   the graphviz code.
+
+
 There are also these new config values:
 
 .. confval:: graphviz_dot
@@ -75,3 +82,11 @@ There are also these new config values:
    Additional command-line arguments to give to dot, as a list.  The default is
    an empty list.  This is the right place to set global graph, node or edge
    attributes via dot's ``-G``, ``-N`` and ``-E`` options.
+
+.. confval:: graphviz_output_format
+
+   The output format for Graphviz when building HTML files.  This must be either
+   ``'png'`` or ``'svg'``; the default is ``'png'``.
+
+   .. versionadded:: 1.0
+      Previously, output always was PNG.
diff --git a/doc/extensions.rst b/doc/extensions.rst
index 0716e485..29c40ccd 100644
--- a/doc/extensions.rst
+++ b/doc/extensions.rst
@@ -51,6 +51,7 @@ These extensions are built in and can be activated by respective entries in the
    ext/ifconfig
    ext/coverage
    ext/todo
+   ext/extlinks
 
 
 Third-party extensions
diff --git a/doc/faq.rst b/doc/faq.rst
index 34502dc4..401e1c75 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -56,3 +56,40 @@ github pages
 
 .. _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-faq:
+
+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:
+
+* 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.
+
+* 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_, 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.
+
+.. _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/markup/code.rst b/doc/markup/code.rst
index 93cd127b..8c223297 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -143,11 +143,17 @@ Includes
    string option, only lines that precede the first lines containing that string
    are included.
 
+   You can prepend and/or append a line to the included code, using the
+   ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
+   highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
+
    .. versionadded:: 0.4.3
       The ``encoding`` option.
    .. versionadded:: 0.6
       The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options,
       as well as support for absolute filenames.
+   .. versionadded:: 1.0
+      The ``prepend`` and ``append`` options.
 
 
 .. rubric:: Footnotes
diff --git a/doc/sphinx-build.1 b/doc/sphinx-build.1
index 498771c9..a3df16d0 100644
--- a/doc/sphinx-build.1
+++ b/doc/sphinx-build.1
@@ -31,6 +31,9 @@ Generates files for CHM generation.
 \fBqthelp\fR
 Generates files for Qt help collection generation.
 .TP
+\fBdevhelp\fR
+Generates files for GNOME Devhelp help viewer.
+.TP
 \fBlatex\fR
 Generates a LaTeX version of the documentation.
 .TP
diff --git a/doc/themes/agogo.png b/doc/themes/agogo.png
new file mode 100644
index 00000000..7afc4a13
--- /dev/null
+++ b/doc/themes/agogo.png
diff --git a/doc/themes/default.png b/doc/themes/default.png
new file mode 100644
index 00000000..be821b67
--- /dev/null
+++ b/doc/themes/default.png
diff --git a/doc/themes/fullsize/agogo.png b/doc/themes/fullsize/agogo.png
new file mode 100644
index 00000000..93fadfcb
--- /dev/null
+++ b/doc/themes/fullsize/agogo.png
diff --git a/doc/themes/fullsize/default.png b/doc/themes/fullsize/default.png
new file mode 100644
index 00000000..b6af8bc3
--- /dev/null
+++ b/doc/themes/fullsize/default.png
diff --git a/doc/themes/fullsize/scrolls.png b/doc/themes/fullsize/scrolls.png
new file mode 100644
index 00000000..7d46f7ed
--- /dev/null
+++ b/doc/themes/fullsize/scrolls.png
diff --git a/doc/themes/fullsize/sphinxdoc.png b/doc/themes/fullsize/sphinxdoc.png
new file mode 100644
index 00000000..722fb900
--- /dev/null
+++ b/doc/themes/fullsize/sphinxdoc.png
diff --git a/doc/themes/fullsize/traditional.png b/doc/themes/fullsize/traditional.png
new file mode 100644
index 00000000..103fd3ca
--- /dev/null
+++ b/doc/themes/fullsize/traditional.png
diff --git a/doc/themes/scrolls.png b/doc/themes/scrolls.png
new file mode 100644
index 00000000..e4cb9aa9
--- /dev/null
+++ b/doc/themes/scrolls.png
diff --git a/doc/themes/sphinxdoc.png b/doc/themes/sphinxdoc.png
new file mode 100644
index 00000000..2d2723a8
--- /dev/null
+++ b/doc/themes/sphinxdoc.png
diff --git a/doc/themes/traditional.png b/doc/themes/traditional.png
new file mode 100644
index 00000000..535213fe
--- /dev/null
+++ b/doc/themes/traditional.png
diff --git a/doc/theming.rst b/doc/theming.rst
index d1d3b27a..c2566ac3 100644
--- a/doc/theming.rst
+++ b/doc/theming.rst
@@ -52,7 +52,33 @@ file :file:`blue.zip`, you can put it right in the directory containing
 Builtin themes
 --------------
 
-Sphinx comes with a selection of themes to choose from:
+.. cssclass:: right
+
++-----------------------------------------+
+| **Theme overview**                      |
++--------------------+--------------------+
+| |default|          | |sphinxdoc|        |
+|                    |                    |
+| *default*          | *sphinxdoc*        |
++--------------------+--------------------+
+| |scrolls|          | |agogo|            |
+|                    |                    |
+| *scrolls*          | *agogo*            |
++--------------------+--------------------+
+| |traditional|      |                    |
+|                    |                    |
+| *traditional*      |                    |
++--------------------+--------------------+
+
+.. |default|     image:: themes/default.png
+.. |sphinxdoc|   image:: themes/sphinxdoc.png
+.. |scrolls|     image:: themes/scrolls.png
+.. |agogo|       image:: themes/agogo.png
+.. |traditional| image:: themes/traditional.png
+
+Sphinx comes with a selection of themes to choose from.
+
+These themes are:
 
 * **basic** -- This is a basically unstyled layout used as the base for the
   *default* and *sphinxdoc* themes, and usable as the base for custom themes as
@@ -62,7 +88,8 @@ Sphinx comes with a selection of themes to choose from:
   - **nosidebar** (true or false): Don't include the sidebar.  Defaults to
     false.
 
-* **default** -- This is the default theme.  It can be customized via these
+* **default** -- This is the default theme, which looks like `the Python
+  documentation <http://docs.python.org/>`_.  It can be customized via these
   options:
 
   - **rightsidebar** (true or false): Put the sidebar on the right side.
@@ -86,6 +113,7 @@ Sphinx comes with a selection of themes to choose from:
   - **bgcolor** (CSS color): Body background color.
   - **textcolor** (CSS color): Body text color.
   - **linkcolor** (CSS color): Body link color.
+  - **visitedlinkcolor** (CSS color): Body color for visited links.
   - **headbgcolor** (CSS color): Background color for headings.
   - **headtextcolor** (CSS color): Text color for headings.
   - **headlinkcolor** (CSS color): Link color for headings.
@@ -99,9 +127,43 @@ Sphinx comes with a selection of themes to choose from:
 * **sphinxdoc** -- The theme used for this documentation.  It features a sidebar
   on the right side.  There are currently no options beyond *nosidebar*.
 
+* **scrolls** -- A more lightweight theme, based on `the Jinja documentation
+  <http://jinja.pocoo.org/2/documentation/>`_.  The following color options are
+  available:
+
+  - **headerbordercolor**
+  - **subheadlinecolor**
+  - **linkcolor**
+  - **visitedlinkcolor**
+  - **admonitioncolor**
+
+* **agogo** -- A theme created by Andi Albrecht.  The following options are
+  supported:
+
+  - **bodyfont** (CSS font family): Font for normal text.
+  - **headerfont** (CSS font family): Font for headings.
+  - **pagewidth** (CSS length): Width of the page content, default 70em.
+  - **documentwidth** (CSS length): Width of the document (without sidebar),
+    default 50em.
+  - **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
+  - **bgcolor** (CSS color): Background color.
+  - **headerbg** (CSS value for "background"): background for the header area,
+    default a grayish gradient.
+  - **footerbg** (CSS value for "background"): background for the footer area,
+    default a light gray gradient.
+  - **linkcolor** (CSS color): Body link color.
+  - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
+    headings.
+  - **headerlinkcolor** (CSS color): Color for the backreference link in
+    headings.
+
 * **traditional** -- A theme resembling the old Python documentation.  There are
   currently no options beyond *nosidebar*.
 
+* **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
 ---------------