merge with 0.50.6b1

33 files changed, 1296 insertions, 283 deletions

diff --git a/doc/Makefile b/doc/Makefile
index cb5fc645..07cee744 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -11,12 +11,13 @@ PAPEROPT_letter  = -D latex_paper_size=letter
 ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
                 $(SPHINXOPTS) .
 
-.PHONY: help clean html web htmlhelp latex changes linkcheck
+.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
-	@echo "  web       to make files usable by Sphinx.web"
+	@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 "  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"
@@ -31,13 +32,21 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in _build/html."
 
+dirhtml:
+	mkdir -p _build/dirhtml _build/doctrees
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in _build/dirhtml."
+
+text:
+	mkdir -p _build/text _build/doctrees
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
+	@echo
+	@echo "Build finished."
+
 pickle:
 	mkdir -p _build/pickle _build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
-	@echo
-	@echo "Build finished; now you can run"
-	@echo "  python -m sphinx.web _build/pickle"
-	@echo "to start the server."
 
 htmlhelp:
 	mkdir -p _build/htmlhelp _build/doctrees
@@ -46,6 +55,16 @@ htmlhelp:
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in _build/htmlhelp."
 
+qthelp:
+	mkdir -p _build/qthelp _build/doctrees
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) _build/qthelp
+	@echo
+	@echo "Build finished; now you can run qcollectiongenerator with the" \
+	      ".qhcp project file in build/qthelp."
+	@echo "# qcollectiongenerator _build/qthelp/Sphinx.qhcp"
+	@echo "To view the help collection:"
+	@echo "# assistant -collectionFile _build/qthelp/Sphinx.qhc"
+
 latex:
 	mkdir -p _build/latex _build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
diff --git a/doc/_templates/index.html b/doc/_templates/index.html
index 43d07e82..1c399f92 100644
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -81,5 +81,5 @@
   </p>
   <p>The code can be found in a Mercurial repository, at
     <tt>http://bitbucket.org/birkenfeld/sphinx/</tt>.</p>
-  
+
 {% endblock %}
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
index 2cc15450..080c0935 100644
--- a/doc/_templates/layout.html
+++ b/doc/_templates/layout.html
@@ -1,17 +1,12 @@
 {% extends "!layout.html" %}
 
 {% block rootrellink %}
-        <li><a href="{{ pathto('index') }}">Sphinx home </a> |&nbsp;</li>
-        <li><a href="{{ pathto('contents') }}">Documentation </a> &raquo;</li>
+        <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|&nbsp;</li>
+        <li><a href="{{ pathto('contents') }}">Documentation</a>&raquo;</li>
 {% endblock %}
 
-{% block relbar1 %}
+{% block header %}
 <div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
 <img src="{{ pathto("_static/sphinx.png", 1) }}" alt="Sphinx logo" />
 </div>
-{{ super() }}
 {% endblock %}
-
-{# put the sidebar before the body #}
-{% block sidebar1 %}{{ sidebar() }}{% endblock %}
-{% block sidebar2 %}{% endblock %}
diff --git a/doc/builders.rst b/doc/builders.rst
index 508ab3c5..bee0094c 100644
--- a/doc/builders.rst
+++ b/doc/builders.rst
@@ -3,7 +3,7 @@
 Available builders
 ==================
 
-.. module:: sphinx.builder
+.. module:: sphinx.builders
    :synopsis: Available built-in builder classes.
 
 These are the built-in Sphinx builders.  More builders can be added by
@@ -13,6 +13,7 @@ The builder's "name" must be given to the **-b** command-line option of
 :program:`sphinx-build` to select a builder.
 
 
+.. module:: sphinx.builders.html
 .. class:: StandaloneHTMLBuilder
 
    This is the standard HTML builder.  Its output is a directory with HTML
@@ -22,14 +23,28 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``html``.
 
+.. class:: DirectoryHTMLBuilder
+
+   This is a subclass of the standard HTML builder.  Its output is a directory
+   with HTML files, where each file is called ``index.html`` and placed in a
+   subdirectory named like its page name.  For example, the document
+   ``markup/rest.rst`` will not result in an output file ``markup/rest.html``,
+   but ``markup/rest/index.html``.  When generating links between pages, the
+   ``index.html`` is omitted, so that the URL would look like ``markup/rest/``.
+
+   Its name is ``dirhtml``.
+
+   .. versionadded:: 0.6
+
 .. class:: HTMLHelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
    also generates HTML Help support files that allow the Microsoft HTML Help
    Workshop to compile them into a CHM file.
 
-   Its name is ``htmlhelp``. 
+   Its name is ``htmlhelp``.
 
+.. module:: sphinx.builders.latex
 .. class:: LaTeXBuilder
 
    This builder produces a bunch of LaTeX files in the output directory.  You
@@ -50,6 +65,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``latex``.
 
+.. module:: sphinx.builders.text
 .. class:: TextBuilder
 
    This builder produces a text file for each reST file -- this is almost the
@@ -60,6 +76,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionadded:: 0.4
 
+.. currentmodule:: sphinx.builders.html
 .. class:: SerializingHTMLBuilder
 
    This builder uses a module that implements the Python serialization API
@@ -81,7 +98,7 @@ The builder's "name" must be given to the **-b** command-line option of
    .. _PHP serialization: http://pypi.python.org/pypi/phpserialize
 
    .. attribute:: implementation
-    
+
       A module that implements `dump()`, `load()`, `dumps()` and `loads()`
       functions that conform to the functions with the same names from the
       pickle module.  Known modules implementing this interface are
@@ -135,6 +152,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionadded:: 0.5
 
+.. module:: sphinx.builders.changes
 .. class:: ChangesBuilder
 
    This builder produces an HTML overview of all :dir:`versionadded`,
@@ -144,6 +162,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``changes``.
 
+.. module:: sphinx.builders.linkcheck
 .. class:: CheckExternalLinksBuilder
 
    This builder scans all documents for external links, tries to open them with
diff --git a/doc/concepts.rst b/doc/concepts.rst
index ca7aaf7c..e6d5fa02 100644
--- a/doc/concepts.rst
+++ b/doc/concepts.rst
@@ -16,6 +16,9 @@ directory`, the extension is stripped, and path separators are converted to
 slashes.  All values, parameters and suchlike referring to "documents" expect
 such a document name.
 
+Examples for document names are ``index``, ``library/zipfile``, or
+``reference/datamodel/types``.  Note that there is no leading slash.
+
 
 The TOC tree
 ------------
@@ -55,22 +58,37 @@ tables of contents.  The ``toctree`` directive is the central element.
      ``strings`` and so forth, and it knows that they are children of the shown
      document, the library index.  From this information it generates "next
      chapter", "previous chapter" and "parent chapter" links.
-     
+
    Document titles in the :dir:`toctree` will be automatically read from the
-   title of the referenced document. If that isn't what you want, you can give
-   the specify an explicit title and target using a similar syntax to reST
+   title of the referenced document. If that isn't what you want, you can
+   specify an explicit title and target using a similar syntax to reST
    hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
    looks like::
-   
+
        .. toctree::
-          
+
           intro
           All about strings <strings>
           datatypes
-          
+
    The second line above will link to the ``strings`` document, but will use the
    title "All about strings" instead of the title of the ``strings`` document.
 
+   You can also add external links, by giving an HTTP URL instead of a document
+   name.
+
+   If you want to have section numbers even in HTML output, give the toctree a
+   ``numbered`` flag option.  For example::
+
+      .. toctree::
+         :numbered:
+
+         foo
+         bar
+
+   Numbering then starts at the heading of ``foo``.  Sub-toctrees are
+   automatically numbered (don't give the ``numbered`` flag to those).
+
    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::
@@ -85,7 +103,24 @@ tables of contents.  The ``toctree`` directive is the central element.
    This includes first all documents whose names start with ``intro``, then all
    documents in the ``recipe`` folder, then all remaining documents (except the
    one containing the directive, of course.) [#]_
-          
+
+   The special entry name ``self`` stands for the document containing the
+   toctree directive.  This is useful if you want to generate a "sitemap" from
+   the toctree.
+
+   You can also give a "hidden" option to the directive, like this::
+
+      .. toctree::
+         :hidden:
+
+         doc_1
+         doc_2
+
+   This will still notify Sphinx of the document hierarchy, but not insert links
+   into the document at the location of the directive -- this makes sense if you
+   intend to insert these links yourself, in a different style, or in the HTML
+   sidebar.
+
    In the end, all documents in the :term:`source directory` (or subdirectories)
    must occur in some ``toctree`` directive; Sphinx will emit a warning if it
    finds a file that is not included, because that means that this file will not
@@ -100,6 +135,10 @@ tables of contents.  The ``toctree`` directive is the central element.
    .. versionchanged:: 0.3
       Added "globbing" option.
 
+   .. versionchanged:: 0.6
+      Added "numbered" and "hidden" options as well as external links and
+      support for "self" references.
+
 
 Special names
 -------------
diff --git a/doc/conf.py b/doc/conf.py
index 89247821..e1a48aa2 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -1,26 +1,9 @@
 # -*- coding: utf-8 -*-
 #
-# Sphinx documentation build configuration file, created by
-# sphinx-quickstart.py on Sat Mar  8 21:47:50 2008.
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# The contents of this file are pickled, so don't put values in the namespace
-# that aren't pickleable (module imports are okay, they're removed automatically).
-#
-# All configuration values have a default value; values that are commented out
-# serve to show the default value.
+# Sphinx documentation build configuration file
 
 import sys, os, re
 
-# If your extensions are in another directory, add it here.
-#sys.path.append(os.path.dirname(__file__))
-
-# General configuration
-# ---------------------
-
-language = 'en'
-
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.addons.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo']
@@ -36,46 +19,22 @@ master_doc = 'contents'
 
 # General substitutions.
 project = 'Sphinx'
-copyright = '2008, Georg Brandl'
+copyright = '2007-2009, Georg Brandl'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
-#
-# The short X.Y version.
 import sphinx
 version = sphinx.__released__
-# The full version, including alpha/beta/rc tags.
 release = version
 
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
+# Show author directives in the output.
 show_authors = True
 
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'friendly'
-
+# The HTML template theme.
+html_theme = 'sphinxdoc'
 
-# Options for HTML output
-# -----------------------
-
-# The style sheet to use for HTML and HTML Help pages. A file of that name
-# must exist either in Sphinx' static/ path, or in one of the custom paths
-# given in html_static_path.
-html_style = 'sphinxdoc.css'
+# A list of ignored prefixes names for module index sorting.
+modindex_common_prefix = ['sphinx.']
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -86,10 +45,6 @@ html_static_path = ['_static']
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
 # Content template for the index page.
 html_index = 'index.html'
 
@@ -100,50 +55,30 @@ html_sidebars = {'index': 'indexsidebar.html'}
 # templates.
 html_additional_pages = {'index': 'index.html'}
 
-# If true, the reST sources are included in the HTML build as _sources/<name>.
-#html_copy_source = True
-
+# Generate an OpenSearch description with that URL as the base.
 html_use_opensearch = 'http://sphinx.pocoo.org'
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Sphinxdoc'
 
-
-# Options for LaTeX output
-# ------------------------
-
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
 # Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, document class [howto/manual]).
+# (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual', 1)]
 
+# Add our logo to the LaTeX file.
 latex_logo = '_static/sphinx.png'
 
-#latex_use_parts = True
-
 # Additional stuff for the LaTeX preamble.
 latex_elements = {
     'fontpkg': '\\usepackage{palatino}'
 }
 
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-
-# Extension options
-# -----------------
-
+# Put TODOs into the output.
 todo_include_todos = True
 
 
-# Extension interface
-# -------------------
+# -- Extension interface -------------------------------------------------------
 
 from sphinx import addnodes
 
@@ -190,7 +125,9 @@ def parse_event(env, sig, signode):
 def setup(app):
     from sphinx.ext.autodoc import cut_lines
     app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))
-    app.add_description_unit('directive', 'dir', 'pair: %s; directive', parse_directive)
+    app.add_description_unit('directive', 'dir', 'pair: %s; directive',
+                             parse_directive)
     app.add_description_unit('role', 'role', 'pair: %s; role', parse_role)
-    app.add_description_unit('confval', 'confval', 'pair: %s; configuration value')
+    app.add_description_unit('confval', 'confval',
+                             'pair: %s; configuration value')
     app.add_description_unit('event', 'event', 'pair: %s; event', parse_event)
diff --git a/doc/config.rst b/doc/config.rst
index e6af9aae..54303bbb 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -22,8 +22,8 @@ Important points to note:
 
 * The term "fully-qualified name" refers to a string that names an importable
   Python object inside a module; for example, the FQN
-  ``"sphinx.builder.Builder"`` means the ``Builder`` class in the
-  ``sphinx.builder`` module.
+  ``"sphinx.builders.Builder"`` means the ``Builder`` class in the
+  ``sphinx.builders`` module.
 
 * Remember that document names use ``/`` as the path separator and don't contain
   the file name extension.
@@ -38,6 +38,11 @@ Important points to note:
   delete them from the namespace with ``del`` if appropriate.  Modules are
   removed automatically, so you don't need to ``del`` your imports after use.
 
+* There is a special object named ``tags`` available in the config file.
+  It can be used to query and change the tags (see :ref:`tags`).  Use
+  ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')``
+  to change.
+
 
 General configuration
 ---------------------
@@ -76,7 +81,7 @@ General configuration
 
    .. versionadded:: 0.5
       Previously, Sphinx accepted only UTF-8 encoded sources.
-   
+
 .. confval:: master_doc
 
    The document name of the "master" document, that is, the document that
@@ -131,18 +136,35 @@ General configuration
 .. confval:: templates_path
 
    A list of paths that contain extra templates (or templates that overwrite
-   builtin templates).  Relative paths are taken as relative to the
-   configuration directory.
+   builtin/theme-specific templates).  Relative paths are taken as relative to
+   the configuration directory.
 
 .. confval:: template_bridge
 
    A string with the fully-qualified name of a callable (or simply a class) that
    returns an instance of :class:`~sphinx.application.TemplateBridge`.  This
    instance is then used to render HTML documents, and possibly the output of
-   other builders (currently the changes builder).
+   other builders (currently the changes builder).  (Note that the template
+   bridge must be made theme-aware if HTML themes are to be used.)
+
+.. confval:: rst_epilog
+
+   .. index:: pair: global; substitutions
+
+   A string of reStructuredText that will be included at the end of every source
+   file that is read.  This is the right place to add substitutions that should
+   be available in every file.  An example::
+
+      rst_epilog = """
+      .. |psf| replace:: Python Software Foundation
+      """
+
+   .. versionadded:: 0.6
 
 .. confval:: default_role
 
+   .. index:: default; role
+
    The name of a reST role (builtin or Sphinx extension) to use as the default
    role, that is, for text marked up ```like this```.  This can be set to
    ``'obj'`` to make ```filter``` a cross-reference to the function "filter".
@@ -164,9 +186,19 @@ General configuration
    .. versionadded:: 0.5
 
 
+.. confval:: modindex_common_prefix
+
+   A list of prefixes that are ignored for sorting the module index (e.g.,
+   if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, not
+   ``F``). This can be handy if you document a project that consists of a single
+   package.  Works only for the HTML builder currently.   Default is ``[]``.
+
+   .. versionadded:: 0.6
+
+
 Project information
 -------------------
-   
+
 .. confval:: project
 
    The documented project's name.
@@ -204,11 +236,14 @@ Project information
    * ``de`` -- German
    * ``en`` -- English
    * ``es`` -- Spanish
+   * ``fi`` -- Finnish
    * ``fr`` -- French
+   * ``it`` -- Italian
    * ``nl`` -- Dutch
    * ``pl`` -- Polish
    * ``pt_BR`` -- Brazilian Portuguese
    * ``sl`` -- Slovenian
+   * ``uk_UA`` -- Ukrainian
    * ``zh_TW`` -- Traditional Chinese
 
 .. confval:: today
@@ -232,7 +267,7 @@ Project information
    :ref:`code-examples` for more details.
 
    .. versionadded:: 0.5
-   
+
 .. confval:: pygments_style
 
    The style name to use for Pygments highlighting of source code.  Default is
@@ -260,6 +295,13 @@ Project information
    A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor`
    directives produce any output in the built files.
 
+.. confval:: trim_footnote_reference_space
+
+   Trim spaces before footnote references that are necessary for the reST parser
+   to recognize the footnote, but do not look too nice in the output.
+
+   .. versionadded:: 0.6
+
 
 .. _html-options:
 
@@ -269,6 +311,37 @@ Options for HTML output
 These options influence HTML as well as HTML Help output, and other builders
 that use Sphinx' HTMLWriter class.
 
+.. confval:: html_theme
+
+   The "theme" that the HTML output should use.  See the :doc:`section about
+   theming <theming>`.  The default is ``'default'``.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_theme_options
+
+   A dictionary of options that influence the look and feel of the selected
+   theme.  These are theme-specific.  For the options understood by the builtin
+   themes, see :ref:`this section <builtin-themes>`.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_theme_path
+
+   A list of paths that contain custom themes, either as subdirectories or as
+   zip files.  Relative paths are taken as relative to the configuration
+   directory.
+
+   .. versionadded:: 0.6
+
+.. confval:: html_style
+
+   The style sheet to use for HTML pages.  A file of that name must exist either
+   in Sphinx' :file:`static/` path, or in one of the custom paths given in
+   :confval:`html_static_path`.  Default is the stylesheet given by the selected
+   theme.  If you only want to add or override a few things compared to the
+   theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet.
+
 .. confval:: html_title
 
    The "title" for HTML documentation generated with Sphinx' own templates.
@@ -285,12 +358,6 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 0.4
 
-.. confval:: html_style
-
-   The style sheet to use for HTML pages.  A file of that name must exist either
-   in Sphinx' :file:`static/` path, or in one of the custom paths given in
-   :confval:`html_static_path`.  Default is ``'default.css'``.
-
 .. confval:: html_logo
 
    If given, this must be the name of an image file that is the logo of the
@@ -314,8 +381,8 @@ that use Sphinx' HTMLWriter class.
 
    A list of paths that contain custom static files (such as style sheets or
    script files).  Relative paths are taken as relative to the configuration
-   directory.  They are copied to the output directory after the builtin static
-   files, so a file named :file:`default.css` will overwrite the builtin
+   directory.  They are copied to the output directory after the theme's static
+   files, so a file named :file:`default.css` will overwrite the theme's
    :file:`default.css`.
 
    .. versionchanged:: 0.4
@@ -332,6 +399,15 @@ that use Sphinx' HTMLWriter class.
    If true, *SmartyPants* will be used to convert quotes and dashes to
    typographically correct entities.  Default: ``True``.
 
+.. confval:: html_add_permalinks
+
+   If true, Sphinx will add "permalinks" for each heading and description
+   environment as paragraph signs that become visible when the mouse hovers over
+   them.  Default: ``True``.
+
+   .. versionadded:: 0.6
+      Previously, this was always activated.
+
 .. confval:: html_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to
@@ -399,6 +475,13 @@ that use Sphinx' HTMLWriter class.
       will only display the titles of matching documents, and no excerpt from
       the matching contents.
 
+.. confval:: html_show_sourcelink
+
+   If true (and :confval:`html_copy_source` is true as well), links to the
+   reST sources will be added to the sidebar.  The default is ``True``.
+
+   .. versionadded:: 0.6
+
 .. confval:: html_use_opensearch
 
    If nonempty, an `OpenSearch <http://opensearch.org>` description file will be
@@ -415,10 +498,18 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 0.4
 
+.. confval:: html_link_suffix
+
+   Suffix for generated links to HTML files.  The default is whatever
+   :confval:`html_file_suffix` is set to; it can be set differently (e.g. to
+   support different web server setups).
+
+   .. versionadded:: 0.6
+
 .. confval:: html_translator_class
 
    A string with the fully-qualified name of a HTML Translator class, that is, a
-   subclass of Sphinx' :class:`~sphinx.htmlwriter.HTMLTranslator`, that is used
+   subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used
    to translate document trees to HTML.  Default is ``None`` (use the builtin
    translator).
 
@@ -502,7 +593,7 @@ These options influence LaTeX output.
    avoid interpretation as escape sequences.
 
    * Keys that you may want to override include:
-     
+
      ``'papersize'``
         Paper size option of the document class (``'a4paper'`` or
         ``'letterpaper'``), default ``'letterpaper'``.
@@ -526,9 +617,9 @@ These options influence LaTeX output.
         Additional preamble content, default empty.
      ``'footer'```
         Additional footer content (before the indices), default empty.
-     
+
    * Keys that don't need be overridden unless in special cases are:
-     
+
      ``'inputenc'``
         "inputenc" package inclusion, default
         ``'\\usepackage[utf8]{inputenc}'``.
@@ -545,9 +636,9 @@ These options influence LaTeX output.
         "printindex" call, the last thing in the file, default
         ``'\\printindex'``.  Override if you want to generate the index
         differently or append some content after the index.
-     
+
    * Keys that are set by other options and therefore should not be overridden are:
-     
+
      ``'docclass'``
      ``'classoptions'``
      ``'title'``
@@ -560,7 +651,20 @@ These options influence LaTeX output.
      ``'makemodindex'``
      ``'shorthandoff'``
      ``'printmodindex'``
-   
+
+.. confval:: latex_additional_files
+
+   A list of file names, relative to the configuration directory, to copy to the
+   build directory when building LaTeX output.  This is useful to copy files
+   that Sphinx doesn't copy automatically, e.g. if they are referenced in custom
+   LaTeX added in ``latex_elements``.  Image files that are referenced in source
+   files (e.g. via ``.. image::``) are copied automatically.
+
+   You have to make sure yourself that the filenames don't collide with those of
+   any automatically copied files.
+
+   .. versionadded:: 0.6
+
 .. confval:: latex_preamble
 
    Additional LaTeX markup for the preamble.
diff --git a/doc/contents.rst b/doc/contents.rst
index 6ddbcbcb..1f3860ea 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -12,9 +12,11 @@ Sphinx documentation contents
    markup/index
    builders
    config
+   theming
    templating
    extensions
-   
+
+   faq
    glossary
    changes
    examples
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index fcc29e38..6864d6ba 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -10,25 +10,39 @@ This function is called at initialization time with one argument, the
 application object representing the Sphinx process.  This application object has
 the following public API:
 
+.. method:: Sphinx.setup_extension(name)
+
+   Load the extension given by the module *name*.  Use this if your extension
+   needs the features provided by another extension.
+
 .. method:: Sphinx.add_builder(builder)
 
    Register a new builder.  *builder* must be a class that inherits from
-   :class:`~sphinx.builder.Builder`.
+   :class:`~sphinx.builders.Builder`.
 
-.. method:: Sphinx.add_config_value(name, default, rebuild_env)
+.. method:: Sphinx.add_config_value(name, default, rebuild)
 
    Register a configuration value.  This is necessary for Sphinx to recognize
    new values and set default values accordingly.  The *name* should be prefixed
    with the extension name, to avoid clashes.  The *default* value can be any
-   Python object.  The boolean value *rebuild_env* must be ``True`` if a change
-   in the setting only takes effect when a document is parsed -- this means that
-   the whole environment must be rebuilt.
+   Python object.  The string value *rebuild* must be one of those values:
+
+   * ``'env'`` if a change in the setting only takes effect when a document is
+     parsed -- this means that the whole environment must be rebuilt.
+   * ``'html'`` if a change in the setting needs a full rebuild of HTML
+     documents.
+   * ``''`` if a change in the setting will not need any special rebuild.
 
    .. versionchanged:: 0.4
       If the *default* value is a callable, it will be called with the config
       object as its argument in order to get the default value.  This can be
       used to implement config values whose default depends on other values.
 
+   .. versionchanged:: 0.6
+      Changed *rebuild* from a simple boolean (equivalent to ``''`` or
+      ``'env'``) to a string.  However, booleans are still accepted and
+      converted internally.
+
 .. method:: Sphinx.add_event(name)
 
    Register an event called *name*.
@@ -45,12 +59,12 @@ the following public API:
    :exc:`docutils.nodes.SkipNode`.  Example::
 
       class math(docutils.nodes.Element)
-   
+
       def visit_math_html(self, node):
           self.body.append(self.starttag(node, 'math'))
       def depart_math_html(self, node):
           self.body.append('</math>')
-   
+
       app.add_node(math, html=(visit_math_html, depart_math_html))
 
    Obviously, translators for which you don't specify visitor methods will choke
@@ -60,13 +74,28 @@ the following public API:
       Added the support for keyword arguments giving visit functions.
 
 .. method:: Sphinx.add_directive(name, func, content, arguments, **options)
+            Sphinx.add_directive(name, directiveclass)
 
    Register a Docutils directive.  *name* must be the prospective directive
-   name, *func* the directive function for details about the signature and
-   return value.  *content*, *arguments* and *options* are set as attributes on
-   the function and determine whether the directive has content, arguments and
-   options, respectively.  For their exact meaning, please consult the Docutils
-   documentation.
+   name.  There are two possible ways to write a directive:
+
+   * In the docutils 0.4 style, *func* is the directive function.  *content*,
+     *arguments* and *options* are set as attributes on the function and
+     determine whether the directive has content, arguments and options,
+     respectively.
+
+   * In the docutils 0.5 style, *directiveclass* is the directive class.  It
+     must already have attributes named *has_content*, *required_arguments*,
+     *optional_arguments*, *final_argument_whitespace* and *option_spec* that
+     correspond to the options for the function way.  See `the Docutils docs
+     <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_ for
+     details.
+
+     The directive class normally must inherit from the class
+     ``docutils.parsers.rst.Directive``.  When writing a directive for usage in
+     a Sphinx extension, you inherit from ``sphinx.util.compat.Directive``
+     instead which does the right thing even on docutils 0.4 (which doesn't
+     support directive classes otherwise).
 
    For example, the (already existing) :dir:`literalinclude` directive would be
    added like this::
@@ -78,7 +107,8 @@ the following public API:
                     language = direcitves.unchanged,
                     encoding = directives.encoding)
 
-   .. XXX once we target docutils 0.5, update this
+   .. versionchanged:: 0.6
+      Docutils 0.5-style directive classes are now supported.
 
 .. method:: Sphinx.add_role(name, role)
 
@@ -86,6 +116,13 @@ the following public API:
    source, *role* the role function (see the `Docutils documentation
    <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ on details).
 
+.. method:: Sphinx.add_generic_role(name, nodeclass)
+
+   Register a Docutils role that does nothing but wrap its contents in the
+   node given by *nodeclass*.
+
+   .. versionadded:: 0.6
+
 .. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None)
 
    This method is a very convenient way to add a new type of information that
@@ -167,7 +204,32 @@ the following public API:
    :confval:`the docs for the config value <html_static_path>`.
 
    .. versionadded:: 0.5
-   
+
+.. method:: Sphinx.add_lexer(alias, lexer)
+
+   Use *lexer*, which must be an instance of a Pygments lexer class, to
+   highlight code blocks with the given language *alias*.
+
+   .. versionadded:: 0.6
+
+.. method:: Sphinx.add_autodocumenter(cls)
+
+   Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc`
+   extension.  It must be a subclass of :class:`sphinx.ext.autodoc.Documenter`.
+   This allows to auto-document new types of objects.  See the source of the
+   autodoc module for examples on how to subclass :class:`Documenter`.
+
+   .. versionadded:: 0.6
+
+.. method:: Sphinx.add_autodoc_attrgetter(type, getter)
+
+   Add *getter*, which must be a function with an interface compatible to the
+   :func:`getattr` builtin, as the autodoc attribute getter for objects that are
+   instances of *type*.  All cases where autodoc needs to get an attribute of a
+   type are then handled by this function instead of :func:`getattr`.
+
+   .. versionadded:: 0.6
+
 .. method:: Sphinx.connect(event, callback)
 
    Register *callback* to be called when *event* is emitted.  For details on
@@ -230,7 +292,7 @@ registered event handlers.
    since the module declarations could have been removed from the file.
 
    .. versionadded:: 0.5
-   
+
 .. event:: source-read (app, docname, source)
 
    Emitted when a source file has been read.  The *source* argument is a list
@@ -242,7 +304,7 @@ registered event handlers.
    ``:math:`...```.
 
    .. versionadded:: 0.5
-   
+
 .. event:: doctree-read (app, doctree)
 
    Emitted when a doctree has been parsed and read by the environment, and is
@@ -264,7 +326,7 @@ registered event handlers.
       future reference and should be a child of the returned reference node.
 
    .. versionadded:: 0.5
-   
+
 .. event:: doctree-resolved (app, doctree, docname)
 
    Emitted when a doctree has been "resolved" by the environment, that is, all
@@ -280,7 +342,7 @@ registered event handlers.
    completed, that is, the environment and all doctrees are now up-to-date.
 
    .. versionadded:: 0.5
-   
+
 .. event:: page-context (app, pagename, templatename, context, doctree)
 
    Emitted when the HTML builder has created a context dictionary to render a
@@ -311,7 +373,7 @@ registered event handlers.
    cleanup actions depending on the exception status.
 
    .. versionadded:: 0.5
-   
+
 
 .. _template-bridge:
 
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index 3e5ce3e1..ff8d189d 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -68,7 +68,7 @@ directive.
             Boil the noodle *time* minutes.
 
    **Options and advanced usage**
-         
+
    * If you want to automatically document members, there's a ``members``
      option::
 
@@ -115,9 +115,11 @@ directive.
 
      .. versionadded:: 0.4
 
-   * The :dir:`autoclass` and :dir:`autoexception` directives also support a
-     flag option called ``show-inheritance``.  When given, a list of base
-     classes will be inserted just below the class signature.
+   * The :dir:`automodule`, :dir:`autoclass` and :dir:`autoexception` directives
+     also support a flag option called ``show-inheritance``.  When given, a list
+     of base classes will be inserted just below the class signature (when used
+     with :dir:`automodule`, this will be inserted for every class that is
+     documented in the module).
 
      .. versionadded:: 0.4
 
@@ -133,6 +135,18 @@ directive.
 
      .. versionadded:: 0.5
 
+   * :dir:`automodule` and :dir:`autoclass` also has an ``member-order`` option
+     that can be used to override the global value of
+     :confval:`autodoc_member_order` for one directive.
+
+     .. versionadded:: 0.6
+
+  * The directives supporting member documentation also have a
+    ``exclude-members`` option that can be used to exclude single member names
+    from documentation, if all members are to be documented.
+
+    .. versionadded:: 0.6
+
    .. note::
 
       In an :dir:`automodule` directive with the ``members`` option set, only
@@ -142,12 +156,30 @@ directive.
 
 
 .. directive:: autofunction
+               autodata
                automethod
                autoattribute
 
    These work exactly like :dir:`autoclass` etc., but do not offer the options
    used for automatic member documentation.
 
+   For module data members and class attributes, documentation can either be put
+   into a special-formatted comment *before* the attribute definition, or in a
+   docstring *after* the definition.  This means that in the following class
+   definition, both attributes can be autodocumented::
+
+      class Foo:
+          """Docstring for class Foo."""
+
+          #: Doc comment for attribute Foo.bar.
+          bar = 1
+
+          baz = 2
+          """Docstring for attribute Foo.baz."""
+
+   .. versionchanged:: 0.6
+      :dir:`autodata` and :dir:`autoattribute` can now extract docstrings.
+
    .. note::
 
       If you document decorated functions or methods, keep in mind that autodoc
@@ -162,19 +194,6 @@ directive.
 
 There are also new config values that you can set:
 
-.. confval:: automodule_skip_lines
-
-   This value (whose default is ``0``) can be used to skip an amount of lines in
-   every module docstring that is processed by an :dir:`automodule` directive.
-   This is provided because some projects like to put headings in the module
-   docstring, which would then interfere with your sectioning, or automatic
-   fields with version control tags, that you don't want to put in the generated
-   documentation.
-
-   .. deprecated:: 0.4
-      Use the more versatile docstring processing provided by
-      :event:`autodoc-process-docstring`.
-
 .. confval:: autoclass_content
 
    This value selects what content will be inserted into the main body of an
@@ -192,6 +211,14 @@ There are also new config values that you can set:
 
    .. versionadded:: 0.3
 
+.. confval:: autodoc_member_order
+
+   This value selects if automatically documented members are sorted
+   alphabetical (value ``'alphabetical'``) or by member type (value
+   ``'groupwise'``).  The default is alphabetical.
+
+   .. versionadded:: 0.6
+
 
 Docstring preprocessing
 -----------------------
diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst
new file mode 100644
index 00000000..a9255857
--- /dev/null
+++ b/doc/ext/autosummary.rst
@@ -0,0 +1,9 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.autosummary` -- Generate autodoc summaries
+===========================================================
+
+.. module:: sphinx.ext.autosummary
+   :synopsis: Generate autodoc summaries
+
+TBW.
diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst
index adc41016..bb11bfe2 100644
--- a/doc/ext/builderapi.rst
+++ b/doc/ext/builderapi.rst
@@ -5,7 +5,7 @@ Writing new builders
 
 .. todo:: Expand this.
 
-.. currentmodule:: sphinx.builder
+.. currentmodule:: sphinx.builders
 
 .. class:: Builder
 
@@ -20,7 +20,7 @@ Writing new builders
    .. automethod:: build_update
    .. automethod:: build
 
-   These methods must be overridden in concrete builder classes:
+   These methods can be overridden in concrete builder classes:
 
    .. automethod:: init
    .. automethod:: get_outdated_docs
@@ -28,3 +28,4 @@ Writing new builders
    .. automethod:: prepare_writing
    .. automethod:: write_doc
    .. automethod:: finish
+
diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst
index 9de6ba9e..19905dc7 100644
--- a/doc/ext/doctest.rst
+++ b/doc/ext/doctest.rst
@@ -131,7 +131,7 @@ completely equivalent. ::
 
    Test-Output example:
 
-   .. testcode:: 
+   .. testcode::
 
       parrot.voom(3000)
 
@@ -149,6 +149,14 @@ There are also these config values for customizing the doctest extension:
    A list of directories that will be added to :data:`sys.path` when the doctest
    builder is used.  (Make sure it contains absolute paths.)
 
+.. confval:: doctest_global_setup
+
+   Python code that is treated like it were put in a ``testsetup`` directive for
+   *every* file that is tested, and for every group.  You can use this to
+   e.g. import modules you will always need in your doctests.
+
+   .. versionadded:: 0.6
+
 .. confval:: doctest_test_doctest_blocks
 
    If this is a nonempty string (the default is ``'default'``), standard reST
@@ -179,7 +187,7 @@ There are also these config values for customizing the doctest extension:
          >>> print 1
          1
 
-      Some more documentation text.      
+      Some more documentation text.
 
    This feature makes it easy for you to test doctests in docstrings included
    with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a
diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst
new file mode 100644
index 00000000..d007bf25
--- /dev/null
+++ b/doc/ext/graphviz.rst
@@ -0,0 +1,77 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.graphviz` -- Add Graphviz graphs
+=================================================
+
+.. module:: sphinx.ext.graphviz
+   :synopsis: Support for Graphviz graphs.
+
+.. versionadded:: 0.6
+
+This extension allows you to embed `Graphviz <http://graphviz.org/>`_ graphs in
+your documents.
+
+It adds these directives:
+
+
+.. directive:: graphviz
+
+   Directive to embed graphviz code.  The input code for ``dot`` is given as the
+   content.  For example::
+
+      .. graphviz::
+
+         digraph foo {
+            "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.
+
+
+.. directive:: graph
+
+   Directive for embedding a single undirected graph.  The name is given as a
+   directive argument, the contents of the graph are the directive content.
+   This is a convenience directive to generate ``graph <name> { <content> }``.
+
+   For example::
+
+      .. graph:: foo
+
+         "bar" -- "baz";
+
+
+.. directive:: digraph
+
+   Directive for embedding a single directed graph.  The name is given as a
+   directive argument, the contents of the graph are the directive content.
+   This is a convenience directive to generate ``digraph <name> { <content> }``.
+
+   For example::
+
+      .. digraph:: foo
+
+         "bar" -> "baz" -> "quux";
+
+
+There are also these new config values:
+
+.. confval:: graphviz_dot
+
+   The command name with which to invoke ``dot``.  The default is ``'dot'``; you
+   may need to set this to a full path if ``dot`` is not in the executable
+   search path.
+
+   Since this setting is not portable from system to system, it is normally not
+   useful to set it in ``conf.py``; rather, giving it on the
+   :program:`sphinx-build` command line via the :option:`-D` option should be
+   preferable, like this::
+
+      sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html
+
+.. confval:: graphviz_dot_args
+
+   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.
diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst
new file mode 100644
index 00000000..fe6d636d
--- /dev/null
+++ b/doc/ext/inheritance.rst
@@ -0,0 +1,46 @@
+.. highlight:: rest
+
+:mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams
+=====================================================================
+
+.. module:: sphinx.ext.inheritance_diagram
+   :synopsis: Support for displaying inheritance diagrams via graphviz.
+
+.. versionadded:: 0.6
+
+This extension allows you to include inheritance diagrams, rendered via the
+:mod:`Graphviz extension <sphinx.ext.graphviz>`.
+
+It adds this directive:
+
+.. directive:: inheritance-diagram
+
+   This directive has one or more arguments, each giving a module or class
+   name.  Class names can be unqualified; in that case they are taken to exist
+   in the currently described module (see :dir:`module`).
+
+   For each given class, and each class in each given module, the base classes
+   are determined.  Then, from all classes and their base classes, a graph is
+   generated which is then rendered via the graphviz extension to a directed
+   graph.
+
+   This directive supports an option called ``parts`` that, if given, must be an
+   integer, advising the directive to remove that many parts of module names
+   from the displayed names.  (For example, if all your class names start with
+   ``lib.``, you can give ``:parts: 1`` to remove that prefix from the displayed
+   node names.)
+
+
+New config values are:
+
+.. confval:: inheritance_graph_attrs
+
+   A dictionary of graphviz graph attributes for inheritance diagrams.
+
+.. confval:: inheritance_node_attrs
+
+   A dictionary of graphviz node attributes for inheritance diagrams.
+
+.. confval:: inheritance_edge_attrs
+
+   A dictionary of graphviz edge attributes for inheritance diagrams.
diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst
index befae2c0..302ab6a3 100644
--- a/doc/ext/intersphinx.rst
+++ b/doc/ext/intersphinx.rst
@@ -49,7 +49,7 @@ linking:
    This will download the corresponding :file:`objects.inv` file from the
    Internet and generate links to the pages under the given URI.  The downloaded
    inventory is cached in the Sphinx environment, so it must be redownloaded
-   whenever you do a full rebuild. 
+   whenever you do a full rebuild.
 
    A second example, showing the meaning of a non-``None`` value::
 
diff --git a/doc/ext/math.rst b/doc/ext/math.rst
index f2664dfe..a214b41e 100644
--- a/doc/ext/math.rst
+++ b/doc/ext/math.rst
@@ -17,8 +17,9 @@ if possible, reuse that support too.
 
 .. note::
 
-   :mod:`sphinx.ext.mathbase` does not need to be added to the
-   :confval:`extensions` config value.
+   :mod:`sphinx.ext.mathbase` is not meant to be added to the
+   :confval:`extensions` config value, instead, use either
+   :mod:`sphinx.ext.pngmath` or :mod:`sphinx.ext.jsmath` as described below.
 
 The input language for mathematics is LaTeX markup.  This is the de-facto
 standard for plain-text math notation and has the added advantage that no
@@ -90,7 +91,7 @@ further translation is necessary when building LaTeX output.
 
       Euler's identity, equation :eq:`euler`, was elected one of the most
       beautiful mathematical formulas.
-   
+
 
 :mod:`sphinx.ext.pngmath` -- Render math as PNG images
 ------------------------------------------------------
@@ -107,8 +108,8 @@ There are various config values you can set to influence how the images are buil
 .. confval:: pngmath_latex
 
    The command name with which to invoke LaTeX.  The default is ``'latex'``; you
-   may need to set this to a full path if ``latex`` not in the executable search
-   path.
+   may need to set this to a full path if ``latex`` is not in the executable
+   search path.
 
    Since this setting is not portable from system to system, it is normally not
    useful to set it in ``conf.py``; rather, giving it on the
@@ -133,7 +134,7 @@ There are various config values you can set to influence how the images are buil
    list.
 
    .. versionadded:: 0.5.1
-   
+
 .. confval:: pngmath_latex_preamble
 
    Additional LaTeX code to put into the preamble of the short LaTeX files that
@@ -145,7 +146,7 @@ There are various config values you can set to influence how the images are buil
    Additional arguments to give to dvipng, as a list.  The default value is
    ``['-gamma 1.5', '-D 110']`` which makes the image a bit darker and larger
    then it is by default.
-   
+
    An arguments you might want to add here is e.g. ``'-bg Transparent'``,
    which produces PNGs with a transparent background.  This is not enabled by
    default because some Internet Explorer versions don't like transparent PNGs.
diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst
index 7bc65a02..4f5a379d 100644
--- a/doc/ext/todo.rst
+++ b/doc/ext/todo.rst
@@ -21,9 +21,9 @@ There are two additional directives when using this extension:
    This directive is replaced by a list of all todo directives in the whole
    documentation, if :confval:`todo_include_todos` is true.
 
-   
+
 There is also an additional config value:
-   
+
 .. confval:: todo_include_todos
 
    If this is ``True``, :dir:`todo` and :dir:`todolist` produce output, else
diff --git a/doc/ext/tutorial.rst b/doc/ext/tutorial.rst
index ae9b7a77..c44748d2 100644
--- a/doc/ext/tutorial.rst
+++ b/doc/ext/tutorial.rst
@@ -109,8 +109,8 @@ new Python module called :file:`todo.py` and add the setup function::
                     latex=(visit_todo_node, depart_todo_node),
                     text=(visit_todo_node, depart_todo_node))
 
-       app.add_directive('todo', todo_directive, 1, (0, 0, 1))
-       app.add_directive('todolist', todolist_directive, 0, (0, 0, 0))
+       app.add_directive('todo', TodoDirective)
+       app.add_directive('todolist', TodolistDirective)
        app.connect('doctree-resolved', process_todo_nodes)
        app.connect('env-purge-doc', purge_todos)
 
@@ -132,9 +132,7 @@ the individual calls do is the following:
 
   We need to create the two node classes ``todo`` and ``todolist`` later.
 
-* :meth:`~Sphinx.add_directive` adds a new *directive*, given by name, handler
-  function and two arguments that specify if the directive has content and how
-  many arguments it accepts.
+* :meth:`~Sphinx.add_directive` adds a new *directive*, given by name and class.
 
   The handler functions are created later.
 
@@ -158,7 +156,7 @@ Let's start with the node classes::
 
    def visit_todo_node(self, node):
        self.visit_admonition(node)
-    
+
    def depart_todo_node(self, node):
        self.depart_admonition(node)
 
@@ -168,17 +166,25 @@ docutils classes defined in :mod:`docutils.nodes`.  ``todo`` inherits from
 is just a "general" node.
 
 
-The Directive Handlers
-----------------------
+The Directive Classes
+---------------------
 
-A directive handler is a function with a host of arguments, covered in detail in
-the docutils documentation.  It must return a list of nodes.
+A directive class is a class deriving usually from
+``docutils.parsers.rst.Directive``.  Since the class-based directive interface
+doesn't exist yet in Docutils 0.4, Sphinx has another base class called
+``sphinx.util.compat.Directive`` that you can derive your directive from, and it
+will work with both Docutils 0.4 and 0.5 upwards.  The directive interface is
+covered in detail in the docutils documentation; the important thing is that the
+class has a method ``run`` that returns a list of nodes.
 
 The ``todolist`` directive is quite simple::
 
-   def todolist_directive(name, arguments, options, content, lineno,
-                          content_offset, block_text, state, state_machine):
-       return [todolist('')]
+   from sphinx.util.compat import Directive
+
+   class TodolistDirective(Directive):
+
+       def run(self):
+           return [todolist('')]
 
 An instance of our ``todolist`` node class is created and returned.  The
 todolist directive has neither content nor arguments that need to be handled.
@@ -187,30 +193,35 @@ The ``todo`` directive function looks like this::
 
    from sphinx.util.compat import make_admonition
 
-   def todo_directive(name, arguments, options, content, lineno,
-                      content_offset, block_text, state, state_machine):
-       env = state.document.settings.env
-    
-       targetid = "todo-%s" % env.index_num
-       env.index_num += 1
-       targetnode = nodes.target('', '', ids=[targetid])
-    
-       ad = make_admonition(todo, name, [_('Todo')], options, content, lineno,
-                            content_offset, block_text, state, state_machine)
-    
-       if not hasattr(env, 'todo_all_todos'):
-           env.todo_all_todos = []
-       env.todo_all_todos.append({
-           'docname': env.docname,
-           'lineno': lineno,
-           'todo': ad[0].deepcopy(),
-           'target': targetnode,
-       })
-    
-       return [targetnode] + ad
+   class TodoDirective(Directive):
+
+       # this enables content in the directive
+       has_content = True
+
+       def run(self):
+           env = self.state.document.settings.env
+
+           targetid = "todo-%s" % env.index_num
+           env.index_num += 1
+           targetnode = nodes.target('', '', ids=[targetid])
+
+           ad = make_admonition(todo, self.name, [_('Todo')], self.options,
+                                self.content, self.lineno, self.content_offset,
+                                self.block_text, self.state, self.state_machine)
+
+           if not hasattr(env, 'todo_all_todos'):
+               env.todo_all_todos = []
+           env.todo_all_todos.append({
+               'docname': env.docname,
+               'lineno': self.lineno,
+               'todo': ad[0].deepcopy(),
+               'target': targetnode,
+           })
+
+           return [targetnode] + ad
 
 Several important things are covered here. First, as you can see, you can refer
-to the build environment instance using ``state.document.settings.env``.
+to the build environment instance using ``self.state.document.settings.env``.
 
 Then, to act as a link target (from the todolist), the todo directive needs to
 return a target node in addition to the todo node.  The target ID (in HTML, this
@@ -236,6 +247,22 @@ node.
 In the last line, the nodes that should be put into the doctree are returned:
 the target node and the admonition node.
 
+The node structure that the directive returns looks like this::
+
+   +--------------------+
+   | target node        |
+   +--------------------+
+   +--------------------+
+   | todo node          |
+   +--------------------+
+     \__+--------------------+
+        | admonition title   |
+        +--------------------+
+        | paragraph          |
+        +--------------------+
+        | ...                |
+        +--------------------+
+
 
 The Event Handlers
 ------------------
@@ -262,20 +289,20 @@ emitted at the end of phase 3 and allows custom resolving to be done::
 
    def process_todo_nodes(app, doctree, fromdocname):
        if not app.config.todo_include_todos:
-           for node in doctree.traverse(todo_node):
+           for node in doctree.traverse(todo):
                node.parent.remove(node)
-    
+
        # Replace all todolist nodes with a list of the collected todos.
        # Augment each todo with a backlink to the original location.
        env = app.builder.env
-    
+
        for node in doctree.traverse(todolist):
            if not app.config.todo_include_todos:
                node.replace_self([])
                continue
-    
+
            content = []
-    
+
            for todo_info in env.todo_all_todos:
                para = nodes.paragraph()
                filename = env.doc2path(todo_info['docname'], base=None)
@@ -283,7 +310,7 @@ emitted at the end of phase 3 and allows custom resolving to be done::
                    _('(The original entry is located in %s, line %d and can be found ') %
                    (filename, todo_info['lineno']))
                para += nodes.Text(description, description)
-    
+
                # Create a reference
                newnode = nodes.reference('', '')
                innernode = nodes.emphasis(_('here'), _('here'))
@@ -294,11 +321,11 @@ emitted at the end of phase 3 and allows custom resolving to be done::
                newnode.append(innernode)
                para += newnode
                para += nodes.Text('.)', '.)')
-    
+
                # Insert into the todolist
                content.append(todo_info['todo'])
                content.append(para)
-    
+
            node.replace_self(content)
 
 It is a bit more involved.  If our new "todo_include_todos" config value is
diff --git a/doc/extensions.rst b/doc/extensions.rst
index 12c82da5..5eb26c14 100644
--- a/doc/extensions.rst
+++ b/doc/extensions.rst
@@ -41,9 +41,12 @@ These extensions are built in and can be activated by respective entries in the
 .. toctree::
 
    ext/autodoc
+   ext/autosummary
    ext/doctest
    ext/intersphinx
    ext/math
+   ext/graphviz
+   ext/inheritance
    ext/refcounting
    ext/ifconfig
    ext/coverage
diff --git a/doc/faq.rst b/doc/faq.rst
new file mode 100644
index 00000000..723601f1
--- /dev/null
+++ b/doc/faq.rst
@@ -0,0 +1,34 @@
+.. _faq:
+
+Sphinx FAQ
+==========
+
+This is a list of Frequently Asked Questions about Sphinx.  Feel free to
+suggest new entries!
+
+How do I...
+-----------
+
+... get section numbers?
+   They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to
+   the :dir:`toctree` directive where you want to start numbering.
+
+... customize the look of the built HTML files?
+   Use themes, see :doc:`theming`.
+
+... add global substitutions or includes?
+   Add them in the :confval:`rst_epilog` config value.
+
+... write my own extension?
+   See the :ref:`extension tutorial <exttut>`.
+
+... use Sphinx with Epydoc?
+   There's a third-party extension providing an `api role`_ which refers to
+   Epydoc's API docs for a given identifier.
+
+... use Sphinx with SCons?
+   Glenn Hutchings has written a SCons build script to build Sphinx
+   documentation; it is hosted here: http://bitbucket.org/zondo/sphinx-scons
+   
+
+.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 6a80ad36..7ec787ff 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -6,7 +6,7 @@ Glossary
 .. glossary::
 
    builder
-      A class (inheriting from :class:`~sphinx.builder.Builder`) that takes
+      A class (inheriting from :class:`~sphinx.builders.Builder`) that takes
       parsed documents and performs an action on them.  Normally, builders
       translate the documents to an output format, but it is also possible to
       use the builder builders that e.g. check for broken links in the
diff --git a/doc/intro.rst b/doc/intro.rst
index 47e016b3..7b8f8651 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -89,6 +89,12 @@ The :program:`sphinx-build` script has several more options:
    cross-references), but rebuild it completely.  The default is to only read
    and parse source files that are new or have changed since the last run.
 
+**-t** *tag*
+   Define the tag *tag*.  This is relevant for :dir:`only` directives that only
+   include their content if this tag is set.
+
+   .. versionadded:: 0.6
+
 **-d** *path*
    Since Sphinx has to read and parse all source files before it can write an
    output file, the parsed source files are cached as "doctree pickles".
@@ -109,10 +115,14 @@ The :program:`sphinx-build` script has several more options:
    Don't look for a configuration file; only take options via the ``-D`` option.
 
    .. versionadded:: 0.5
-   
+
 **-D** *setting=value*
-   Override a configuration value set in the :file:`conf.py` file.  (The value
-   must be a string value.)
+   Override a configuration value set in the :file:`conf.py` file.  The value
+   must be a string or dictionary value.  For the latter, supply the setting
+   name and key like this: ``-D latex_elements.docclass=scrartcl``.
+
+   .. versionchanged:: 0.6
+      The value can now be a dictionary value.
 
 **-A** *name=value*
    Make the *name* assigned to *value* in the HTML templates.
@@ -129,6 +139,13 @@ The :program:`sphinx-build` script has several more options:
    Do not output anything on standard output, also suppress warnings.  Only
    errors are written to standard error.
 
+**-w** *file*
+   Write warnings (and errors) to the given file, in addition to standard error.
+
+**-W**
+   Turn warnings into errors.  This means that the build stops at the first
+   warning and ``sphinx-build`` exits with exit status 1.
+
 **-P**
    (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
    unhandled exception occurs while building.
diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index 6b2fbd02..93cd127b 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -99,12 +99,14 @@ Includes
 
       .. literalinclude:: example.py
 
-   The file name is relative to the current file's path.
+   The file name is usually relative to the current file's path.  However, if it
+   is absolute (starting with ``/``), it is relative to the top source
+   directory.
 
    The directive also supports the ``linenos`` flag option to switch on line
    numbers, and a ``language`` option to select a language different from the
    current file's standard language.  Example with options::
-    
+
       .. literalinclude:: example.rb
          :language: ruby
          :linenos:
@@ -116,8 +118,36 @@ Includes
       .. literalinclude:: example.py
          :encoding: latin-1
 
+   The directive also supports including only parts of the file.  If it is a
+   Python module, you can select a class, function or method to include using
+   the ``pyobject`` option::
+
+      .. literalinclude:: example.py
+         :pyobject: Timer.start
+
+   This would only include the code lines belonging to the ``start()`` method in
+   the ``Timer`` class within the file.
+
+   Alternately, you can specify exactly which lines to include by giving a
+   ``lines`` option::
+
+      .. literalinclude:: example.py
+         :lines: 1,3,5-10,20-
+
+   This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.
+
+   Another way to control which part of the file is included is to use the
+   ``start-after`` and ``end-before`` options (or only one of them).  If
+   ``start-after`` is given as a string option, only lines that follow the first
+   line containing that string are included.  If ``end-before`` is given as a
+   string option, only lines that precede the first lines containing that string
+   are included.
+
    .. 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.
 
 
 .. rubric:: Footnotes
diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst
index 892cdc4a..ec8ede37 100644
--- a/doc/markup/desc.rst
+++ b/doc/markup/desc.rst
@@ -205,6 +205,12 @@ The directives are:
 
    .. versionadded:: 0.4
 
+.. directive:: .. classmethod:: name(signature)
+
+   Like :dir:`method`, but indicates that the method is a class method.
+
+   .. versionadded:: 0.6
+
 
 .. _signatures:
 
@@ -254,7 +260,7 @@ explained by an example::
    .. function:: format_exception(etype, value, tb[, limit=None])
 
       Format the exception with a traceback.
-   
+
       :param etype: exception type
       :param value: exception value
       :param tb: traceback object
diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index 5dbd638e..69721b32 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -224,7 +224,53 @@ to labels:
 Using :role:`ref` is advised over standard reStructuredText links to sections
 (like ```Section title`_``) because it works across files, when section headings
 are changed, and for all builders that support cross-references.
-  
+
+
+Cross-referencing documents
+---------------------------
+
+.. versionadded:: 0.6
+
+There is also a way to directly link to documents:
+
+.. role:: doc
+
+   Link to the specified document; the document name can be specified in
+   absolute or relative fashion.  For example, if the reference
+   ``:doc:`parrot``` occurs in the document ``sketches/index``, then the link
+   refers to ``sketches/parrot``.  If the reference is ``:doc:`/people``` or
+   ``:doc:`../people```, the link refers to ``people``.
+
+   If no explicit link text is given (like usual: ``:doc:`Monty Python members
+   </people>```), the link caption will be the title of the given document.
+
+
+Referencing downloadable files
+------------------------------
+
+.. versionadded:: 0.6
+
+.. role:: download
+
+   This role lets you link to files within your source tree that are not reST
+   documents that can be viewed, but files that can be downloaded.
+
+   When you use this role, the referenced file is automatically marked for
+   inclusion in the output when building (obviously, for HTML output only).
+   All downloadable files are put into the ``_downloads`` subdirectory of the
+   output directory; duplicate filenames are handled.
+
+   An example::
+
+      See :download:`this example script <../example.py>`.
+
+   The given filename is usually relative to the directory the current source
+   file is contained in, but if it absolute (starting with ``/``), it is taken
+   as relative to the top source directory.
+
+   The ``example.py`` file will be copied to the output directory, and a
+   suitable link generated to it.
+
 
 Other semantic markup
 ---------------------
@@ -232,6 +278,16 @@ Other semantic markup
 The following roles don't do anything special except formatting the text
 in a different style:
 
+.. role:: abbr
+
+   An abbreviation.  If the role content contains a parenthesized explanation,
+   it will be treated specially: it will be shown in a tool-tip in HTML, and
+   output only once in LaTeX.
+
+   Example: ``:abbr:`LIFO (last-in, first-out)```.
+
+   .. versionadded:: 0.6
+
 .. role:: command
 
    The name of an OS-level command, such as ``rm``.
@@ -330,7 +386,7 @@ in a different style:
    curly braces to indicate a "variable" part, as in ``:file:``.
 
    If you don't need the "variable part" indication, use the standard
-   ````code```` instead.   
+   ````code```` instead.
 
 
 The following roles generate external links:
@@ -351,6 +407,7 @@ The following roles generate external links:
 Note that there are no special roles for including hyperlinks as you can use
 the standard reST markup for that purpose.
 
+
 .. _default-substitutions:
 
 Substitutions
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index 98f5485e..01e5a3f1 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -3,6 +3,8 @@
 Miscellaneous markup
 ====================
 
+.. _metadata:
+
 File-wide metadata
 ------------------
 
@@ -46,6 +48,28 @@ Meta-information markup
    output.
 
 
+.. _tags:
+
+Including content based on tags
+-------------------------------
+
+.. directive:: .. only:: <expression>
+
+   Include the content of the directive only if the *expression* is true.  The
+   expression should consist of tags, like this::
+
+      .. only:: html and draft
+
+   Undefined tags are false, defined tags (via the ``-t`` command-line option or
+   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.
+
+   .. versionadded:: 0.6
+
+
 Tables
 ------
 
diff --git a/doc/markup/para.rst b/doc/markup/para.rst
index c60eb258..e8adc75c 100644
--- a/doc/markup/para.rst
+++ b/doc/markup/para.rst
@@ -1,4 +1,4 @@
-.. highlight:: rest
+x.. highlight:: rest
 
 Paragraph-level markup
 ----------------------
@@ -85,9 +85,9 @@ units as well as normal text:
 
    This directive creates a paragraph heading that is not used to create a
    table of contents node.
-   
+
    .. note::
-      
+
       If the *title* of the rubric is "Footnotes", this rubric is ignored by
       the LaTeX writer, since it is assumed to only contain footnote
       definitions and therefore would create an empty heading.
@@ -100,6 +100,27 @@ units as well as normal text:
       .. centered:: LICENSE AGREEMENT
 
 
+.. directive:: hlist
+
+   This directive must contain a bullet list.  It will transform it into a more
+   compact list by either distributing more than one item horizontally, or
+   reducing spacing between items, depending on the builder.
+
+   For builders that support the horizontal distribution, there is a ``columns``
+   option that specifies the number of columns; it defaults to 2.  Example::
+
+      .. hlist::
+         :columns: 3
+
+         * A list of
+         * short items
+         * that should be
+         * displayed
+         * horizontally
+
+   .. versionadded:: 0.6
+
+
 Table-of-contents markup
 ------------------------
 
@@ -182,14 +203,18 @@ Glossary
       .. glossary::
 
          environment
-            A structure where information about all documents under the root is saved,
-            and used for cross-referencing.  The environment is pickled after the
-            parsing stage, so that successive runs only need to read and parse new and
-            changed documents.
+            A structure where information about all documents under the root is
+            saved, and used for cross-referencing.  The environment is pickled
+            after the parsing stage, so that successive runs only need to read
+            and parse new and changed documents.
 
          source directory
-            The directory which, including its subdirectories, contains all source
-            files for one Sphinx project.
+            The directory which, including its subdirectories, contains all
+            source files for one Sphinx project.
+
+   .. versionadded:: 0.6
+      You can now give the glossary directive a ``:sorted:`` flag that will
+      automatically sort the entries alphabetically.
 
 
 Grammar production displays
@@ -218,7 +243,7 @@ the definition of the symbol.  There is this directive:
    Note that no further reST parsing is done in the production, so that you
    don't have to escape ``*`` or ``|`` characters.
 
-.. XXX describe optional first parameter 
+.. XXX describe optional first parameter
 
 The following is an example taken from the Python Reference Manual::
 
diff --git a/doc/rest.rst b/doc/rest.rst
index d7ef5c7b..e70fa105 100644
--- a/doc/rest.rst
+++ b/doc/rest.rst
@@ -212,10 +212,14 @@ reST supports an image directive, used like so::
    .. image:: gnu.png
       (options)
 
-When used within Sphinx, the file name given (here ``gnu.png``) must be relative
-to the source file, and Sphinx will automatically copy image files over to a
-subdirectory of the output directory on building (e.g. the ``_static`` directory
-for HTML output.)
+When used within Sphinx, the file name given (here ``gnu.png``) must either be
+relative to the source file, or absolute which means that they are relative to
+the top source directory.  For example, the file ``sketch/spam.rst`` could refer
+to the image ``images/spam.png`` as ``../images/spam.png`` or
+``/images/spam.png``.
+
+Sphinx will automatically copy image files over to a subdirectory of the output
+directory on building (e.g. the ``_static`` directory for HTML output.)
 
 Interpretation of image size options (``width`` and ``height``) is as follows:
 if the size has no unit or the unit is pixels, the given size will only be
@@ -236,6 +240,9 @@ the former, while the HTML builder would prefer the latter.
 .. versionchanged:: 0.4
    Added the support for file names ending in an asterisk.
 
+.. versionchanged:: 0.6
+   Image paths can now be absolute.
+
 
 Footnotes
 ---------
@@ -282,7 +289,7 @@ markup blocks, like this::
 See the `reST reference for substitutions
 <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions>`_
 for details.
-   
+
 If you want to use some substitutions for all documents, put them into a
 separate file and include it into all documents you want to use them in, using
 the :dir:`include` directive.  Be sure to give the include file a file name
@@ -301,7 +308,7 @@ footnotes above) is regarded as a comment.  For example::
    .. This is a comment.
 
 You can indent text after a comment start to form multiline comments::
-   
+
    ..
       This whole indented block
       is a comment.
@@ -329,5 +336,5 @@ There are some problems one commonly runs into while authoring reST documents:
 
 * **No nested inline markup:** Something like ``*see :func:`foo`*`` is not
   possible.
-  
+
 .. XXX more?
diff --git a/doc/sphinx-build.1 b/doc/sphinx-build.1
new file mode 100644
index 00000000..498771c9
--- /dev/null
+++ b/doc/sphinx-build.1
@@ -0,0 +1,102 @@
+.TH sphinx-build 1 "Jan 2009" "Sphinx 0.6" "User Commands"
+.SH NAME
+sphinx-build \- Sphinx documentation generator tool
+.SH SYNOPSIS
+.B sphinx-build
+[\fIoptions\fR] <\fIsourcedir\fR> <\fIoutdir\fR> [\fIfilenames\fR...]
+.SH DESCRIPTION
+sphinx-build generates documentation from the files in <sourcedir> and places it
+in the <outdir>.
+
+sphinx-build looks for <sourcedir>/conf.py for the configuration settings.
+.B sphinx-quickstart(1)
+may be used to generate template files, including conf.py.
+
+sphinx-build can create documentation in different formats.  A format is
+selected by specifying the builder name on the command line; it defaults to
+HTML.  Builders can also perform other tasks related to documentation
+processing.
+
+By default, everything that is outdated is built.  Output only for selected
+files can be built by specifying individual filenames.
+
+List of available builders:
+.TP
+\fBhtml\fR
+HTML files generation.  This is default builder.
+.TP
+\fBhtmlhelp\fR
+Generates files for CHM generation.
+.TP
+\fBqthelp\fR
+Generates files for Qt help collection generation.
+.TP
+\fBlatex\fR
+Generates a LaTeX version of the documentation.
+.TP
+\fBtext\fR
+Generates a plain-text version of the documentation.
+.TP
+\fBchanges\fR
+Generates HTML files listing changed/added/deprecated items for the
+current version.
+.TP
+\fBlinkcheck\fR
+Checks the integrity of all external links in the documentation.
+.TP
+\fBpickle / json\fR
+Generates serialized HTML files in the selected format.
+
+.SH OPTIONS
+.TP
+\fB-b\fR <builder>
+Builder to use; defaults to html. See the full list of builders above.
+.TP
+\fB-a\fR
+Generates output for all files; without this option only output for
+new and changed files is generated.
+.TP
+\fB-E\fR
+Ignores cached files, forces to re-read all source files from disk.
+.TP
+\fB-c\fR <path>
+Locates the conf.py file in the specified path instead of <sourcedir>.
+.TP
+\fB-C\fR
+Specifies that no conf.py file at all is to be used.  Configuration can
+only be set with the -D option.
+.TP
+\fB-D\fR <setting>=<value>
+Overrides a setting from the configuration file.
+.TP
+\fB-d\fR <path>
+Path to cached files; defaults to <outdir>/.doctrees.
+.TP
+\fB-A\fR <name>=<value>
+Passes a value into the HTML templates (only for html builders).
+.TP
+\fB-N\fR
+Prevents colored output.
+.TP
+\fB-q\fR
+Quiet operation, just prints warnings and errors on stderr.
+.TP
+\fB-Q\fR
+Very quiet operation, doesn't print anything except for errors.
+.TP
+\fB-w\fR <file>
+Write warnings and errors into the given file, in addition to stderr.
+.TP
+\fB-W\fR
+Turn warnings into errors.
+.TP
+\fB-P\fR
+Runs Pdb on exception.
+.SH "SEE ALSO"
+.BR sphinx-quickstart(1)
+.SH AUTHOR
+Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
+al.
+.PP
+This manual page was initially written by Mikhail Gusarov
+<dottedmag@dottedmag.net>, for the Debian project.
diff --git a/doc/sphinx-quickstart.1 b/doc/sphinx-quickstart.1
new file mode 100644
index 00000000..93b0a4a5
--- /dev/null
+++ b/doc/sphinx-quickstart.1
@@ -0,0 +1,17 @@
+.TH sphinx-quickstart 1 "Jan 2009" "Sphinx 0.6" "User Commands"
+.SH NAME
+sphinx-quickstart \- Sphinx documentation template generator
+.SH SYNOPSIS
+.B sphinx-quickstart
+.SH DESCRIPTION
+sphinx-quickstart is an interactive tool that asks some questions about your
+project and then generates a complete documentation directory and sample
+Makefile to be used with \fBsphinx-build(1)\fR.
+.SH "SEE ALSO"
+.BR sphinx-build(1)
+.SH AUTHOR
+Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
+al.
+.PP
+This manual page was initially written by Mikhail Gusarov
+<dottedmag@dottedmag.net> for the Debian project.
diff --git a/doc/templating.rst b/doc/templating.rst
index 61a8a72b..61657547 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -1,3 +1,5 @@
+.. highlight:: html+jinja
+
 .. _templating:
 
 Templating
@@ -19,10 +21,10 @@ No.  You have several other options:
   configuration value accordingly.
 
 * You can :ref:`write a custom builder <writing-builders>` that derives from
-  :class:`~sphinx.builder.StandaloneHTMLBuilder` and calls your template engine
+  :class:`~sphinx.builders.StandaloneHTMLBuilder` and calls your template engine
   of choice.
 
-* You can use the :class:`~sphinx.builder.PickleHTMLBuilder` that produces
+* You can use the :class:`~sphinx.builders.PickleHTMLBuilder` that produces
   pickle files with the page contents, and postprocess them using a custom tool,
   or use them in your Web application.
 
@@ -37,27 +39,26 @@ template, customizing it while also keeping the changes at a minimum.
 
 To customize the output of your documentation you can override all the templates
 (both the layout templates and the child templates) by adding files with the
-same name as the original filename into the template directory of the folder the
-Sphinx quickstart generated for you.
+same name as the original filename into the template directory of the structure
+the Sphinx quickstart generated for you.
 
 Sphinx will look for templates in the folders of :confval:`templates_path`
 first, and if it can't find the template it's looking for there, it falls back
-to the builtin templates that come with Sphinx.
+to the selected theme's templates.
 
 A template contains **variables**, which are replaced with values when the
 template is evaluated, **tags**, which control the logic of the template and
 **blocks** which are used for template inheritance.
 
-Sphinx provides base templates with a couple of blocks it will fill with data.
-The default templates are located in the :file:`templates` folder of the Sphinx
-installation directory.  Templates with the same name in the
-:confval:`templates_path` override templates located in the builtin folder.
+Sphinx' *basic* theme provides base templates with a couple of blocks it will
+fill with data.  These are located in the :file:`themes/basic` subdirectory of
+the Sphinx installation directory, and used by all builtin Sphinx themes.
+Templates with the same name in the :confval:`templates_path` override templates
+supplied by the selected theme.
 
 For example, to add a new link to the template area containing related links all
 you have to do is to add a new template called ``layout.html`` with the
-following contents:
-
-.. sourcecode:: html+jinja
+following contents::
 
     {% extends "!layout.html" %}
     {% block rootrellink %}
@@ -65,16 +66,24 @@ following contents:
         {{ super() }}
     {% endblock %}
 
-By prefixing the name of the extended template with an exclamation mark, Sphinx
-will load the builtin layout template.  If you override a block, you should call
-``{{ super() }}`` somewhere to render the block's content in the extended
-template -- unless you don't want that content to show up.
+By prefixing the name of the overridden template with an exclamation mark,
+Sphinx will load the layout template from the underlying HTML theme.
+
+**Important**: If you override a block, call ``{{ super() }}`` somewhere to
+render the block's content in the extended template -- unless you don't want
+that content to show up.
+
+
+Working the the builtin templates
+---------------------------------
 
+The builtin **basic** theme supplies the templates that all builtin Sphinx
+themes are based on.  It has the following elements you can override or use:
 
 Blocks
 ~~~~~~
 
-The following blocks exist in the ``layout`` template:
+The following blocks exist in the ``layout.html`` template:
 
 `doctype`
     The doctype of the output format.  By default this is XHTML 1.0 Transitional
@@ -92,11 +101,11 @@ The following blocks exist in the ``layout`` template:
     add references to JavaScript or extra CSS files.
 
 `relbar1` / `relbar2`
-    This block contains the list of related links (the parent documents on the
-    left, and the links to index, modules etc. on the right).  `relbar1` appears
-    before the document, `relbar2` after the document.  By default, both blocks
-    are filled; to show the relbar only before the document, you would override
-    `relbar2` like this::
+    This block contains the *relation bar*, the list of related links (the
+    parent documents on the left, and the links to index, modules etc. on the
+    right).  `relbar1` appears before the document, `relbar2` after the
+    document.  By default, both blocks are filled; to show the relbar only
+    before the document, you would override `relbar2` like this::
 
        {% block relbar2 %}{% endblock %}
 
@@ -109,7 +118,8 @@ The following blocks exist in the ``layout`` template:
     the :data:`reldelim1`.
 
 `document`
-    The contents of the document itself.
+    The contents of the document itself.  It contains the block "body" where the
+    individual content is put by subtemplates like ``page.html``.
 
 `sidebar1` / `sidebar2`
     A possible location for a sidebar.  `sidebar1` appears before the document
@@ -135,6 +145,10 @@ The following blocks exist in the ``layout`` template:
 `sidebarrel`
     The relation links (previous, next document) within the sidebar.
 
+`sidebarsourcelink`
+    The "Show source" link within the sidebar (normally only shown if this is
+    enabled by :confval:`html_show_sourcelink`).
+
 `sidebarsearch`
     The search box within the sidebar.  Override this if you want to place some
     content at the bottom of the sidebar.
@@ -162,13 +176,17 @@ using the ``{% set %}`` tag:
    defaults to ``' |'``.  Each item except of the last one in the related bar
    ends with the value of this variable.
 
-Overriding works like this:
-
-.. sourcecode:: html+jinja
+Overriding works like this::
 
    {% extends "!layout.html" %}
    {% set reldelim1 = ' &gt;' %}
 
+.. data:: script_files
+
+   Add additional script files here, like this::
+
+      {% set script_files = script_files + [pathto("_static/myscript.js", 1)] %}
+
 
 Helper Functions
 ~~~~~~~~~~~~~~~~
@@ -196,7 +214,7 @@ them to generate links or output multiply used elements.
 
 .. function:: relbar()
 
-   Return the rendered relbar.
+   Return the rendered relation bar.
 
 
 Global Variables
@@ -206,32 +224,145 @@ These global variables are available in every template and are safe to use.
 There are more, but most of them are an implementation detail and might change
 in the future.
 
+.. data:: builder
+
+   The name of the builder (e.g. ``html`` or ``htmlhelp``).
+
+.. data:: copyright
+
+   The value of :confval:`copyright`.
+
 .. data:: docstitle
 
    The title of the documentation (the value of :confval:`html_title`).
 
-.. data:: sourcename
+.. data:: embedded
 
-   The name of the copied source file for the current document.  This is only
-   nonempty if the :confval:`html_copy_source` value is true.
+   True if the built HTML is meant to be embedded in some viewing application
+   that handles navigation, not the web browser, such as for HTML help or Qt
+   help formats.  In this case, the sidebar is not included.
 
-.. data:: builder
+.. data:: favicon
+
+   The path to the HTML favicon in the static path, or ``''``.
+
+.. data:: file_suffix
+
+   The value of the builder's :attr:`out_suffix` attribute, i.e. the file name
+   extension that the output files will get.  For a standard HTML builder, this
+   is usually ``.html``.
+
+.. data:: has_source
+
+   True if the reST document sources are copied (if :confval:`html_copy_source`
+   is true).
+
+.. data:: last_updated
+
+   The build date.
 
-   The name of the builder (for builtin builders, ``html``, ``htmlhelp``, or
-   ``web``).
+.. data:: logo
+
+   The path to the HTML logo image in the static path, or ``''``.
+
+.. data:: master_doc
+
+   The value of :confval:`master_doc`, for usage with :func:`pathto`.
 
 .. data:: next
 
    The next document for the navigation.  This variable is either false or has
    two attributes `link` and `title`.  The title contains HTML markup.  For
-   example, to generate a link to the next page, you can use this snippet:
-
-   .. sourcecode:: html+jinja
+   example, to generate a link to the next page, you can use this snippet::
 
       {% if next %}
       <a href="{{ next.link|e }}">{{ next.title }}</a>
       {% endif %}
 
+.. data:: pagename
+
+   The "page name" of the current file, i.e. either the document name if the
+   file is generated from a reST source, or the equivalent hierarchical name
+   relative to the output directory (``[directory/]filename_without_extension``).
+
+.. data:: parents
+
+   A list of parent documents for navigation, structured like the :data:`next`
+   item.
+
 .. data:: prev
 
    Like :data:`next`, but for the previous page.
+
+.. data:: project
+
+   The value of :confval:`project`.
+
+.. data:: release
+
+   The value of :confval:`release`.
+
+.. data:: rellinks
+
+   A list of links to put at the left side of the relbar, next to "next" and
+   "prev".  This usually contains links to the index and the modindex.  If you
+   add something yourself, it must be a tuple ``(pagename, link title,
+   accesskey, link text)``.
+
+.. data:: shorttitle
+
+   The value of :confval:`html_short_title`.
+
+.. data:: show_source
+
+   True if :confval:`html_show_sourcelink` is true.
+
+.. data:: sphinx_version
+
+   The version of Sphinx used to build.
+
+.. data:: style
+
+   The name of the main stylesheet, as given by the theme or
+   :confval:`html_style`.
+
+.. data:: title
+
+   The title of the current document, as used in the ``<title>`` tag.
+
+.. data:: use_opensearch
+
+   The value of :confval:`html_use_opensearch`.
+
+.. data:: version
+
+   The value of :confval:`version`.
+
+
+In addition to these values, there are also all **theme options** available
+(prefixed by ``theme_``), as well as the values given by the user in
+:confval:`html_context`.
+
+In documents that are created from source files (as opposed to
+automatically-generated files like the module index, or documents that already
+are in HTML form), these variables are also available:
+
+.. data:: meta
+
+   Document metadata, see :ref:`metadata`.
+
+.. data:: sourcename
+
+   The name of the copied source file for the current document.  This is only
+   nonempty if the :confval:`html_copy_source` value is true.
+
+.. data:: toc
+
+   The local table of contents for the current page, rendered as HTML bullet
+   lists.
+
+.. data:: toctree
+
+   A callable yielding the global TOC tree containing the current page, rendered
+   as HTML bullet lists.  If the optional keyword argument ``collapse`` is true,
+   all TOC entries that are not ancestors of the current page are collapsed.
diff --git a/doc/theming.rst b/doc/theming.rst
new file mode 100644
index 00000000..3e3a33c8
--- /dev/null
+++ b/doc/theming.rst
@@ -0,0 +1,187 @@
+.. highlightlang:: python
+
+HTML theming support
+====================
+
+.. versionadded:: 0.6
+
+Sphinx supports changing the appearance of its HTML output via *themes*.  A
+theme is a collection of HTML templates, stylesheet(s) and other static files.
+Additionally, it has a configuration file which specifies from which theme to
+inherit, which highlighting style to use, and what options exist for customizing
+the theme's look and feel.
+
+Themes are meant to be project-unaware, so they can be used for different
+projects without change.
+
+
+Using a theme
+-------------
+
+Using an existing theme is easy.  If the theme is builtin to Sphinx, you only
+need to set the :confval:`html_theme` config value.  With the
+:confval:`html_theme_options` config value you can set theme-specific options
+that change the look and feel.  For example, you could have the following in
+your :file:`conf.py`::
+
+    html_theme = "default"
+    html_theme_options = {
+        "rightsidebar": "true",
+        "relbarbgcolor: "black"
+    }
+
+That would give you the default theme, but with a sidebar on the right side and
+a black background for the relation bar (the bar with the navigation links at
+the page's top and bottom).
+
+If the theme does not come with Sphinx, it can be in two forms: either a
+directory (containing :file:`theme.conf` and other needed files), or a zip file
+with the same contents.  Either of them must be put where Sphinx can find it;
+for this there is the config value :confval:`html_theme_path`.  It gives a list
+of directories, relative to the directory containing :file:`conf.py`, that can
+contain theme directories or zip files.  For example, if you have a theme in the
+file :file:`blue.zip`, you can put it right in the directory containing
+:file:`conf.py` and use this configuration::
+
+    html_theme = "blue"
+    html_theme_path = ["."]
+
+
+.. _builtin-themes:
+
+Builtin themes
+--------------
+
+Sphinx comes with a selection of themes to choose from:
+
+* **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
+  well.  The HTML contains all important elements like sidebar and relation bar.
+  There is one option (which is inherited by *default* and *sphinxdoc*):
+
+  - **nosidebar** (true or false): Don't include the sidebar.  Defaults to
+    false.
+
+* **default** -- This is the default theme.  It can be customized via these
+  options:
+
+  - **rightsidebar** (true or false): Put the sidebar on the right side.
+    Defaults to false.
+
+  - **stickysidebar** (true or false): Make the sidebar "fixed" so that it
+    doesn't scroll out of view for long body content.  This may not work well
+    with all browsers.  Defaults to false.
+
+  There are also various color and font options that can change the color scheme
+  without having to write a custom stylesheet:
+
+  - **footerbgcolor** (CSS color): Background color for the footer line.
+  - **footertextcolor** (CSS color): Text color for the footer line.
+  - **sidebarbgcolor** (CSS color): Background color for the sidebar.
+  - **sidebartextcolor** (CSS color): Text color for the sidebar.
+  - **sidebarlinkcolor** (CSS color): Link color for the sidebar.
+  - **relbarbgcolor** (CSS color): Background color for the relation bar.
+  - **relbartextcolor** (CSS color): Text color for the relation bar.
+  - **relbarlinkcolor** (CSS color): Link color for the relation bar.
+  - **bgcolor** (CSS color): Body background color.
+  - **textcolor** (CSS color): Body text color.
+  - **linkcolor** (CSS color): Body link color.
+  - **headbgcolor** (CSS color): Background color for headings.
+  - **headtextcolor** (CSS color): Text color for headings.
+  - **headlinkcolor** (CSS color): Link color for headings.
+  - **codebgcolor** (CSS color): Background color for code blocks.
+  - **codetextcolor** (CSS color): Default text color for code blocks, if not
+    set differently by the highlighting style.
+
+  - **bodyfont** (CSS font-family): Font for normal text.
+  - **headfont** (CSS font-family): Font for headings.
+
+* **sphinxdoc** -- The theme used for this documentation.  It features a sidebar
+  on the right side.  There are currently no options beyond *nosidebar*.
+
+* **traditional** -- A theme resembling the old Python documentation.  There are
+  currently no options beyond *nosidebar*.
+
+
+Creating themes
+---------------
+
+As said, themes are either a directory or a zipfile (whose name is the theme
+name), containing the following:
+
+* A :file:`theme.conf` file, see below.
+* HTML templates, if needed.
+* A ``static/`` directory containing any static files that will be copied to the
+  output statid directory on build.  These can be images, styles, script files.
+
+The :file:`theme.conf` file is in INI format [1]_ (readable by the standard
+Python :mod:`ConfigParser` module) and has the following structure:
+
+.. sourcecode:: ini
+
+    [theme]
+    inherit = base theme
+    stylesheet = main CSS name
+    pygments_style = stylename
+
+    [options]
+    variable = default value
+
+* The **inherit** setting gives the name of a "base theme", or ``none``.  The
+  base theme will be used to locate missing templates (most themes will not have
+  to supply most templates if they use ``basic`` as the base theme), its options
+  will be inherited, and all of its static files will be used as well.
+
+* The **stylesheet** setting gives the name of a CSS file which will be
+  referenced in the HTML header.  If you need more than one CSS file, either
+  include one from the other via CSS' ``@import``, or use a custom HTML template
+  that adds ``<link rel="stylesheet">`` tags as necessary.  Setting the
+  :confval:`html_style` config value will override this setting.
+
+* The **pygments_style** setting gives the name of a Pygments style to use for
+  highlighting.  This can be overridden by the user in the
+  :confval:`pygments_style` config value.
+
+* The **options** section contains pairs of variable names and default values.
+  These options can be overridden by the user in :confval:`html_theme_options`
+  and are accessible from all templates as ``theme_<name>``.
+
+
+Templating
+~~~~~~~~~~
+
+The :doc:`guide to templating <templating>` is helpful if you want to write your
+own templates.  What is important to keep in mind is the order in which Sphinx
+searches for templates:
+
+* First, in the user's ``templates_path`` directories.
+* Then, in the selected theme.
+* Then, in its base theme, its base's base theme, etc.
+
+When extending a template in the base theme with the same name, use the theme
+name as an explicit directory: ``{% extends "basic/layout.html" %}``.  From a
+user ``templates_path`` template, you can still use the "exclamation mark"
+syntax as described in the templating document.
+
+
+Static templates
+~~~~~~~~~~~~~~~~
+
+Since theme options are meant for the user to configure a theme more easily,
+without having to write a custom stylesheet, it is necessary to be able to
+template static files as well as HTML files.  Therefore, Sphinx supports
+so-called "static templates", like this:
+
+If the name of a file in the ``static/`` directory of a theme (or in the user's
+static path, for that matter) ends with ``_t``, it will be processed by the
+template engine.  The ``_t`` will be left from the final file name.  For
+example, the *default* theme has a file ``static/default.css_t`` which uses
+templating to put the color options into the stylesheet.  When a documentation
+is built with the default theme, the output directory will contain a
+``_static/default.css`` file where all template tags have been processed.
+
+
+.. [1] It is not an executable Python file, as opposed to :file:`conf.py`,
+       because that would pose an unnecessary security risk if themes are
+       shared.
+