merge with 0.6

57 files changed, 2812 insertions, 1196 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 89b01a08..d6a0cf72 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -9,9 +9,9 @@ PAPER        =
 PAPEROPT_a4      = -D latex_paper_size=a4
 PAPEROPT_letter  = -D latex_paper_size=letter
 ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \
-                $(SPHINXOPTS) .
+                $(SPHINXOPTS) $(O) .
 
-.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest
+.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest man
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -20,7 +20,9 @@ help:
 	@echo "  pickle    to make pickle files"
 	@echo "  json      to make json files"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
+	@echo "  epub      to make an epub file"
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  man       to make manual pages"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
 
@@ -28,25 +30,31 @@ clean:
 	-rm -rf _build/*
 
 html:
-	mkdir -p _build/html _build/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) _build/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."
 
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) _build/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in _build/singlehtml."
+
 text:
-	mkdir -p _build/text _build/doctrees
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text
 	@echo
 	@echo "Build finished."
 
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) _build/man
+	@echo
+	@echo "Build finished."
+
 pickle:
-	mkdir -p _build/pickle _build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) _build/pickle
 
 json:
@@ -54,14 +62,12 @@ json:
 	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) _build/json
 
 htmlhelp:
-	mkdir -p _build/htmlhelp _build/doctrees
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) _build/htmlhelp
 	@echo
 	@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" \
@@ -70,8 +76,12 @@ qthelp:
 	@echo "To view the help collection:"
 	@echo "# assistant -collectionFile _build/qthelp/Sphinx.qhc"
 
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) _build/epub
+	@echo
+	@echo "Build finished. The epub file is in _build/epub."
+
 latex:
-	mkdir -p _build/latex _build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in _build/latex."
@@ -79,18 +89,15 @@ latex:
 	      "run these through (pdf)latex."
 
 changes:
-	mkdir -p _build/changes _build/doctrees
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
 	@echo
 	@echo "The overview file is in _build/changes."
 
 linkcheck:
-	mkdir -p _build/linkcheck _build/doctrees
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) _build/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in _build/linkcheck/output.txt."
 
 doctest:
-	mkdir -p _build/doctest _build/doctrees
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
diff --git a/doc/_templates/index.html b/doc/_templates/index.html
index a68a6251..524b2ffb 100644
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -4,7 +4,7 @@
   <h1>Welcome</h1>
 
   <div class="quotebar">
-    <p>What users say:</p>
+    <p><em>What users say:</em></p>
     <p>&ldquo;Cheers for a great tool that actually makes programmers <b>want</b>
       to write documentation!&rdquo;</p>
   </div>
@@ -12,28 +12,30 @@
   <p>
     Sphinx is a tool that makes it easy to create intelligent and beautiful
     documentation, written by Georg Brandl and licensed under the BSD license.</p>
-  <p>It was originally created to translate <a href="http://docs.python.org/dev/">the
-    new Python documentation</a>, and it has excellent support for the documentation
-    of Python projects, but other documents can be written with it too.  Of course,
-    this site is also created from reStructuredText sources using Sphinx!
+  <p>It was originally created for <a href="http://docs.python.org/dev/">the
+    new Python documentation</a>, and it has excellent facilities for the
+    documentation of Python projects, but C/C++ is already supported as well,
+    and it is planned to add special support for other languages as well.  Of
+    course, this site is also created from reStructuredText sources using
+    Sphinx!
   </p>
   <p>
-    It is still under constant development, and the following features are
-    already present, work fine and can be seen &#8220;in action&#8221; in the
-    Python docs:
+    Sphinx is under constant development.  The following features are present,
+    work fine and can be seen &#8220;in action&#8221; in the Python docs:
   </p>
   <ul>
-    <li><b>Output formats:</b> HTML (including Windows HTML Help) and LaTeX, for
-    printable PDF versions</li>
+    <li><b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for
+      printable PDF versions), manual pages, plain text</li>
     <li><b>Extensive cross-references:</b> semantic markup and automatic links
-    for functions, classes, glossary terms and similar pieces of information</li>
+      for functions, classes, citations, glossary terms and similar pieces of
+      information</li>
     <li><b>Hierarchical structure:</b> easy definition of a document tree, with
-    automatic links to siblings, parents and children</li>
+      automatic links to siblings, parents and children</li>
     <li><b>Automatic indices:</b> general index as well as a module index</li>
     <li><b>Code handling:</b> automatic highlighting using the <a
-    href="http://pygments.org">Pygments</a> highlighter</li>
+      href="http://pygments.org">Pygments</a> highlighter</li>
     <li><b>Extensions:</b> automatic testing of code snippets, inclusion of
-    docstrings from Python modules, and more</li>
+      docstrings from Python modules (API docs), and more</li>
   </ul>
   <p>
     Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a>
@@ -42,45 +44,46 @@
     suite, the <a href="http://docutils.sf.net/">Docutils</a>.
   </p>
 
-  <h2>Examples</h2>
-  <p>
-    The <a href="http://docs.python.org/dev/">Python documentation</a> and
-    this page are different examples of Sphinx in use.
-    You can also download PDF versions of the Sphinx documentation:
-    a <a href="http://sphinx.pocoo.org/sphinx.pdf">version</a> generated from
-    the LaTeX Sphinx produces, and a
-    <a href="http://sphinx.pocoo.org/sphinx-rst2pdf.pdf">version</a> generated by rst2pdf.
-  </p>
-  <p>
-    For examples of how Sphinx source files look, use the &#8220;Show source&#8221;
-    links on all pages of the documentation apart from this welcome page.
-  </p>
-  <p>Links to more documentation generated with Sphinx can be found on the
-    <a href="{{ pathto("examples") }}">Projects using Sphinx</a> page.
-  </p>
-
   <h2>Documentation</h2>
 
   <table class="contentstable" align="center" style="margin-left: 30px"><tr>
     <td width="50%">
+      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">First steps with Sphinx</a><br/>
+         <span class="linkdescr">overview of basic tasks</span></p>
       <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/>
          <span class="linkdescr">for a complete overview</span></p>
+    </td><td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
          <span class="linkdescr">search the documentation</span></p>
-    </td><td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/>
          <span class="linkdescr">all functions, classes, terms</span></p>
-      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">Module Index</a><br/>
-         <span class="linkdescr">quick access to all documented modules</span></p>
     </td></tr>
   </table>
 
+  <p>
+    You can also download PDF versions of the Sphinx documentation:
+    a <a href="http://sphinx.pocoo.org/sphinx.pdf">version</a> generated from
+    the LaTeX Sphinx produces, and
+    a <a href="http://sphinx.pocoo.org/sphinx-rst2pdf.pdf">version</a> generated
+    by rst2pdf.
+  </p>
+
+  <h2>Examples</h2>
+  <p>Links to documentation generated with Sphinx can be found on the
+    <a href="{{ pathto("examples") }}">Projects using Sphinx</a> page.
+  </p>
+  <p>
+    For examples of how Sphinx source files look, use the &#8220;Show
+    source&#8221; links on all pages of the documentation apart from this
+    welcome page.
+  </p>
+
   <p>You may also be interested in the very nice
     <a href="http://matplotlib.sourceforge.net/sampledoc/">tutorial</a> on how to
     create a customized documentation using Sphinx written by the matplotlib
     developers.</p>
 
-  <p>There is a <a href="http://sphinx.shibu.jp/">Japanese translation</a>
+  <p>There is a <a href="http://sphinx-users.jp/doc10/">Japanese translation</a>
     of this documentation, thanks to Yoshiki Shibukawa.</p>
 
   <h2>Get Sphinx</h2>
diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
index 080c0935..6e609e1a 100644
--- a/doc/_templates/layout.html
+++ b/doc/_templates/layout.html
@@ -1,8 +1,19 @@
 {% extends "!layout.html" %}
 
+{% block extrahead %}
+{{ super() }}
+{%- if not embedded %}
+<style type="text/css">
+  table.right { float: right; margin-left: 20px; }
+  table.right td { border: 1px solid #ccc; }
+</style>
+{%- endif %}
+{% endblock %}
+
 {% block rootrellink %}
         <li><a href="{{ pathto('index') }}">Sphinx home</a>&nbsp;|&nbsp;</li>
-        <li><a href="{{ pathto('contents') }}">Documentation</a>&raquo;</li>
+        <li><a href="{{ pathto('contents') }}">Documentation</a>
+          &raquo;</li>
 {% endblock %}
 
 {% block header %}
diff --git a/doc/builders.rst b/doc/builders.rst
index bc9bfabf..6e90ccc6 100644
--- a/doc/builders.rst
+++ b/doc/builders.rst
@@ -36,6 +36,17 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionadded:: 0.6
 
+.. class:: SingleFileHTMLBuilder
+
+   This is an HTML builder that combines the whole project in one output file.
+   (Obviously this only works with smaller projects.)  The file is named like
+   the master document.  No indices will be generated.
+
+   Its name is ``singlehtml``.
+
+   .. versionadded:: 1.0
+
+.. module:: sphinx.builders.htmlhelp
 .. class:: HTMLHelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
@@ -44,6 +55,41 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``htmlhelp``.
 
+.. module:: sphinx.builders.qthelp
+.. class:: QtHelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates `Qt help`_ collection support files that allow
+   the Qt collection generator to compile them.
+
+   Its name is ``qthelp``.
+
+   .. _Qt help: http://doc.trolltech.com/4.6/qthelp-framework.html
+
+.. module:: sphinx.builders.devhelp
+.. class:: DevhelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates `GNOME Devhelp <http://live.gnome.org/devhelp>`__
+   support file that allows the GNOME Devhelp reader to view them.
+
+   Its name is ``devhelp``.
+
+.. module:: sphinx.builders.epub
+.. class:: EpubBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates an *epub* file for ebook readers.  See :ref:`epub-faq` for
+   details about it.  For definition of the epub format, have a look at
+   `<http://www.idpf.org/specs.htm>`_ or `<http://en.wikipedia.org/wiki/EPUB>`_.
+
+   Some ebook readers do not show the link targets of references.  Therefore
+   this builder adds the targets after the link when necessary.  The display
+   of the URLs can be customized by adding CSS rules for the class
+   ``link-target``.
+
+   Its name is ``epub``.
+
 .. module:: sphinx.builders.latex
 .. class:: LaTeXBuilder
 
@@ -82,6 +128,22 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf
 
    .. versionadded:: 0.4
 
+.. module:: sphinx.builders.manpage
+.. class:: ManualPageBuilder
+
+   This builder produces manual pages in the groff format.  You have to specify
+   which documents are to be included in which manual pages via the
+   :confval:`man_pages` configuration value.
+
+   Its name is ``man``.
+
+   .. note::
+
+      This builder requires the docutils manual page writer, which is only
+      available as of docutils 0.6.
+
+   .. versionadded:: 1.0
+
 .. currentmodule:: sphinx.builders.html
 .. class:: SerializingHTMLBuilder
 
@@ -89,7 +151,7 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf
    (`pickle`, `simplejson`, `phpserialize`, and others) to dump the generated
    HTML documentation.  The pickle builder is a subclass of it.
 
-   A concreate subclass of this builder serializing to the `PHP serialization`_
+   A concrete subclass of this builder serializing to the `PHP serialization`_
    format could look like this::
 
         import phpserialize
@@ -161,8 +223,8 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf
 .. module:: sphinx.builders.changes
 .. class:: ChangesBuilder
 
-   This builder produces an HTML overview of all :dir:`versionadded`,
-   :dir:`versionchanged` and :dir:`deprecated` directives for the current
+   This builder produces an HTML overview of all :rst:dir:`versionadded`,
+   :rst:dir:`versionchanged` and :rst:dir:`deprecated` directives for the current
    :confval:`version`.  This is useful to generate a ChangeLog file, for
    example.
 
@@ -234,8 +296,8 @@ The special files are located in the root output directory.  They are:
    ``project``, ``copyright``, ``release``, ``version``
       The same values as given in the configuration file.
 
-   ``style``, ``use_modindex``
-      :confval:`html_style` and :confval:`html_use_modindex`, respectively.
+   ``style``
+      :confval:`html_style`.
 
    ``last_updated``
       Date of last build.
@@ -260,7 +322,9 @@ The special files are located in the root output directory.  They are:
 ``environment.pickle``
    The build environment.  This is always a pickle file, independent of the
    builder and a copy of the environment that was used when the builder was
-   started.  (XXX: document common members)
+   started.
+
+   .. todo:: Document common members.
 
-   Unlike the other pickle files this pickle file requires that the sphinx
-   module is available on unpickling.
+   Unlike the other pickle files this pickle file requires that the ``sphinx``
+   package is available on unpickling.
diff --git a/doc/conf.py b/doc/conf.py
index 415b0c8d..08e447f2 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -2,109 +2,73 @@
 #
 # Sphinx documentation build configuration file
 
-import sys, os, re
+import re
+import sphinx
 
-# 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',
-              'sphinx.ext.autosummary']
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The suffix of source filenames.
-source_suffix = '.rst'
+              'sphinx.ext.autosummary', 'sphinx.ext.extlinks']
 
-# The master toctree document.
 master_doc = 'contents'
+templates_path = ['_templates']
+exclude_patterns = ['_build']
 
-# General substitutions.
 project = 'Sphinx'
 copyright = '2007-2010, Georg Brandl'
-
-# The default replacements for |version| and |release|, also used in various
-# other places throughout the built documents.
-import sphinx
 version = sphinx.__released__
 release = version
-
-# Show author directives in the output.
 show_authors = True
 
-# The HTML template theme.
 html_theme = 'sphinxdoc'
-
-# 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,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-html_last_updated_fmt = '%b %d, %Y'
-
-# Content template for the index page.
 html_index = 'index.html'
-
-# Custom sidebar templates, maps page names to templates.
-html_sidebars = {'index': 'indexsidebar.html'}
-
-# Additional templates that should be rendered to pages, maps page names to
-# templates.
+html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
 html_additional_pages = {'index': 'index.html'}
-
-# 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'
 
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass [howto/manual]).
+epub_theme = 'epub'
+epub_basename = 'sphinx'
+epub_author = 'Georg Brandl'
+epub_publisher = 'http://sphinx.pocoo.org/'
+epub_scheme = 'url'
+epub_identifier = epub_publisher
+epub_pre_files = [('index', 'Welcome')]
+epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
+    '_static/jquery.js', '_static/searchtools.js',
+    '_static/basic.css', 'search.html']
+
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual', 1)]
-
-# Add our logo to the LaTeX file.
 latex_logo = '_static/sphinx.png'
-
-# Additional stuff for the LaTeX preamble.
 latex_elements = {
-    'fontpkg': '\\usepackage{palatino}'
+    'fontpkg': '\\usepackage{palatino}',
 }
 
-# Put TODOs into the output.
+autodoc_member_order = 'groupwise'
 todo_include_todos = True
+extlinks = {'rstref': ('http://docutils.sourceforge.net/docs/ref/rst/'
+                       'restructuredtext.html#%s', ''),
+            'rstrole': ('http://docutils.sourceforge.net/docs/ref/rst/'
+                        'roles.html#%s', ''),
+            'rstdir': ('http://docutils.sourceforge.net/docs/ref/rst/'
+                       'directives.html#%s', '')}
+
+man_pages = [
+    ('contents', 'sphinx-all', 'Sphinx documentation generator system manual',
+     'Georg Brandl', 1),
+    ('man/sphinx-build', 'sphinx-build', 'Sphinx documentation generator tool',
+     '', 1),
+    ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
+     'template generator', '', 1),
+]
 
 
 # -- Extension interface -------------------------------------------------------
 
 from sphinx import addnodes
 
-dir_sig_re = re.compile(r'\.\. ([^:]+)::(.*)$')
-
-def parse_directive(env, sig, signode):
-    if not sig.startswith('.'):
-        dec_sig = '.. %s::' % sig
-        signode += addnodes.desc_name(dec_sig, dec_sig)
-        return sig
-    m = dir_sig_re.match(sig)
-    if not m:
-        signode += addnodes.desc_name(sig, sig)
-        return sig
-    name, args = m.groups()
-    dec_name = '.. %s::' % name
-    signode += addnodes.desc_name(dec_name, dec_name)
-    signode += addnodes.desc_addname(args, args)
-    return name
-
-
-def parse_role(env, sig, signode):
-    signode += addnodes.desc_name(':%s:' % sig, ':%s:' % sig)
-    return sig
-
 
 event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)')
 
@@ -126,9 +90,7 @@ 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('role', 'role', 'pair: %s; role', parse_role)
     app.add_description_unit('confval', 'confval',
-                             'pair: %s; configuration value')
+                             objname='configuration value',
+                             indextemplate='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 c118d165..8c9c12c1 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -1,5 +1,7 @@
 .. highlightlang:: python
 
+.. _build-config:
+
 The build configuration file
 ============================
 
@@ -85,7 +87,29 @@ General configuration
 .. confval:: master_doc
 
    The document name of the "master" document, that is, the document that
-   contains the root :dir:`toctree` directive.  Default is ``'contents'``.
+   contains the root :rst:dir:`toctree` directive.  Default is ``'contents'``.
+
+.. confval:: exclude_patterns
+
+   A list of glob-style patterns that should be excluded when looking for source
+   files. [1]_ They are matched against the source file names relative to the
+   source directory, using slashes as directory separators on all platforms.
+
+   Example patterns:
+
+   - ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file (replaces
+     entry in :confval:`unused_docs`
+   - ``'library/xml'`` -- ignores the ``library/xml`` directory (replaces entry
+     in :confval:`exclude_trees`)
+   - ``'library/xml*'`` -- ignores all files and directories starting with
+     ``library/xml``
+   - ``'**/.svn'`` -- ignores all ``.svn`` directories (replaces entry in
+     :confval:`exclude_dirnames`)
+
+   :confval:`exclude_patterns` is also consulted when looking for static files
+   in :confval:`html_static_path`.
+
+   .. versionadded:: 1.0
 
 .. confval:: unused_docs
 
@@ -93,6 +117,9 @@ General configuration
    toctree.  Use this setting to suppress the warning that is normally emitted
    in that case.
 
+   .. deprecated:: 1.0
+      Use :confval:`exclude_patterns` instead.
+
 .. confval:: exclude_trees
 
    A list of directory paths, relative to the source directory, that are to be
@@ -101,6 +128,9 @@ General configuration
 
    .. versionadded:: 0.4
 
+   .. deprecated:: 1.0
+      Use :confval:`exclude_patterns` instead.
+
 .. confval:: exclude_dirnames
 
    A list of directory names that are to be excluded from any recursive
@@ -110,15 +140,8 @@ General configuration
 
    .. versionadded:: 0.5
 
-.. confval:: exclude_dirs
-
-   A list of directory names, relative to the source directory, that are to be
-   excluded from the search for source files.
-
-   .. deprecated:: 0.5
-      This does not take subdirs of the excluded directories into account.  Use
-      :confval:`exclude_trees` or :confval:`exclude_dirnames`, which match the
-      expectations.
+   .. deprecated:: 1.0
+      Use :confval:`exclude_patterns` instead.
 
 .. confval:: locale_dirs
 
@@ -126,10 +149,11 @@ General configuration
 
    Directories in which to search for additional Sphinx message catalogs (see
    :confval:`language`), relative to the source directory.  The directories on
-   this path are searched by the standard :mod:`gettext` module for a domain of
-   ``sphinx``; so if you add the directory :file:`./locale` to this settting,
-   the message catalogs (compiled from ``.po`` format using :program:`msgfmt`)
-   must be in :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.
+   this path are searched by the standard :mod:`gettext` module for a text
+   domain of ``sphinx``; so if you add the directory :file:`./locale` to this
+   settting, the message catalogs (compiled from ``.po`` format using
+   :program:`msgfmt`) must be in
+   :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.
 
    The default is ``[]``.
 
@@ -161,17 +185,33 @@ General configuration
 
    .. versionadded:: 0.6
 
+.. confval:: rst_prolog
+
+   A string of reStructuredText that will be included at the beginning of every
+   source file that is read.
+
+   .. versionadded:: 1.0
+
+.. confval:: default_domain
+
+   .. index:: default; domain
+
+   The name of the default :ref:`domain <domains>`.  Can also be ``None`` to
+   disable a default domain.  The default is ``'py'``.
+
+   .. versionadded:: 1.0
+
 .. 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".
-   The default is ``None``, which doesn't reassign the default role.
+   ``'py:obj'`` to make ```filter``` a cross-reference to the Python function
+   "filter".  The default is ``None``, which doesn't reassign the default role.
 
    The default role can always be set within individual documents using the
-   standard reST :dir:`default-role` directive.
+   standard reST :rst:dir:`default-role` directive.
 
    .. versionadded:: 0.4
 
@@ -185,15 +225,21 @@ General configuration
 
    .. versionadded:: 0.5
 
+.. confval:: needs_sphinx
 
-.. confval:: modindex_common_prefix
+   If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
+   compare it with its version and refuse to build if it is too old.  Default is
+   no requirement.
 
-   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:: 1.0
 
-   .. versionadded:: 0.6
+.. confval:: nitpicky
+
+   If true, Sphinx will warn about *all* references where the target cannot be
+   found.  Default is ``False``.  You can activate this mode temporarily using
+   the :option:`-n` command-line switch.
+
+   .. versionadded:: 1.0
 
 
 Project information
@@ -232,19 +278,23 @@ Project information
 
    Currently supported languages are:
 
+   * ``ca`` -- Catalan
    * ``cs`` -- Czech
    * ``de`` -- German
    * ``en`` -- English
    * ``es`` -- Spanish
    * ``fi`` -- Finnish
    * ``fr`` -- French
+   * ``hr`` -- Croatian
    * ``it`` -- Italian
    * ``nl`` -- Dutch
    * ``pl`` -- Polish
    * ``pt_BR`` -- Brazilian Portuguese
    * ``ru`` -- Russian
    * ``sl`` -- Slovenian
+   * ``tr`` -- Turkish
    * ``uk_UA`` -- Ukrainian
+   * ``zh_CN`` -- Simplified Chinese
    * ``zh_TW`` -- Traditional Chinese
 
 .. confval:: today
@@ -287,14 +337,24 @@ Project information
 .. confval:: add_module_names
 
    A boolean that decides whether module names are prepended to all
-   :term:`description unit` titles, e.g. for :dir:`function` directives.
-   Default is ``True``.
+   :term:`object` names (for object types where a "module" of some kind is
+   defined), e.g. for :rst:dir:`function` directives.  Default is ``True``.
 
 .. confval:: show_authors
 
-   A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor`
+   A boolean that decides whether :rst:dir:`moduleauthor` and :rst:dir:`sectionauthor`
    directives produce any output in the built files.
 
+.. confval:: modindex_common_prefix
+
+   A list of prefixes that are ignored for sorting the Python 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
+
 .. confval:: trim_footnote_reference_space
 
    Trim spaces before footnote references that are necessary for the reST parser
@@ -302,6 +362,15 @@ Project information
 
    .. versionadded:: 0.6
 
+.. confval:: trim_doctest_flags
+
+   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
+   the ends of lines are removed for all code blocks showing interactive Python
+   sessions (i.e. doctests).  Default is true.  See the extension
+   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
+
+   .. versionadded:: 1.0
+
 
 .. _html-options:
 
@@ -388,6 +457,9 @@ that use Sphinx' HTMLWriter class.
    .. versionchanged:: 0.4
       The paths in :confval:`html_static_path` can now contain subdirectories.
 
+   .. versionchanged:: 1.0
+      The entries in :confval:`html_static_path` can now be single files.
+
 .. confval:: html_last_updated_fmt
 
    If this is not the empty string, a 'Last updated on:' timestamp is inserted
@@ -411,14 +483,53 @@ that use Sphinx' HTMLWriter class.
 .. confval:: html_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to
-   template names.  Example::
+   template names.
+
+   The keys can contain glob-style patterns [1]_, in which case all matching
+   documents will get the specified sidebars.  (A warning is emitted when a
+   more than one glob-style pattern matches for any document.)
+
+   The values can be either lists or single strings.
+
+   * If a value is a list, it specifies the complete list of sidebar templates
+     to include.  If all or some of the default sidebars are to be included,
+     they must be put into this list as well.
+
+     The default sidebars (for documents that don't match any pattern) are:
+     ``['localtoc.html', 'relations.html', 'sourcelink.html',
+     'searchbox.html']``.
+
+   * If a value is a single string, it specifies a custom sidebar to be added
+     between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries.  This
+     is for compatibility with Sphinx versions before 1.0.
+
+   Builtin sidebar templates that can be rendered are:
+
+   * **localtoc.html** -- a fine-grained table of contents of the current document
+   * **globaltoc.html** -- a coarse-grained table of contents for the whole
+     documentation set, collapsed
+   * **relations.html** -- two links to the previous and next documents
+   * **sourcelink.html** -- a link to the source of the current document, if
+     enabled in :confval:`html_show_sourcelink`
+   * **searchbox.html** -- the "quick search" box
+
+   Example::
 
       html_sidebars = {
-         'using/windows': 'windowssidebar.html'
+         '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
+         'using/windows': ['windowssidebar.html', 'searchbox.html'],
       }
 
-   This will render the template ``windowssidebar.html`` within the sidebar of
-   the given document.
+   This will render the custom template ``windowssidebar.html`` and the quick
+   search box within the sidebar of the given document, and render the default
+   sidebars for all other pages (except that the local TOC is replaced by the
+   global TOC).
+
+   .. versionadded:: 1.0
+      The ability to use globbing keys and to specify multiple sidebars.
+
+   Note that this value only has no effect if the chosen theme does not possess
+   a sidebar, like the builtin **scrolls** and **haiku** themes.
 
 .. confval:: html_additional_pages
 
@@ -447,10 +558,25 @@ that use Sphinx' HTMLWriter class.
          ... old template content ...
          {% endblock %}
 
+.. confval:: html_domain_indices
+
+   If true, generate domain-specific indices in addition to the general index.
+   For e.g. the Python domain, this is the global module index.  Default is
+   ``True``.
+
+   This value can be a bool or a list of index names that should be generated.
+   To find out the index name for a specific index, look at the HTML file name.
+   For example, the Python module index has the name ``'py-modindex'``.
+
+   .. versionadded:: 1.0
+
 .. confval:: html_use_modindex
 
    If true, add a module index to the HTML documents.   Default is ``True``.
 
+   .. deprecated:: 1.0
+      Use :confval:`html_domain_indices`.
+
 .. confval:: html_use_index
 
    If true, add an index to the HTML documents.  Default is ``True``.
@@ -513,6 +639,12 @@ that use Sphinx' HTMLWriter class.
    to translate document trees to HTML.  Default is ``None`` (use the builtin
    translator).
 
+.. confval:: html_show_copyright
+
+   If true, "(C) Copyright ..." is shown in the HTML footer. Default is ``True``.
+
+   .. versionadded:: 1.0
+
 .. confval:: html_show_sphinx
 
    If true, "Created using Sphinx" is shown in the HTML footer.  Default is
@@ -520,11 +652,130 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 0.4
 
+.. confval:: html_output_encoding
+
+   Encoding of HTML output files. Default is ``'utf-8'``.  Note that this
+   encoding name must both be a valid Python encoding name and a valid HTML
+   ``charset`` value.
+
+   .. versionadded:: 1.0
+
+.. confval:: html_compact_lists
+
+   If true, list items containing only a single paragraph will not be rendered
+   with a ``<p>`` element.  This is standard docutils behavior.  Default:
+   ``True``.
+
+   .. versionadded:: 1.0
+
+.. confval:: html_secnumber_suffix
+
+   Suffix for section numbers.  Default: ``". "``.  Set to ``" "`` to suppress
+   the final dot on section numbers.
+
+   .. versionadded:: 1.0
+
 .. confval:: htmlhelp_basename
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.
 
 
+.. _epub-options:
+
+Options for epub output
+-----------------------
+
+These options influence the epub output.  As this builder derives from the HTML
+builder, the HTML options also apply where appropriate.  The actual values for
+some of the options is not really important, they just have to be entered into
+the `Dublin Core metadata <http://dublincore.org/>`_.
+
+.. confval:: epub_basename
+
+   The basename for the epub file.  It defaults to the :confval:`project` name.
+
+.. confval:: epub_theme
+
+   The HTML theme for the epub output.  Since the default themes are not
+   optimized for small screen space, using the same theme for HTML and epub
+   output is usually not wise.  This defaults to ``'epub'``, a theme designed to
+   save visual space.
+
+.. confval:: epub_title
+
+   The title of the document.  It defaults to the :confval:`html_title` option
+   but can be set independently for epub creation.
+
+.. confval:: epub_author
+
+   The author of the document.  This is put in the Dublin Core metadata.  The
+   default value is ``'unknown'``.
+
+.. confval:: epub_language
+
+   The language of the document.  This is put in the Dublin Core metadata.  The
+   default is the :confval:`language` option or ``'en'`` if unset.
+
+.. confval:: epub_publisher
+
+   The publisher of the document.  This is put in the Dublin Core metadata.  You
+   may use any sensible string, e.g. the project homepage.  The default value is
+   ``'unknown'``.
+
+.. confval:: epub_copyright
+
+   The copyright of the document.  It defaults to the :confval:`copyright`
+   option but can be set independently for epub creation.
+
+.. confval:: epub_identifier
+
+   An identifier for the document.  This is put in the Dublin Core metadata.
+   For published documents this is the ISBN number, but you can also use an
+   alternative scheme, e.g. the project homepage.  The default value is
+   ``'unknown'``.
+
+.. confval:: epub_scheme
+
+   The publication scheme for the :confval:`epub_identifier`.  This is put in
+   the Dublin Core metadata.  For published books the scheme is ``'ISBN'``.  If
+   you use the project homepage, ``'URL'`` seems reasonable.  The default value
+   is ``'unknown'``.
+
+.. confval:: epub_uid
+
+   A unique identifier for the document.  This is put in the Dublin Core
+   metadata.  You may use a random string.  The default value is ``'unknown'``.
+
+.. confval:: epub_pre_files
+
+   Additional files that should be inserted before the text generated by
+   Sphinx. It is a list of tuples containing the file name and the title.
+   Example::
+
+      epub_pre_files = [
+          ('index.html', 'Welcome'),
+      ]
+
+   The default value is ``[]``.
+
+.. confval:: epub_post_files
+
+   Additional files that should be inserted after the text generated by Sphinx.
+   It is a list of tuples containing the file name and the title.  The default
+   value is ``[]``.
+
+.. confval:: epub_exclude_files
+
+   A list of files that are generated/copied in the build directory but should
+   not be included in the epub file.  The default value is ``[]``.
+
+.. confval:: epub_tocdepth
+
+   The depth of the table of contents in the file :file:`toc.ncx`.  It should
+   be an integer greater than zero.  The default value is 3.  Note: A deeply
+   nested table of contents may be difficult to navigate.
+
+
 .. _latex-options:
 
 Options for LaTeX output
@@ -578,10 +829,24 @@ These options influence LaTeX output.
 
    A list of document names to append as an appendix to all manuals.
 
+.. confval:: latex_domain_indices
+
+   If true, generate domain-specific indices in addition to the general index.
+   For e.g. the Python domain, this is the global module index.  Default is
+   ``True``.
+
+   This value can be a bool or a list of index names that should be generated,
+   like for :confval:`html_domain_indices`.
+
+   .. versionadded:: 1.0
+
 .. confval:: latex_use_modindex
 
    If true, add a module index to LaTeX documents.   Default is ``True``.
 
+   .. deprecated:: 1.0
+      Use :confval:`latex_domain_indices`.
+
 .. confval:: latex_elements
 
    .. versionadded:: 0.5
@@ -648,9 +913,15 @@ These options influence LaTeX output.
      ``'logo'``
      ``'releasename'``
      ``'makeindex'``
-     ``'makemodindex'``
      ``'shorthandoff'``
-     ``'printmodindex'``
+
+.. confval:: latex_docclass
+
+   A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document
+   classes that will be used as the base for the two Sphinx classes.  Default
+   is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``.
+
+   .. versionadded:: 1.0
 
 .. confval:: latex_additional_files
 
@@ -685,3 +956,42 @@ These options influence LaTeX output.
 
    .. deprecated:: 0.5
       Use the ``'pointsize'`` key in the :confval:`latex_elements` value.
+
+
+.. _man-options:
+
+Options for manual page output
+------------------------------
+
+These options influence manual page output.
+
+.. confval:: man_pages
+
+   This value determines how to group the document tree into manual pages.  It
+   must be a list of tuples ``(startdocname, name, description, authors,
+   section)``, where the items are:
+
+   * *startdocname*: document name that is the "root" of the manual page.  All
+     documents referenced by it in TOC trees will be included in the manual file
+     too.  (If you want one master manual page, use your :confval:`master_doc`
+     here.)
+   * *name*: name of the manual page.  This should be a short string without
+     spaces or special characters.  It is used to determine the file name as
+     well as the name of the manual page (in the NAME section).
+   * *description*: description of the manual page.  This is used in the NAME
+     section.
+   * *authors*: A list of strings with authors, or a single string.  Can be
+     an empty string or list if you do not want to automatically generate
+     an AUTHORS section in the manual page.
+   * *section*: The manual page section.  Used for the output file name as well
+     as in the manual page header.
+
+   .. versionadded:: 1.0
+
+
+.. rubric:: Footnotes
+
+.. [1] A note on available globbing syntax: you can use the standard shell
+       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
+       these all don't match slashes.  A double star ``**`` can be used to match
+       any sequence of characters *including* slashes.
diff --git a/doc/contents.rst b/doc/contents.rst
index 1f3860ea..079f93f2 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -7,9 +7,11 @@ Sphinx documentation contents
    :maxdepth: 2
 
    intro
-   concepts
+   tutorial
+   invocation
    rest
    markup/index
+   domains
    builders
    config
    theming
diff --git a/doc/domains.rst b/doc/domains.rst
new file mode 100644
index 00000000..0f62f176
--- /dev/null
+++ b/doc/domains.rst
@@ -0,0 +1,650 @@
+.. highlight:: rst
+
+.. _domains:
+
+Sphinx Domains
+==============
+
+.. versionadded:: 1.0
+
+What is a Domain?
+-----------------
+
+Originally, Sphinx was conceived for a single project, the documentation of the
+Python language.  Shortly afterwards, it was made available for everyone as a
+documentation tool, but the documentation of Python modules remained deeply
+built in -- the most fundamental directives, like ``function``, were designed
+for Python objects.  Since Sphinx has become somewhat popular, interest
+developed in using it for many different purposes: C/C++ projects, JavaScript,
+or even reStructuredText markup (like in this documentation).
+
+While this was always possible, it is now much easier to easily support
+documentation of projects using different programming languages or even ones not
+supported by the main Sphinx distribution, by providing a **domain** for every
+such purpose.
+
+A domain is a collection of markup (reStructuredText :term:`directive`\ s and
+:term:`role`\ s) to describe and link to :term:`object`\ s belonging together,
+e.g. elements of a programming language.  Directive and role names in a domain
+have names like ``domain:name``, e.g. ``py:function``.  Domains can also provide
+custom indices (like the Python Module Index).
+
+Having domains means that there are no naming problems when one set of
+documentation wants to refer to e.g. C++ and Python classes.  It also means that
+extensions that support the documentation of whole new languages are much easier
+to write.
+
+This section describes what the domains that come with Sphinx provide.  The
+domain API is documented as well, in the section :ref:`domain-api`.
+
+
+.. _basic-domain-markup:
+
+Basic Markup
+------------
+
+Most domains provide a number of :dfn:`object description directives`, used to
+describe specific objects provided by modules.  Each directive requires one or
+more signatures to provide basic information about what is being described, and
+the content should be the description.  The basic version makes entries in the
+general index; if no index entry is desired, you can give the directive option
+flag ``:noindex:``.  An example using a Python domain directive::
+
+   .. py:function:: spam(eggs)
+                    ham(eggs)
+      :noindex:
+
+      Spam or ham the foo.
+
+The domains also provide roles that link back to these object descriptions.  For
+example, to link to one of the functions described in the example above, you
+could say ::
+
+   The function :py:func:`spam` does a similar thing.
+
+As you can see, both directive and role names contain the domain name and the
+directive name.
+
+.. rubric:: Default Domain
+
+To avoid having to writing the domain name all the time when you e.g. only
+describe Python objects, a default domain can be selected with either the config
+value :confval:`default_domain` or this directive:
+
+.. rst:directive:: .. default-domain:: name
+
+   Select a new default domain.  While the :confval:`default_domain` selects a
+   global default, this only has an effect within the same file.
+
+If no other default is selected, the Python domain (named ``py``) is the default
+one, mostly for compatibility with documentation written for older versions of
+Sphinx.
+
+Directives and roles that belong to the default domain can be mentioned without
+giving the domain name, i.e. ::
+
+   .. function:: pyfunc()
+
+      Describes a Python function.
+
+   Reference to :func:`pyfunc`.
+
+
+Cross-referencing syntax
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+For cross-reference roles provided by domains, the same facilities exist as for
+general cross-references.  See :ref:`xref-syntax`.
+
+In short:
+
+* You may supply an explicit title and reference target: ``:role:`title
+  <target>``` will refer to *target*, but the link text will be *title*.
+
+* If you prefix the content with ``!``, no reference/hyperlink will be created.
+
+* If you prefix the content with ``~``, the link text will only be the last
+  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
+  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
+
+
+The Python Domain
+-----------------
+
+The Python domain (name **py**) provides the following directives for module
+declarations:
+
+.. rst:directive:: .. py:module:: name
+
+   This directive marks the beginning of the description of a module (or package
+   submodule, in which case the name should be fully qualified, including the
+   package name).  It does not create content (like e.g. :rst:dir:`py:class` does).
+
+   This directive will also cause an entry in the global module index.
+
+   The ``platform`` option, if present, is a comma-separated list of the
+   platforms on which the module is available (if it is available on all
+   platforms, the option should be omitted).  The keys are short identifiers;
+   examples that are in use include "IRIX", "Mac", "Windows", and "Unix".  It is
+   important to use a key which has already been used when applicable.
+
+   The ``synopsis`` option should consist of one sentence describing the
+   module's purpose -- it is currently only used in the Global Module Index.
+
+   The ``deprecated`` option can be given (with no value) to mark a module as
+   deprecated; it will be designated as such in various locations then.
+
+
+.. rst:directive:: .. py:currentmodule:: name
+
+   This directive tells Sphinx that the classes, functions etc. documented from
+   here are in the given module (like :rst:dir:`py:module`), but it will not create
+   index entries, an entry in the Global Module Index, or a link target for
+   :rst:role:`mod`.  This is helpful in situations where documentation for things in
+   a module is spread over multiple files or sections -- one location has the
+   :rst:dir:`py:module` directive, the others only :rst:dir:`py:currentmodule`.
+
+
+The following directives are provided for module and class contents:
+
+.. rst:directive:: .. py:data:: name
+
+   Describes global data in a module, including both variables and values used
+   as "defined constants."  Class and object attributes are not documented
+   using this environment.
+
+.. rst:directive:: .. py:exception:: name
+
+   Describes an exception class.  The signature can, but need not include
+   parentheses with constructor arguments.
+
+.. rst:directive:: .. py:function:: name(signature)
+
+   Describes a module-level function.  The signature should include the
+   parameters, enclosing optional parameters in brackets.  Default values can be
+   given if it enhances clarity; see :ref:`signatures`.  For example::
+
+      .. py:function:: Timer.repeat([repeat=3[, number=1000000]])
+
+   Object methods are not documented using this directive. Bound object methods
+   placed in the module namespace as part of the public interface of the module
+   are documented using this, as they are equivalent to normal functions for
+   most purposes.
+
+   The description should include information about the parameters required and
+   how they are used (especially whether mutable objects passed as parameters
+   are modified), side effects, and possible exceptions.  A small example may be
+   provided.
+
+.. rst:directive:: .. py:class:: name[(signature)]
+
+   Describes a class.  The signature can include parentheses with parameters
+   which will be shown as the constructor arguments.  See also
+   :ref:`signatures`.
+
+   Methods and attributes belonging to the class should be placed in this
+   directive's body.  If they are placed outside, the supplied name should
+   contain the class name so that cross-references still work.  Example::
+
+      .. py:class:: Foo
+         .. py:method:: quux()
+
+      -- or --
+
+      .. py:class:: Bar
+
+      .. py:method:: Bar.quux()
+
+   The first way is the preferred one.
+
+.. rst:directive:: .. py:attribute:: name
+
+   Describes an object data attribute.  The description should include
+   information about the type of the data to be expected and whether it may be
+   changed directly.
+
+.. rst:directive:: .. py:method:: name(signature)
+
+   Describes an object method.  The parameters should not include the ``self``
+   parameter.  The description should include similar information to that
+   described for ``function``.  See also :ref:`signatures`.
+
+.. rst:directive:: .. py:staticmethod:: name(signature)
+
+   Like :rst:dir:`py:method`, but indicates that the method is a static method.
+
+   .. versionadded:: 0.4
+
+.. rst:directive:: .. py:classmethod:: name(signature)
+
+   Like :rst:dir:`py:method`, but indicates that the method is a class method.
+
+   .. versionadded:: 0.6
+
+
+.. _signatures:
+
+Python Signatures
+~~~~~~~~~~~~~~~~~
+
+Signatures of functions, methods and class constructors can be given like they
+would be written in Python, with the exception that optional parameters can be
+indicated by brackets::
+
+   .. py:function:: compile(source[, filename[, symbol]])
+
+It is customary to put the opening bracket before the comma.  In addition to
+this "nested" bracket style, a "flat" style can also be used, due to the fact
+that most optional parameters can be given independently::
+
+   .. py:function:: compile(source[, filename, symbol])
+
+Default values for optional arguments can be given (but if they contain commas,
+they will confuse the signature parser).  Python 3-style argument annotations
+can also be given as well as return type annotations::
+
+   .. py:function:: compile(source : string[, filename, symbol]) -> ast object
+
+
+Info field lists
+~~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.4
+
+Inside Python object description directives, reST field lists with these fields
+are recognized and formatted nicely:
+
+* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
+  Description of a parameter.
+* ``type``: Type of a parameter.
+* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific
+  exception is raised.
+* ``var``, ``ivar``, ``cvar``: Description of a variable.
+* ``returns``, ``return``: Description of the return value.
+* ``rtype``: Return type.
+
+The field names must consist of one of these keywords and an argument (except
+for ``returns`` and ``rtype``, which do not need an argument).  This is best
+explained by an example::
+
+   .. py: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
+      :param limit: maximum number of stack frames to show
+      :type limit: integer or None
+      :rtype: list of strings
+
+It is also possible to combine parameter type and description, if the type is a
+single word, like this::
+
+   :param integer limit: maximum number of stack frames to show
+
+This will render like this:
+
+   .. py:function:: format_exception(etype, value, tb[, limit=None])
+      :noindex:
+
+      Format the exception with a traceback.
+
+      :param etype: exception type
+      :param value: exception value
+      :param tb: traceback object
+      :param limit: maximum number of stack frames to show
+      :type limit: integer or None
+      :rtype: list of strings
+
+
+Cross-referencing Python objects
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles refer to objects in modules and are possibly hyperlinked if
+a matching identifier is found:
+
+.. rst:role:: py:mod
+
+   Reference a module; a dotted name may be used.  This should also be used for
+   package names.
+
+.. rst:role:: py:func
+
+   Reference a Python function; dotted names may be used.  The role text needs
+   not include trailing parentheses to enhance readability; they will be added
+   automatically by Sphinx if the :confval:`add_function_parentheses` config
+   value is true (the default).
+
+.. rst:role:: py:data
+
+   Reference a module-level variable.
+
+.. rst:role:: py:const
+
+   Reference a "defined" constant.  This may be a C-language ``#define`` or a
+   Python variable that is not intended to be changed.
+
+.. rst:role:: py:class
+
+   Reference a class; a dotted name may be used.
+
+.. rst:role:: py:meth
+
+   Reference a method of an object.  The role text can include the type name and
+   the method name; if it occurs within the description of a type, the type name
+   can be omitted.  A dotted name may be used.
+
+.. rst:role:: py:attr
+
+   Reference a data attribute of an object.
+
+.. rst:role:: py:exc
+
+   Reference an exception.  A dotted name may be used.
+
+.. rst:role:: py:obj
+
+   Reference an object of unspecified type.  Useful e.g. as the
+   :confval:`default_role`.
+
+   .. versionadded:: 0.4
+
+The name enclosed in this markup can include a module name and/or a class name.
+For example, ``:py:func:`filter``` could refer to a function named ``filter`` in
+the current module, or the built-in function of that name.  In contrast,
+``:py:func:`foo.filter``` clearly refers to the ``filter`` function in the
+``foo`` module.
+
+Normally, names in these roles are searched first without any further
+qualification, then with the current module name prepended, then with the
+current module and class name (if any) prepended.  If you prefix the name with a
+dot, this order is reversed.  For example, in the documentation of Python's
+:mod:`codecs` module, ``:py:func:`open``` always refers to the built-in
+function, while ``:py:func:`.open``` refers to :func:`codecs.open`.
+
+A similar heuristic is used to determine whether the name is an attribute of the
+currently documented class.
+
+
+The C Domain
+------------
+
+The C domain (name **c**) is suited for documentation of C API.
+
+.. rst:directive:: .. c:function:: type name(signature)
+
+   Describes a C function. The signature should be given as in C, e.g.::
+
+      .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+   This is also used to describe function-like preprocessor macros.  The names
+   of the arguments should be given so they may be used in the description.
+
+   Note that you don't have to backslash-escape asterisks in the signature, as
+   it is not parsed by the reST inliner.
+
+.. rst:directive:: .. c:member:: type name
+
+   Describes a C struct member. Example signature::
+
+      .. c:member:: PyObject* PyTypeObject.tp_bases
+
+   The text of the description should include the range of values allowed, how
+   the value should be interpreted, and whether the value can be changed.
+   References to structure members in text should use the ``member`` role.
+
+.. rst:directive:: .. c:macro:: name
+
+   Describes a "simple" C macro.  Simple macros are macros which are used for
+   code expansion, but which do not take arguments so cannot be described as
+   functions.  This is not to be used for simple constant definitions.  Examples
+   of its use in the Python documentation include :c:macro:`PyObject_HEAD` and
+   :c:macro:`Py_BEGIN_ALLOW_THREADS`.
+
+.. rst:directive:: .. c:type:: name
+
+   Describes a C type (whether defined by a typedef or struct). The signature
+   should just be the type name.
+
+.. rst:directive:: .. c:var:: type name
+
+   Describes a global C variable.  The signature should include the type, such
+   as::
+
+      .. c:var:: PyObject* PyClass_Type
+
+
+Cross-referencing C constructs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following roles create cross-references to C-language constructs if they are
+defined in the documentation:
+
+.. rst:role:: c:data
+
+   Reference a C-language variable.
+
+.. rst:role:: c:func
+
+   Reference a C-language function. Should include trailing parentheses.
+
+.. rst:role:: c:macro
+
+   Reference a "simple" C macro, as defined above.
+
+.. rst:role:: c:type
+
+   Reference a C-language type.
+
+
+The C++ Domain
+--------------
+
+The C++ domain (name **cpp**) supports documenting C++ projects.
+
+The following directives are available:
+
+.. rst:directive:: .. cpp:class:: signatures
+               .. cpp:function:: signatures
+               .. cpp:member:: signatures
+               .. cpp:type:: signatures
+
+   Describe a C++ object.  Full signature specification is supported -- give the
+   signature as you would in the declaration.  Example::
+
+      .. cpp:function:: const int IntArray::operator[]
+
+         Describes the indexing operator of IntArrays.
+
+.. rst:directive:: .. cpp:namespace:: namespace
+
+   Select the current C++ namespace for the following objects.
+
+These roles link to the given object types:
+
+.. rst:role:: cpp:class
+          cpp:func
+          cpp:member
+          cpp:type
+
+   Reference a C++ object.  You can give the full signature (and need to, for
+   overloaded functions.)
+
+
+The Standard Domain
+-------------------
+
+The so-called "standard" domain collects all markup that doesn't warrant a
+domain of its own.  Its directives and roles are not prefixed with a domain
+name.
+
+The standard domain is also where custom object descriptions, added using the
+:func:`~sphinx.application.Sphinx.add_object_type` API, are placed.
+
+There is a set of directives allowing documenting command-line programs:
+
+.. rst:directive:: .. option:: name args, name args, ...
+
+   Describes a command line option or switch.  Option argument names should be
+   enclosed in angle brackets.  Example::
+
+      .. option:: -m <module>, --module <module>
+
+         Run a module as a script.
+
+   The directive will create a cross-reference target named after the *first*
+   option, referencable by :rst:role:`option` (in the example case, you'd use
+   something like ``:option:`-m```).
+
+.. rst:directive:: .. envvar:: name
+
+   Describes an environment variable that the documented code or program uses or
+   defines.  Referencable by :rst:role:`envvar`.
+
+.. rst:directive:: .. program:: name
+
+   Like :rst:dir:`py:currentmodule`, this directive produces no output.  Instead, it
+   serves to notify Sphinx that all following :rst:dir:`option` directives
+   document options for the program called *name*.
+
+   If you use :rst:dir:`program`, you have to qualify the references in your
+   :rst:role:`option` roles by the program name, so if you have the following
+   situation ::
+
+      .. program:: rm
+
+      .. option:: -r
+
+         Work recursively.
+
+      .. program:: svn
+
+      .. option:: -r revision
+
+         Specify the revision to work upon.
+
+   then ``:option:`rm -r``` would refer to the first option, while
+   ``:option:`svn -r``` would refer to the second one.
+
+   The program name may contain spaces (in case you want to document subcommands
+   like ``svn add`` and ``svn commit`` separately).
+
+   .. versionadded:: 0.5
+
+
+There is also a very generic object description directive, which is not tied to
+any domain:
+
+.. rst:directive:: .. describe:: text
+               .. object:: text
+
+   This directive produces the same formatting as the specific ones provided by
+   domains, but does not create index entries or cross-referencing targets.
+   Example::
+
+      .. describe:: PAPER
+
+         You can set this variable to select a paper size.
+
+
+The JavaScript Domain
+---------------------
+
+The JavaScript domain (name **js**) provides the following directives:
+
+.. rst:directive:: .. js:function:: name(signature)
+
+   Describes a JavaScript function, method or constructor.  If you want to
+   describe arguments as optional use square brackets as :ref:`documented
+   <signatures>` for Python signatures.
+
+   You can use fields to give more details about arguments and their expected
+   types, errors which may be thrown by the function, and the value being
+   returned::
+
+      .. js:function:: $.getJSON(href, callback[, errback])
+
+         :param string href: An URI to the location of the resource.
+         :param callback: Get's called with the object.
+         :param errback:
+             Get's called in case the request fails. And a lot of other
+             text so we need multiple lines
+         :throws SomeError: For whatever reason in that case.
+         :returns: Something
+
+   This is rendered as:
+
+      .. js:function:: $.getJSON(href, callback[, errback])
+
+        :param string href: An URI to the location of the resource.
+        :param callback: Get's called with the object.
+        :param errback:
+            Get's called in case the request fails. And a lot of other
+            text so we need multiple lines.
+        :throws SomeError: For whatever reason in that case.
+        :returns: Something
+
+.. rst:directive:: .. js:data:: name
+
+   Describes a global variable or constant.
+
+.. rst:directive:: .. js:attribute:: object.name
+
+   Describes the attribute *name* of *object*.
+
+These roles are provided to refer to the described objects:
+
+.. rst:role:: js:func
+          js:data
+          js:attr
+
+
+The reStructuredText domain
+---------------------------
+
+The reStructuredText domain (name **rst**) provides the following directives:
+
+.. rst:directive:: .. rst:directive:: name
+
+   Describes a reST directive.  The *name* can be a single directive name or
+   actual directive syntax (`..` prefix and `::` suffix) with arguments that
+   will be rendered differently.  For example::
+
+      .. rst:directive:: foo
+
+         Foo description.
+
+      .. rst:directive:: .. bar:: baz
+
+         Bar description.
+
+   will be rendered as:
+
+      .. rst:directive:: foo
+
+         Foo description.
+
+      .. rst:directive:: .. bar:: baz
+
+         Bar description.
+
+.. rst:directive:: .. rst:role:: name
+
+   Describes a reST role.  For example::
+
+      .. rst:role:: foo
+
+         Foo description.
+
+   will be rendered as:
+
+      .. rst:role:: foo
+
+         Foo description.
+
+These roles are provided to refer to the described objects:
+
+.. rst:role:: rst:dir
+              rst:role
+
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 398e972e..402dd72f 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -43,20 +43,42 @@ the following public API:
       ``'env'``) to a string.  However, booleans are still accepted and
       converted internally.
 
+.. method:: Sphinx.add_domain(domain)
+
+   Make the given *domain* (which must be a class; more precisely, a subclass of
+   :class:`~sphinx.domains.Domain`) known to Sphinx.
+
+   .. versionadded:: 1.0
+
+.. method:: Sphinx.override_domain(domain)
+
+   Make the given *domain* class known to Sphinx, assuming that there is already
+   a domain with its ``.name``.  The new domain must be a subclass of the
+   existing one.
+
+   .. versionadded:: 1.0
+
+.. method:: Sphinx.add_index_to_domain(domain, index)
+
+   Add a custom *index* class to the domain named *domain*.  *index* must be a
+   subclass of :class:`~sphinx.domains.Index`.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_event(name)
 
-   Register an event called *name*.
+   Register an event called *name*.  This is needed to be able to emit it.
 
 .. method:: Sphinx.add_node(node, **kwds)
 
    Register a Docutils node class.  This is necessary for Docutils internals.
    It may also be used in the future to validate nodes in the parsed documents.
 
-   Node visitor functions for the Sphinx HTML, LaTeX and text writers can be
-   given as keyword arguments: the keyword must be one or more of ``'html'``,
-   ``'latex'``, ``'text'``, the value a 2-tuple of ``(visit, depart)`` methods.
-   ``depart`` can be ``None`` if the ``visit`` function raises
-   :exc:`docutils.nodes.SkipNode`.  Example:
+   Node visitor functions for the Sphinx HTML, LaTeX, text and manpage writers
+   can be given as keyword arguments: the keyword must be one or more of
+   ``'html'``, ``'latex'``, ``'text'``, ``'man'``, the value a 2-tuple of
+   ``(visit, depart)`` methods.  ``depart`` can be ``None`` if the ``visit``
+   function raises :exc:`docutils.nodes.SkipNode`.  Example:
 
    .. code-block:: python
 
@@ -81,10 +103,10 @@ the following public API:
    Register a Docutils directive.  *name* must be the prospective directive
    name.  There are two possible ways to write a directive:
 
-   * In the docutils 0.4 style, *func* is the directive function.  *content*,
+   * In the docutils 0.4 style, *obj* 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.
+     respectively.  **This style is deprecated.**
 
    * In the docutils 0.5 style, *directiveclass* is the directive class.  It
      must already have attributes named *has_content*, *required_arguments*,
@@ -99,7 +121,7 @@ the following public API:
      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
+   For example, the (already existing) :rst:dir:`literalinclude` directive would be
    added like this:
 
    .. code-block:: python
@@ -114,12 +136,26 @@ the following public API:
    .. versionchanged:: 0.6
       Docutils 0.5-style directive classes are now supported.
 
+.. method:: Sphinx.add_directive_to_domain(domain, name, func, content, arguments, **options)
+            Sphinx.add_directive_to_domain(domain, name, directiveclass)
+
+   Like :meth:`add_directive`, but the directive is added to the domain named
+   *domain*.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_role(name, role)
 
    Register a Docutils role.  *name* must be the role name that occurs in the
    source, *role* the role function (see the `Docutils documentation
    <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ on details).
 
+.. method:: Sphinx.add_role_to_domain(domain, name, role)
+
+   Like :meth:`add_role`, but the role is added to the domain named *domain*.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_generic_role(name, nodeclass)
 
    Register a Docutils role that does nothing but wrap its contents in the
@@ -127,36 +163,38 @@ the following public API:
 
    .. versionadded:: 0.6
 
-.. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None)
+.. method:: Sphinx.add_object_type(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None, objname='')
 
-   This method is a very convenient way to add a new type of information that
+   This method is a very convenient way to add a new :term:`object` type that
    can be cross-referenced.  It will do this:
 
-   * Create a new directive (called *directivename*) for a :term:`description
-     unit`.  It will automatically add index entries if *indextemplate* is
-     nonempty; if given, it must contain exactly one instance of ``%s``.  See
-     the example below for how the template will be interpreted.
+   * Create a new directive (called *directivename*) for documenting an object.
+     It will automatically add index entries if *indextemplate* is nonempty; if
+     given, it must contain exactly one instance of ``%s``.  See the example
+     below for how the template will be interpreted.
    * Create a new role (called *rolename*) to cross-reference to these
-     description units.
+     object descriptions.
    * If you provide *parse_node*, it must be a function that takes a string and
      a docutils node, and it must populate the node with children parsed from
      the string.  It must then return the name of the item to be used in
      cross-referencing and index entries.  See the :file:`conf.py` file in the
      source for this documentation for an example.
+   * The *objname* (if not given, will default to *directivename*) names the
+     type of object.  It is used when listing objects, e.g. in search results.
 
    For example, if you have this call in a custom Sphinx extension::
 
-      app.add_description_unit('directive', 'dir', 'pair: %s; directive')
+      app.add_object_type('directive', 'dir', 'pair: %s; directive')
 
    you can use this markup in your documents::
 
-      .. directive:: function
+      .. rst:directive:: function
 
          Document a function.
 
       <...>
 
-      See also the :dir:`function` directive.
+      See also the :rst:dir:`function` directive.
 
    For the directive, an index entry will be generated as if you had prepended ::
 
@@ -168,16 +206,19 @@ the following public API:
    ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also use
    ``docutils.nodes.generated`` if you want no further text decoration).
 
-   For the role content, you have the same options as for standard Sphinx roles
-   (see :ref:`xref-syntax`).
+   For the role content, you have the same syntactical possibilities as for
+   standard Sphinx roles (see :ref:`xref-syntax`).
 
-.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None)
+   This method is also available under the deprecated alias
+   :meth:`add_description_unit`.
 
-   This method is very similar to :meth:`add_description_unit` except that the
+.. method:: Sphinx.add_crossref_type(directivename, rolename, indextemplate='', ref_nodeclass=None, objname='')
+
+   This method is very similar to :meth:`add_object_type` except that the
    directive it generates must be empty, and will produce no output.
 
    That means that you can add semantic targets to your sources, and refer to
-   them using custom roles instead of generic ones (like :role:`ref`).  Example
+   them using custom roles instead of generic ones (like :rst:role:`ref`).  Example
    call::
 
       app.add_crossref_type('topic', 'topic', 'single: %s', docutils.nodes.emphasis)
@@ -209,6 +250,14 @@ the following public API:
 
    .. versionadded:: 0.5
 
+.. method:: Sphinx.add_stylesheet(filename)
+
+   Add *filename* to the list of CSS files that the default HTML template will
+   include.  Like for :meth:`add_javascript`, the filename must be relative to
+   the HTML static path.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_lexer(alias, lexer)
 
    Use *lexer*, which must be an instance of a Pygments lexer class, to
@@ -256,11 +305,18 @@ the following public API:
 .. method:: Sphinx.emit_firstresult(event, *arguments)
 
    Emit *event* and pass *arguments* to the callback functions.  Return the
-   result of the first callback that doesn't return ``None`` (and don't call
-   the rest of the callbacks).
+   result of the first callback that doesn't return ``None``.
 
    .. versionadded:: 0.5
 
+.. method:: Sphinx.require_sphinx(version)
+
+   Compare *version* (which must be a ``major.minor`` version string,
+   e.g. ``'1.1'``) with the version of the running Sphinx, and abort the build
+   when it is too old.
+
+   .. versionadded:: 1.0
+
 
 .. exception:: ExtensionError
 
@@ -347,7 +403,15 @@ registered event handlers.
 
    .. versionadded:: 0.5
 
-.. event:: page-context (app, pagename, templatename, context, doctree)
+.. event:: html-collect-pages (app)
+
+   Emitted when the HTML builder is starting to write non-document pages.  You
+   can add pages to write by returning an iterable from this event consisting of
+   ``(pagename, context, templatename)``.
+
+   .. versionadded:: 1.0
+
+.. event:: html-page-context (app, pagename, templatename, context, doctree)
 
    Emitted when the HTML builder has created a context dictionary to render a
    template with -- this can be used to add custom elements to the context.
@@ -386,3 +450,19 @@ The template bridge
 
 .. autoclass:: TemplateBridge
    :members:
+
+
+.. _domain-api:
+
+Domain API
+----------
+
+.. module:: sphinx.domains
+
+.. autoclass:: Domain
+   :members:
+
+.. autoclass:: ObjType
+
+.. autoclass:: Index
+   :members:
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index b4b4b3f3..bd725cfa 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -27,18 +27,18 @@ two locations for documentation, while at the same time avoiding
 auto-generated-looking pure API documentation.
 
 :mod:`autodoc` provides several directives that are versions of the usual
-:dir:`module`, :dir:`class` and so forth.  On parsing time, they import the
+:rst:dir:`module`, :rst:dir:`class` and so forth.  On parsing time, they import the
 corresponding module and extract the docstring of the given objects, inserting
-them into the page source under a suitable :dir:`module`, :dir:`class` etc.
+them into the page source under a suitable :rst:dir:`module`, :rst:dir:`class` etc.
 directive.
 
 .. note::
 
-   Just as :dir:`class` respects the current :dir:`module`, :dir:`autoclass`
-   will also do so, and likewise with :dir:`method` and :dir:`class`.
+   Just as :rst:dir:`class` respects the current :rst:dir:`module`, :rst:dir:`autoclass`
+   will also do so, and likewise with :rst:dir:`method` and :rst:dir:`class`.
 
 
-.. directive:: automodule
+.. rst:directive:: automodule
                autoclass
                autoexception
 
@@ -89,6 +89,9 @@ directive.
         .. autoclass:: Noodle
            :members: eat, slurp
 
+   * If you want to make the ``members`` option the default, see
+     :confval:`autodoc_default_flags`.
+
    * Members without docstrings will be left out, unless you give the
      ``undoc-members`` flag option::
 
@@ -124,27 +127,27 @@ directive.
 
      .. versionadded:: 0.4
 
-   * The :dir:`automodule`, :dir:`autoclass` and :dir:`autoexception` directives
+   * The :rst:dir:`automodule`, :rst:dir:`autoclass` and :rst: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
+     with :rst:dir:`automodule`, this will be inserted for every class that is
      documented in the module).
 
      .. versionadded:: 0.4
 
    * All autodoc directives support the ``noindex`` flag option that has the
-     same effect as for standard :dir:`function` etc. directives: no index
+     same effect as for standard :rst:dir:`function` etc. directives: no index
      entries are generated for the documented object (and all autodocumented
      members).
 
      .. versionadded:: 0.4
 
-   * :dir:`automodule` also recognizes the ``synopsis``, ``platform`` and
-     ``deprecated`` options that the standard :dir:`module` directive supports.
+   * :rst:dir:`automodule` also recognizes the ``synopsis``, ``platform`` and
+     ``deprecated`` options that the standard :rst:dir:`module` directive supports.
 
      .. versionadded:: 0.5
 
-   * :dir:`automodule` and :dir:`autoclass` also has an ``member-order`` option
+   * :rst:dir:`automodule` and :rst: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.
 
@@ -158,18 +161,18 @@ directive.
 
    .. note::
 
-      In an :dir:`automodule` directive with the ``members`` option set, only
+      In an :rst:dir:`automodule` directive with the ``members`` option set, only
       module members whose ``__module__`` attribute is equal to the module name
       as given to ``automodule`` will be documented.  This is to prevent
       documentation of imported classes or functions.
 
 
-.. directive:: autofunction
+.. rst:directive:: autofunction
                autodata
                automethod
                autoattribute
 
-   These work exactly like :dir:`autoclass` etc., but do not offer the options
+   These work exactly like :rst: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
@@ -187,7 +190,7 @@ directive.
           """Docstring for attribute Foo.baz."""
 
    .. versionchanged:: 0.6
-      :dir:`autodata` and :dir:`autoattribute` can now extract docstrings.
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract docstrings.
 
    .. note::
 
@@ -206,12 +209,12 @@ There are also new config values that you can set:
 .. confval:: autoclass_content
 
    This value selects what content will be inserted into the main body of an
-   :dir:`autoclass` directive.  The possible values are:
+   :rst:dir:`autoclass` directive.  The possible values are:
 
    ``"class"``
       Only the class' docstring is inserted.  This is the default.  You can
-      still document ``__init__`` as a separate method using :dir:`automethod`
-      or the ``members`` option to :dir:`autoclass`.
+      still document ``__init__`` as a separate method using :rst:dir:`automethod`
+      or the ``members`` option to :rst:dir:`autoclass`.
    ``"both"``
       Both the class' and the ``__init__`` method's docstring are concatenated
       and inserted.
@@ -223,10 +226,34 @@ There are also new config values that you can set:
 .. 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.
+   alphabetical (value ``'alphabetical'``), by member type (value
+   ``'groupwise'``) or by source order (value ``'bysource'``).  The default is
+   alphabetical.
+
+   Note that for source order, the module must be a Python module with the
+   source code available.
 
    .. versionadded:: 0.6
+   .. versionchanged:: 1.0
+      Support for ``'bysource'``.
+
+.. confval:: autodoc_default_flags
+
+   This value is a list of autodoc directive flags that should be automatically
+   applied to all autodoc directives.  The supported flags are ``'members'``,
+   ``'undoc-members'``, ``'inherited-members'`` and ``'show-inheritance'``.
+
+   If you set one of these flags in this config value, you can use a negated
+   form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
+   For example, if ``autodoc_default_flags`` is set to ``['members',
+   'undoc-members']``, and you write a directive like this::
+
+      .. automodule:: foo
+         :no-undoc-members:
+
+   the directive will be interpreted as if only ``:members:`` was given.
+
+   .. versionadded:: 1.0
 
 
 Docstring preprocessing
diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst
index 7b5e5b6b..9f66e510 100644
--- a/doc/ext/autosummary.rst
+++ b/doc/ext/autosummary.rst
@@ -15,22 +15,22 @@ one of them on a separate page makes them easier to read.
 
 The :mod:`sphinx.ext.autosummary` extension does this in two parts:
 
-1. There is an :dir:`autosummary` directive for generating summary listings that
+1. There is an :rst:dir:`autosummary` directive for generating summary listings that
    contain links to the documented items, and short summary blurbs extracted
    from their docstrings.
 
 2. The convenience script :program:`sphinx-autogen` or the new
    :confval:`autosummary_generate` config value can be used to generate short
-   "stub" files for the entries listed in the :dir:`autosummary` directives.
+   "stub" files for the entries listed in the :rst:dir:`autosummary` directives.
    These by default contain only the corresponding :mod:`sphinx.ext.autodoc`
    directive.
 
 
-.. directive:: autosummary
+.. rst:directive:: autosummary
 
    Insert a table that contains links to documented items, and a short summary
    blurb (the first sentence of the docstring) for each of them.  The
-   :dir:`autosummary` directive can also optionally serve as a :dir:`toctree`
+   :rst:dir:`autosummary` directive can also optionally serve as a :rst:dir:`toctree`
    entry for the included items.
 
    For example, ::
@@ -60,7 +60,7 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
 
    **Options**
 
-   * If you want the :dir:`autosummary` table to also serve as a :dir:`toctree`
+   * If you want the :rst:dir:`autosummary` table to also serve as a :rst:dir:`toctree`
      entry, use the ``toctree`` option, for example::
 
          .. autosummary::
@@ -76,7 +76,7 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
      directory. If no argument is given, output is placed in the same directory
      as the file that contains the directive.
 
-   * If you don't want the :dir:`autosummary` to show function signatures in the
+   * If you don't want the :rst:dir:`autosummary` to show function signatures in the
      listing, include the ``nosignatures`` option::
 
          .. autosummary::
@@ -85,18 +85,32 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
             sphinx.environment.BuildEnvironment
             sphinx.util.relative_uri
 
+   * You can specify a custom template with the ``template`` option.
+     For example, ::
+
+         .. autosummary::
+            :template: mytemplate.rst
+
+            sphinx.environment.BuildEnvironment
+
+     would use the template :file:`mytemplate.rst` in your
+     :confval:`templates_path` to generate the pages for all entries
+     listed. See `Customizing templates`_ below.
+
+     .. versionadded:: 1.0
+
 
 :program:`sphinx-autogen` -- generate autodoc stub pages
 --------------------------------------------------------
 
 The :program:`sphinx-autogen` script can be used to conveniently generate stub
-documentation pages for items included in :dir:`autosummary` listings.
+documentation pages for items included in :rst:dir:`autosummary` listings.
 
 For example, the command ::
 
     $ sphinx-autogen -o generated *.rst
 
-will read all :dir:`autosummary` tables in the :file:`*.rst` files that have the
+will read all :rst:dir:`autosummary` tables in the :file:`*.rst` files that have the
 ``:toctree:`` option set, and output corresponding stub pages in directory
 ``generated`` for all documented items.  The generated pages by default contain
 text of the form::
@@ -118,7 +132,100 @@ also use this new config value:
 
 .. confval:: autosummary_generate
 
-   A list of documents for which stub pages should be generated.
+   Boolean indicating whether to scan all found documents for autosummary
+   directives, and to generate stub pages for each.
+
+   Can also be a list of documents for which stub pages should be generated.
 
    The new files will be placed in the directories specified in the
    ``:toctree:`` options of the directives.
+
+
+Customizing templates
+---------------------
+
+.. versionadded:: 1.0
+
+You can customize the stub page templates, in a similar way as the HTML Jinja
+templates, see :ref:`templating`. (:class:`~sphinx.application.TemplateBridge`
+is not supported.)
+
+.. note::
+
+   If you find yourself spending much time tailoring the stub templates, this
+   may indicate that it's a better idea to write custom narrative documentation
+   instead.
+
+Autosummary uses the following template files:
+
+- :file:`autosummary/base.rst` -- fallback template
+- :file:`autosummary/module.rst` -- template for modules
+- :file:`autosummary/class.rst` -- template for classes
+- :file:`autosummary/function.rst` -- template for functions
+- :file:`autosummary/attribute.rst` -- template for class attributes
+- :file:`autosummary/method.rst` -- template for class methods
+
+The following variables available in the templates:
+
+.. currentmodule:: None
+
+.. data:: name
+
+   Name of the documented object, excluding the module and class parts.
+
+.. data:: objname
+
+   Name of the documented object, excluding the module parts.
+
+.. data:: fullname
+
+   Full name of the documented object, including module and class parts.
+
+.. data:: module
+
+   Name of the module the documented object belongs to.
+
+.. data:: class
+
+   Name of the class the documented object belongs to.  Only available for
+   methods and attributes.
+
+.. data:: underline
+
+   A string containing ``len(full_name) * '='``.
+
+.. data:: members
+
+   List containing names of all members of the module or class.  Only available
+   for modules and classes.
+
+.. data:: functions
+
+   List containing names of "public" functions in the module.  Here, "public"
+   here means that the name does not start with an underscore. Only available
+   for modules.
+
+.. data:: classes
+
+   List containing names of "public" classes in the module.  Only available for
+   modules.
+
+.. data:: exceptions
+
+   List containing names of "public" exceptions in the module.  Only available
+   for modules.
+
+.. data:: methods
+
+   List containing names of "public" methods in the class.  Only available for
+   classes.
+
+.. data:: attributes
+
+   List containing names of "public" attributes in the class.  Only available
+   for classes.
+
+.. note::
+
+   You can use the :rst:dir:`autosummary` directive in the stub pages.
+   Stub pages are generated also based on these directives.
diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst
index bb11bfe2..3ace2687 100644
--- a/doc/ext/builderapi.rst
+++ b/doc/ext/builderapi.rst
@@ -13,7 +13,6 @@ Writing new builders
 
    These methods are predefined and will be called from the application:
 
-   .. automethod:: load_env
    .. automethod:: get_relative_uri
    .. automethod:: build_all
    .. automethod:: build_specific
diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst
index 0c64f17a..20e747de 100644
--- a/doc/ext/doctest.rst
+++ b/doc/ext/doctest.rst
@@ -39,13 +39,13 @@ interpreted as follows: if it is empty, the block is assigned to the group named
 ``default`` group).  Otherwise, it must be a comma-separated list of group
 names.
 
-.. directive:: .. testsetup:: [group]
+.. rst:directive:: .. testsetup:: [group]
 
    A setup code block.  This code is not shown in the output for other builders,
    but executed before the doctests of the group(s) it belongs to.
 
 
-.. directive:: .. doctest:: [group]
+.. rst:directive:: .. doctest:: [group]
 
    A doctest-style code block.  You can use standard :mod:`doctest` flags for
    controlling how actual output is compared with what you give as output.  By
@@ -78,7 +78,7 @@ names.
    output.
 
 
-.. directive:: .. testcode:: [group]
+.. rst:directive:: .. testcode:: [group]
 
    A code block for a code-output-style test.
 
@@ -107,10 +107,10 @@ names.
       applies to testcode/testoutput as well.
 
 
-.. directive:: .. testoutput:: [group]
+.. rst:directive:: .. testoutput:: [group]
 
    The corresponding output, or the exception message, for the last
-   :dir:`testcode` block.
+   :rst:dir:`testcode` block.
 
    This directive supports two options:
 
@@ -134,7 +134,7 @@ names.
 
 
 The following is an example for the usage of the directives.  The test via
-:dir:`doctest` and the test via :dir:`testcode` and :dir:`testoutput` are
+:rst:dir:`doctest` and the test via :rst:dir:`testcode` and :rst:dir:`testoutput` are
 equivalent. ::
 
    The parrot module
@@ -197,9 +197,9 @@ There are also these config values for customizing the doctest extension:
 
       Some more documentation text.
 
-   (Note that no special ``::`` is needed to introduce the block; docutils
-   recognizes it from the leading ``>>>``.  Also, no additional indentation is
-   necessary, though it doesn't hurt.)
+   (Note that no special ``::`` is used to introduce a doctest block; docutils
+   recognizes them from the leading ``>>>``.  Also, no additional indentation is
+   used, though it doesn't hurt.)
 
    If this value is left at its default value, the above snippet is interpreted
    by the doctest builder exactly like the following::
@@ -220,4 +220,5 @@ There are also these config values for customizing the doctest extension:
    Note though that you can't have blank lines in reST doctest blocks.  They
    will be interpreted as one block ending and another one starting.  Also,
    removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
-   :dir:`doctest` blocks.
+   :rst:dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to
+   achieve the latter in all code blocks with Python console content.
diff --git a/doc/ext/extlinks.rst b/doc/ext/extlinks.rst
new file mode 100644
index 00000000..d4478c5b
--- /dev/null
+++ b/doc/ext/extlinks.rst
@@ -0,0 +1,54 @@
+:mod:`sphinx.ext.extlinks` -- Markup to shorten external links
+==============================================================
+
+.. module:: sphinx.ext.extlinks
+   :synopsis: Allow inserting external links with common base URLs easily.
+.. moduleauthor:: Georg Brandl
+
+.. versionadded:: 1.0
+
+
+This extension is meant to help with the common pattern of having many external
+links that point to URLs on one and the same site, e.g. links to bug trackers,
+version control web interfaces, or simply subpages in other websites.  It does
+so by providing aliases to base URLs, so that you only need to give the subpage
+name when creating a link.
+
+Let's assume that you want to include many links to issues at the Sphinx
+tracker, at :samp:`http://bitbucket.org/birkenfeld/sphinx/issue/{num}`.  Typing
+this URL again and again is tedious, so you can use :mod:`~sphinx.ext.extlinks`
+to avoid repeating yourself.
+
+The extension adds one new config value:
+
+.. confval:: extlinks
+
+   This config value must be a dictionary of external sites, mapping unique
+   short alias names to a base URL and a *prefix*.  For example, to create an
+   alias for the above mentioned issues, you would add ::
+
+      extlinks = {'issue': ('http://bitbucket.org/birkenfeld/sphinx/issue/%s',
+                            'issue ')}
+
+   Now, you can use the alias name as a new role, e.g. ``:issue:`123```.  This
+   then inserts a link to http://bitbucket.org/birkenfeld/sphinx/issue/123.
+   As you can see, the target given in the role is substituted in the base URL
+   in the place of ``%s``.
+
+   The link *caption* depends on the second item in the tuple, the *prefix*:
+
+   - If the prefix is ``None``, the link caption is the full URL.
+   - If the prefix is the empty string, the link caption is the partial URL
+     given in the role content (``123`` in this case.)
+   - If the prefix is a non-empty string, the link caption is the partial URL,
+     prepended by the prefix -- in the above example, the link caption would be
+     ``issue 123``.
+
+   You can also use the usual "explicit title" syntax supported by other roles
+   that generate links, i.e. ``:issue:`this issue <123>```.  In this case, the
+   *prefix* is not relevant.
+
+.. note::
+
+   Since links are generated from the role in the reading stage, they appear as
+   ordinary links to e.g. the ``linkcheck`` builder.
diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst
index d007bf25..3741cec6 100644
--- a/doc/ext/graphviz.rst
+++ b/doc/ext/graphviz.rst
@@ -14,7 +14,7 @@ your documents.
 It adds these directives:
 
 
-.. directive:: graphviz
+.. rst:directive:: graphviz
 
    Directive to embed graphviz code.  The input code for ``dot`` is given as the
    content.  For example::
@@ -25,11 +25,12 @@ It adds these directives:
             "bar" -> "baz";
          }
 
-   In HTML output, the code will be rendered to a PNG image.  In LaTeX output,
-   the code will be rendered to an embeddable PDF file.
+   In HTML output, the code will be rendered to a PNG or SVG image (see
+   :confval:`graphviz_output_format`).  In LaTeX output, the code will be
+   rendered to an embeddable PDF file.
 
 
-.. directive:: graph
+.. rst: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.
@@ -42,7 +43,7 @@ It adds these directives:
          "bar" -- "baz";
 
 
-.. directive:: digraph
+.. rst: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.
@@ -55,6 +56,12 @@ It adds these directives:
          "bar" -> "baz" -> "quux";
 
 
+.. versionadded:: 1.0
+   All three directives support an ``alt`` option that determines the image's
+   alternate text for HTML output.  If not given, the alternate text defaults to
+   the graphviz code.
+
+
 There are also these new config values:
 
 .. confval:: graphviz_dot
@@ -75,3 +82,11 @@ There are also these new config values:
    Additional command-line arguments to give to dot, as a list.  The default is
    an empty list.  This is the right place to set global graph, node or edge
    attributes via dot's ``-G``, ``-N`` and ``-E`` options.
+
+.. confval:: graphviz_output_format
+
+   The output format for Graphviz when building HTML files.  This must be either
+   ``'png'`` or ``'svg'``; the default is ``'png'``.
+
+   .. versionadded:: 1.0
+      Previously, output always was PNG.
diff --git a/doc/ext/ifconfig.rst b/doc/ext/ifconfig.rst
index d7d16981..a11e3072 100644
--- a/doc/ext/ifconfig.rst
+++ b/doc/ext/ifconfig.rst
@@ -8,7 +8,7 @@
 
 This extension is quite simple, and features only one directive:
 
-.. directive:: ifconfig
+.. rst:directive:: ifconfig
 
    Include content of the directive only if the Python expression given as an
    argument is ``True``, evaluated in the namespace of the project's
diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst
index 72849e05..76388a94 100644
--- a/doc/ext/inheritance.rst
+++ b/doc/ext/inheritance.rst
@@ -13,11 +13,11 @@ This extension allows you to include inheritance diagrams, rendered via the
 
 It adds this directive:
 
-.. directive:: inheritance-diagram
+.. rst: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`).
+   in the currently described module (see :rst: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
diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst
index 6a079cd4..29b4057f 100644
--- a/doc/ext/intersphinx.rst
+++ b/doc/ext/intersphinx.rst
@@ -8,17 +8,16 @@
 
 .. versionadded:: 0.5
 
-This extension can generate automatic links to the documentation of Python
-objects in other projects.  This works as follows:
+This extension can generate automatic links to the documentation of objects in
+other projects.  This works as follows:
 
-* Each Sphinx HTML build creates a file named :file:`objects.inv` that
-  contains a mapping from Python identifiers to URIs relative to the HTML set's
-  root.
+* Each Sphinx HTML build creates a file named :file:`objects.inv` that contains
+  a mapping from object names to URIs relative to the HTML set's root.
 
 * Projects using the Intersphinx extension can specify the location of such
   mapping files in the :confval:`intersphinx_mapping` config value.  The mapping
-  will then be used to resolve otherwise missing references to Python objects
-  into links to the other documentation.
+  will then be used to resolve otherwise missing references to objects into
+  links to the other documentation.
 
 * By default, the mapping file is assumed to be at the same location as the rest
   of the documentation; however, the location of the mapping file can also be
@@ -31,37 +30,63 @@ linking:
 
 .. confval:: intersphinx_mapping
 
+   This config value contains the locations and names of other projects that
+   should be linked to in this documentation.
+
+   Relative local paths for target locations are taken as relative to the base
+   of the built documentation, while relative local paths for inventory
+   locations are taken as relative to the source directory.
+
+   When fetching remote inventory files, proxy settings will be read from
+   the ``$HTTP_PROXY`` environment variable.
+
+   **Old format for this config value**
+
+   This is the format used before Sphinx 1.0.  It is still recognized.
+
    A dictionary mapping URIs to either ``None`` or an URI.  The keys are the
    base URI of the foreign Sphinx documentation sets and can be local paths or
    HTTP URIs.  The values indicate where the inventory file can be found: they
    can be ``None`` (at the same location as the base URI) or another local or
    HTTP URI.
 
-   Relative local paths in the keys are taken as relative to the base of the
-   built documentation, while relative local paths in the values are taken as
-   relative to the source directory.
+   **New format for this config value**
 
-   An example, to add links to modules and objects in the Python standard
-   library documentation::
+   .. versionadded:: 1.0
 
-      intersphinx_mapping = {'http://docs.python.org/': None}
+   A dictionary mapping unique identifiers to a tuple ``(target, inventory)``.
+   Each ``target`` is the base URI of a foreign Sphinx documentation set and can
+   be a local path or an HTTP URI.  The ``inventory`` indicates where the
+   inventory file can be found: it can be ``None`` (at the same location as
+   the base URI) or another local or HTTP URI.
+
+   The unique identifier can be used to prefix cross-reference targets, so that
+   it is clear which intersphinx set the target belongs to.  A link like
+   ``:ref:`comparison manual <python:comparisons>``` will link to the label
+   "comparisons" in the doc set "python", if it exists.
+
+   **Example**
+
+   To add links to modules and objects in the Python standard library
+   documentation, use::
+
+      intersphinx_mapping = {'python': ('http://docs.python.org/', None)}
 
    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.
 
-   A second example, showing the meaning of a non-``None`` value::
+   A second example, showing the meaning of a non-``None`` value of the second
+   tuple item::
 
-      intersphinx_mapping = {'http://docs.python.org/': 'python-inv.txt'}
+      intersphinx_mapping = {'python': ('http://docs.python.org/',
+                                        'python-inv.txt')}
 
    This will read the inventory from :file:`python-inv.txt` in the source
    directory, but still generate links to the pages under
-   ``http://docs.python.org/``.  It is up to you to update the inventory file
-   as new objects are added to the Python documentation.
-
-   When fetching remote inventory files, proxy settings will be read from
-   the ``$HTTP_PROXY`` environment variable.
+   ``http://docs.python.org/``.  It is up to you to update the inventory file as
+   new objects are added to the Python documentation.
 
 .. confval:: intersphinx_cache_limit
 
diff --git a/doc/ext/math.rst b/doc/ext/math.rst
index c1602558..b9f6ab12 100644
--- a/doc/ext/math.rst
+++ b/doc/ext/math.rst
@@ -27,13 +27,13 @@ further translation is necessary when building LaTeX output.
 
 :mod:`mathbase` defines these new markup elements:
 
-.. role:: math
+.. rst:role:: math
 
    Role for inline math.  Use like this::
 
       Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.
 
-.. directive:: math
+.. rst:directive:: math
 
    Directive for displayed math (math that takes the whole line for itself).
 
@@ -66,7 +66,7 @@ further translation is necessary when building LaTeX output.
    Normally, equations are not numbered.  If you want your equation to get a
    number, use the ``label`` option.  When given, it selects a label for the
    equation, by which it can be cross-referenced, and causes an equation number
-   to be issued.  See :role:`eqref` for an example.  The numbering style depends
+   to be issued.  See :rst:role:`eqref` for an example.  The numbering style depends
    on the output format.
 
    There is also an option ``nowrap`` that prevents any wrapping of the given
@@ -81,7 +81,7 @@ further translation is necessary when building LaTeX output.
             f(x) & = & x^2 + 2xy + y^2
          \end{eqnarray}
 
-.. role:: eq
+.. rst:role:: eq
 
    Role for cross-referencing equations via their label.  This currently works
    only within the same document.  Example::
diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst
index 4f5a379d..349d286a 100644
--- a/doc/ext/todo.rst
+++ b/doc/ext/todo.rst
@@ -9,14 +9,14 @@
 
 There are two additional directives when using this extension:
 
-.. directive:: todo
+.. rst:directive:: todo
 
-   Use this directive like, for example, :dir:`note`.
+   Use this directive like, for example, :rst:dir:`note`.
 
    It will only show up in the output if :confval:`todo_include_todos` is true.
 
 
-.. directive:: todolist
+.. rst:directive:: todolist
 
    This directive is replaced by a list of all todo directives in the whole
    documentation, if :confval:`todo_include_todos` is true.
@@ -26,5 +26,5 @@ There is also an additional config value:
 
 .. confval:: todo_include_todos
 
-   If this is ``True``, :dir:`todo` and :dir:`todolist` produce output, else
+   If this is ``True``, :rst:dir:`todo` and :rst:dir:`todolist` produce output, else
    they produce nothing.  The default is ``False``.
diff --git a/doc/ext/tutorial.rst b/doc/ext/tutorial.rst
index c44748d2..de61e201 100644
--- a/doc/ext/tutorial.rst
+++ b/doc/ext/tutorial.rst
@@ -201,8 +201,7 @@ The ``todo`` directive function looks like this::
        def run(self):
            env = self.state.document.settings.env
 
-           targetid = "todo-%s" % env.index_num
-           env.index_num += 1
+           targetid = "todo-%d" % env.new_serialno('todo')
            targetnode = nodes.target('', '', ids=[targetid])
 
            ad = make_admonition(todo, self.name, [_('Todo')], self.options,
@@ -225,9 +224,10 @@ 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
-will be the anchor name) is generated by using ``env.index_num`` which is
-persistent between directive calls and therefore leads to unique target names.
-The target node is instantiated without any text (the first two arguments).
+will be the anchor name) is generated by using ``env.new_serialno`` which is
+returns a new integer directive on each call and therefore leads to unique
+target names.  The target node is instantiated without any text (the first two
+arguments).
 
 An admonition is created using a standard docutils function (wrapped in Sphinx
 for docutils cross-version compatibility).  The first argument gives the node
diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst
new file mode 100644
index 00000000..ba6c8f86
--- /dev/null
+++ b/doc/ext/viewcode.rst
@@ -0,0 +1,19 @@
+:mod:`sphinx.ext.viewcode` -- Add links to highlighted source code
+==================================================================
+
+.. module:: sphinx.ext.viewcode
+   :synopsis: Add links to a highlighted version of the source code.
+.. moduleauthor:: Georg Brandl
+
+.. versionadded:: 1.0
+
+
+This extension looks at your Python object descriptions (``.. class::``,
+``.. function::`` etc.) and tries to find the source files where the objects are
+contained.  When found, a separate HTML page will be output for each module with
+a highlighted version of the source code, and a link will be added to all object
+descriptions that leads to the source code of the described object.  A link back
+from the source to the description will also be inserted.
+
+There are currently no configuration values for this extension; you just need to
+add ``'sphinx.ext.viewcode'`` to your :confval:`extensions` value for it to work.
diff --git a/doc/extensions.rst b/doc/extensions.rst
index 0716e485..38927520 100644
--- a/doc/extensions.rst
+++ b/doc/extensions.rst
@@ -51,6 +51,8 @@ These extensions are built in and can be activated by respective entries in the
    ext/ifconfig
    ext/coverage
    ext/todo
+   ext/extlinks
+   ext/viewcode
 
 
 Third-party extensions
diff --git a/doc/faq.rst b/doc/faq.rst
index 54aef384..613283c5 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -16,7 +16,7 @@ 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.
+   the :rst:dir:`toctree` directive where you want to start numbering.
 
 ... customize the look of the built HTML files?
    Use themes, see :doc:`theming`.
@@ -24,6 +24,10 @@ How do I...
 ... add global substitutions or includes?
    Add them in the :confval:`rst_epilog` config value.
 
+... display the whole TOC tree in the sidebar?
+   Use the :data:`toctree` callable in a custom layout template, probably in the
+   ``sidebartoc`` block.
+
 ... write my own extension?
    See the :ref:`extension tutorial <exttut>`.
 
@@ -33,6 +37,8 @@ How do I...
    come through cleanly.
 
 
+.. _usingwith:
+
 Using Sphinx with...
 --------------------
 
@@ -48,6 +54,12 @@ SCons
    Glenn Hutchings has written a SCons build script to build Sphinx
    documentation; it is hosted here: http://bitbucket.org/zondo/sphinx-scons
 
+PyPI
+   Jannis Leidel wrote a `setuptools command
+   <http://pypi.python.org/pypi/Sphinx-PyPI-upload>`_ that automatically uploads
+   Sphinx documentation to the PyPI package documentation area at
+   http://packages.python.org/.
+
 github pages
    You can use `Michael Jones' sphinx-to-github tool
    <http://github.com/michaeljones/sphinx-to-github/tree/master>`_ to prepare
@@ -89,3 +101,40 @@ Google Analytics
 
 .. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
 .. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
+
+
+.. _epub-faq:
+
+Epub info
+---------
+
+The epub builder is currently in an experimental stage.  It has only been tested
+with the Sphinx documentation itself.  If you want to create epubs, here are
+some notes:
+
+* Split the text into several files. The longer the individual HTML files are,
+  the longer it takes the ebook reader to render them.  In extreme cases, the
+  rendering can take up to one minute.
+
+* Try to minimize the markup.  This also pays in rendering time.
+
+* For some readers you can use embedded or external fonts using the CSS
+  ``@font-face`` directive.  This is *extremely* useful for code listings which
+  are often cut at the right margin.  The default Courier font (or variant) is
+  quite wide and you can only display up to 60 characters on a line.  If you
+  replace it with a narrower font, you can get more characters on a line.  You
+  may even use `FontForge <http://fontforge.sourceforge.net/>`_ and create
+  narrow variants of some free font.  In my case I get up to 70 characters on a
+  line.
+
+  You may have to experiment a little until you get reasonable results.
+
+* Test the created epubs. You can use several alternatives.  The ones I am aware
+  of are Epubcheck_, Calibre_, FBreader_ (although it does not render the CSS),
+  and Bookworm_.  For bookworm you can download the source from
+  http://code.google.com/p/threepress/ and run your own local server.
+
+.. _Epubcheck: http://code.google.com/p/epubcheck/
+.. _Calibre: http://calibre-ebook.com/
+.. _FBreader: http://www.fbreader.org/
+.. _Bookworm: http://bookworm.oreilly.com/
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 7ec787ff..2a82e20f 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -19,10 +19,43 @@ Glossary
       the :term:`source directory`, but can be set differently with the **-c**
       command-line option.
 
-   description unit
-      The basic building block of Sphinx documentation.  Every "description
-      directive" (e.g. :dir:`function` or :dir:`describe`) creates such a unit;
-      and most units can be cross-referenced to.
+   directive
+      A reStructuredText markup element that allows marking a block of content
+      with special meaning.  Directives are supplied not only by docutils, but
+      Sphinx and custom extensions can add their own.  The basic directive
+      syntax looks like this::
+
+         .. directivename:: argument ...
+            :option: value
+
+            Content of the directive.
+
+      See :ref:`directives` for more information.
+
+   document name
+      Since reST source files can have different extensions (some people like
+      ``.txt``, some like ``.rst`` -- the extension can be configured with
+      :confval:`source_suffix`) and different OSes have different path separators,
+      Sphinx abstracts them: :dfn:`document names` are always relative to the
+      :term:`source directory`, the extension is stripped, and path separators
+      are converted to slashes.  All values, parameters and such referring to
+      "documents" expect such document names.
+
+      Examples for document names are ``index``, ``library/zipfile``, or
+      ``reference/datamodel/types``.  Note that there is no leading or trailing
+      slash.
+
+   domain
+      A domain is a collection of markup (reStructuredText :term:`directive`\ s
+      and :term:`role`\ s) to describe and link to :term:`object`\ s belonging
+      together, e.g. elements of a programming language.  Directive and role
+      names in a domain have names like ``domain:name``, e.g. ``py:function``.
+
+      Having domains means that there are no naming problems when one set of
+      documentation wants to refer to e.g. C++ and Python classes.  It also
+      means that extensions that support the documentation of whole new
+      languages are much easier to write.  For more information about domains,
+      see the chapter :ref:`domains`.
 
    environment
       A structure where information about all documents under the root is saved,
@@ -30,6 +63,19 @@ Glossary
       parsing stage, so that successive runs only need to read and parse new and
       changed documents.
 
+   master document
+      The document that contains the root :rst:dir:`toctree` directive.
+
+   object
+      The basic building block of Sphinx documentation.  Every "object
+      directive" (e.g. :rst:dir:`function` or :rst:dir:`object`) creates such a block;
+      and most objects can be cross-referenced to.
+
+   role
+      A reStructuredText markup element that allows marking a piece of text.
+      Like directives, roles are extensible.  The basic syntax looks like this:
+      ``:rolename:`content```.  See :ref:`inlinemarkup` for details.
+
    source directory
       The directory which, including its subdirectories, contains all source
       files for one Sphinx project.
diff --git a/doc/intro.rst b/doc/intro.rst
index 773bc74e..33f97a3f 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -8,12 +8,13 @@ you have a directory containing a bunch of reST-formatted documents (and
 possibly subdirectories of docs in there as well), Sphinx can generate a
 nicely-organized arrangement of HTML files (in some other directory) for easy
 browsing and navigation.  But from the same source, it can also generate a
-LaTeX file that you can compile into a PDF version of the documents.
+LaTeX file that you can compile into a PDF version of the documents, or a
+PDF file directly using `rst2pdf <http://rst2pdf.googlecode.com>`_.
 
 The focus is on hand-written documentation, rather than auto-generated API docs.
-Though there is limited support for that kind of docs as well (which is intended
-to be freely mixed with hand-written content), if you need pure API docs have a
-look at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST.
+Though there is support for that kind of docs as well (which is intended to be
+freely mixed with hand-written content), if you need pure API docs have a look
+at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST.
 
 
 Conversion from other systems
@@ -35,6 +36,12 @@ to reStructuredText/Sphinx from other documentation systems.
   markup; it is at `Google Code <http://code.google.com/p/db2rst/>`_.
 
 
+Use with other systems
+----------------------
+
+See the :ref:`pertinent section in the FAQ list <usingwith>`.
+
+
 Prerequisites
 -------------
 
@@ -47,113 +54,8 @@ or some (not broken) SVN trunk snapshot.
 .. _Pygments: http://pygments.org
 
 
-Setting up the documentation sources
-------------------------------------
-
-The root directory of a documentation collection is called the :dfn:`source
-directory`.  Normally, this directory also contains the Sphinx configuration
-file :file:`conf.py`, but that file can also live in another directory, the
-:dfn:`configuration directory`.
-
-.. versionadded:: 0.3
-   Support for a different configuration directory.
-
-Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
-source directory and creates a default :file:`conf.py` from a few questions it
-asks you.  Just run ::
-
-   $ sphinx-quickstart
-
-and answer the questions.
-
-
-Running a build
----------------
-
-A build is started with the :program:`sphinx-build` script.  It is called
-like this::
-
-     $ sphinx-build -b latex sourcedir builddir
-
-where *sourcedir* is the :term:`source directory`, and *builddir* is the
-directory in which you want to place the built documentation (it must be an
-existing directory).  The :option:`-b` option selects a builder; in this example
-Sphinx will build LaTeX files.
-
-The :program:`sphinx-build` script has several more options:
-
-**-a**
-   If given, always write all output files.  The default is to only write output
-   files for new and changed source files.  (This may not apply to all
-   builders.)
-
-**-E**
-   Don't use a saved :term:`environment` (the structure caching all
-   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".
-   Normally, these files are put in a directory called :file:`.doctrees` under
-   the build directory; with this option you can select a different cache
-   directory (the doctrees can be shared between all builders).
-
-**-c** *path*
-   Don't look for the :file:`conf.py` in the source directory, but use the given
-   configuration directory instead.  Note that various other files and paths
-   given by configuration values are expected to be relative to the
-   configuration directory, so they will have to be present at this location
-   too.
-
-   .. versionadded:: 0.3
-
-**-C**
-   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 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.
-
-**-N**
-   Do not do colored output.  (On Windows, colored output is disabled in any
-   case.)
-
-**-q**
-   Do not output anything on standard output, only write warnings and errors to
-   standard error.
-
-**-Q**
-   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.
-
+Usage
+-----
 
-You can also give one or more filenames on the command line after the source and
-build directories.  Sphinx will then try to build only these output files (and
-their dependencies).
+See :doc:`tutorial` for an introduction.  It also contains links to more
+advanced sections in this manual for the topics it discusses.
diff --git a/doc/invocation.rst b/doc/invocation.rst
new file mode 100644
index 00000000..6b8b9ee3
--- /dev/null
+++ b/doc/invocation.rst
@@ -0,0 +1,178 @@
+.. _invocation:
+
+Invocation of sphinx-build
+==========================
+
+The :program:`sphinx-build` script builds a Sphinx documentation set.  It is
+called like this::
+
+     $ sphinx-build [options] sourcedir builddir [filenames]
+
+where *sourcedir* is the :term:`source directory`, and *builddir* is the
+directory in which you want to place the built documentation.  Most of the time,
+you don't need to specify any *filenames*.
+
+The :program:`sphinx-build` script has several options:
+
+.. option:: -b buildername
+
+   The most important option: it selects a builder.  The most common builders
+   are:
+
+   **html**
+      Build HTML pages.  This is the default builder.
+
+   **dirhtml**
+      Build HTML pages, but with a single directory per document.  Makes for
+      prettier URLs (no ``.html``) if served from a webserver.
+
+   **singlehtml**
+      Build a single HTML with the whole content.
+
+   **htmlhelp**, **qthelp**, **devhelp**, **epub**
+      Build HTML files with additional information for building a documentation
+      collection in one of these formats.
+
+   **latex**
+      Build LaTeX sources that can be compiled to a PDF document using
+      :program:`pdflatex`.
+
+   **man**
+      Build manual pages in groff format for UNIX systems.
+
+   **text**
+      Build plain text files.
+
+   **doctest**
+      Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
+      extension is enabled.
+
+   **linkcheck**
+      Check the integrity of all external links.
+
+   See :ref:`builders` for a list of all builders shipped with Sphinx.
+   Extensions can add their own builders.
+
+.. option:: -a
+
+   If given, always write all output files.  The default is to only write output
+   files for new and changed source files.  (This may not apply to all
+   builders.)
+
+.. option:: -E
+
+   Don't use a saved :term:`environment` (the structure caching all
+   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.
+
+.. option:: -t tag
+
+   Define the tag *tag*.  This is relevant for :rst:dir:`only` directives that only
+   include their content if this tag is set.
+
+   .. versionadded:: 0.6
+
+.. option:: -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".
+   Normally, these files are put in a directory called :file:`.doctrees` under
+   the build directory; with this option you can select a different cache
+   directory (the doctrees can be shared between all builders).
+
+.. option:: -c path
+
+   Don't look for the :file:`conf.py` in the source directory, but use the given
+   configuration directory instead.  Note that various other files and paths
+   given by configuration values are expected to be relative to the
+   configuration directory, so they will have to be present at this location
+   too.
+
+   .. versionadded:: 0.3
+
+.. option:: -C
+
+   Don't look for a configuration file; only take options via the ``-D`` option.
+
+   .. versionadded:: 0.5
+
+.. option:: -D setting=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``.  For boolean
+   values, use ``0`` or ``1`` as the value.
+
+   .. versionchanged:: 0.6
+      The value can now be a dictionary value.
+
+.. option:: -A name=value
+
+   Make the *name* assigned to *value* in the HTML templates.
+
+   .. versionadded:: 0.5
+
+.. option:: -n
+
+   Run in nit-picky mode.  Currently, this generates warnings for all missing
+   references.
+
+.. option:: -N
+
+   Do not emit colored output.  (On Windows, colored output is disabled in any
+   case.)
+
+.. option:: -q
+
+   Do not output anything on standard output, only write warnings and errors to
+   standard error.
+
+.. option:: -Q
+
+   Do not output anything on standard output, also suppress warnings.  Only
+   errors are written to standard error.
+
+.. option:: -w file
+
+   Write warnings (and errors) to the given file, in addition to standard error.
+
+.. option:: -W
+
+   Turn warnings into errors.  This means that the build stops at the first
+   warning and ``sphinx-build`` exits with exit status 1.
+
+.. option:: -P
+
+   (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
+   unhandled exception occurs while building.
+
+
+You can also give one or more filenames on the command line after the source and
+build directories.  Sphinx will then try to build only these output files (and
+their dependencies).
+
+
+Makefile options
+----------------
+
+The :file:`Makefile` and :file:`make.bat` files created by
+:program:`sphinx-quickstart` usually run :program:`sphinx-build` only with the
+:option:`-b` and :option:`-d` options.  However, they support the following
+variables to customize behavior:
+
+.. describe:: PAPER
+
+   The value for :confval:`latex_paper_size`.
+
+.. describe:: SPHINXBUILD
+
+   The command to use instead of ``sphinx-build``.
+
+.. describe:: BUILDDIR
+
+   The build directory to use instead of the one chosen in
+   :program:`sphinx-quickstart`.
+
+.. describe:: SPHINXOPTS
+
+   Additional options for :program:`sphinx-build`.
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst
new file mode 100644
index 00000000..30f824e8
--- /dev/null
+++ b/doc/man/sphinx-build.rst
@@ -0,0 +1,102 @@
+:orphan:
+
+sphinx-build manual page
+========================
+
+Synopsis
+--------
+
+**sphinx-build** [*options*] <*sourcedir*> <*outdir*> [*filenames* ...]
+
+
+Description
+-----------
+
+:program:`sphinx-build` generates documentation from the files in
+``<sourcedir>`` and places it in the ``<outdir>``.
+
+:program:`sphinx-build` looks for ``<sourcedir>/conf.py`` for the configuration
+settings.  :manpage:`sphinx-quickstart(1)` may be used to generate template
+files, including ``conf.py``.
+
+:program:`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:
+
+html
+   HTML file generation.  This is the default builder.
+
+htmlhelp
+   Generates files for CHM (compiled help files) generation.
+
+qthelp
+   Generates files for Qt help collection generation.
+
+devhelp
+   Generates files for the GNOME Devhelp help viewer.
+
+latex
+   Generates LaTeX output that can be compiled to a PDF document.
+
+man
+   Generates manual pages.
+
+text
+   Generates a plain-text version of the documentation.
+
+changes
+   Generates HTML files listing changed/added/deprecated items for
+   the current version of the documented project.
+
+linkcheck
+   Checks the integrity of all external links in the source.
+
+pickle / json
+   Generates serialized HTML files for use in web applications.
+
+
+Options
+-------
+
+-b <builder>          Builder to use; defaults to html. See the full list
+                      of builders above.
+-a                    Generate output for all files; without this option only
+                      output for new and changed files is generated.
+-E                    Ignore cached files, forces to re-read all source files
+                      from disk.
+-c <path>             Locate the conf.py file in the specified path instead of
+                      <sourcedir>.
+-C                    Specify that no conf.py file at all is to be used.
+                      Configuration can only be set with the -D option.
+-D <setting=value>    Override a setting from the configuration file.
+-d <path>             Path to cached files; defaults to <outdir>/.doctrees.
+-A <name=value>       Pass a value into the HTML templates (only for HTML builders).
+-n                    Run in nit-picky mode, warn about all missing references.
+-N                    Prevent colored output.
+-q                    Quiet operation, just print warnings and errors on stderr.
+-Q                    Very quiet operation, don't print anything except for errors.
+-w <file>             Write warnings and errors into the given file, in addition
+                      to stderr.
+-W                    Turn warnings into errors.
+-P                    Run Pdb on exception.
+
+
+See also
+--------
+
+:manpage:`sphinx-quickstart(1)`
+
+Author
+------
+
+Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
+al.
+
+This manual page was initially written by Mikhail Gusarov
+<dottedmag@dottedmag.net>, for the Debian project.
diff --git a/doc/man/sphinx-quickstart.rst b/doc/man/sphinx-quickstart.rst
new file mode 100644
index 00000000..17277261
--- /dev/null
+++ b/doc/man/sphinx-quickstart.rst
@@ -0,0 +1,33 @@
+:orphan:
+
+sphinx-quickstart manual page
+=============================
+
+Synopsis
+--------
+
+**sphinx-quickstart**
+
+
+Description
+-----------
+
+:program:`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 :manpage:`sphinx-build(1)`.
+
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`
+
+
+Author
+------
+
+Georg Brandl <georg@python.org>, Armin Ronacher <armin.ronacher@active-4.com> et
+al.
+
+This manual page was initially written by Mikhail Gusarov
+<dottedmag@dottedmag.net>, for the Debian project.
diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index 93cd127b..eaaf17d0 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -43,14 +43,14 @@ installed) and handled in a smart way:
   This language is used until the next ``highlight`` directive is encountered.
 
 * For documents that have to show snippets in different languages, there's also
-  a :dir:`code-block` directive that is given the highlighting language
+  a :rst:dir:`code-block` directive that is given the highlighting language
   directly::
 
      .. code-block:: ruby
 
         Some Ruby code.
 
-  The directive's alias name :dir:`sourcecode` works as well.
+  The directive's alias name :rst:dir:`sourcecode` works as well.
 
 * The valid values for the highlighting language are:
 
@@ -70,7 +70,7 @@ Line numbers
 
 If installed, Pygments can generate line numbers for code blocks.  For
 automatically-highlighted blocks (those started by ``::``), line numbers must be
-switched on in a :dir:`highlight` directive, with the ``linenothreshold``
+switched on in a :rst:dir:`highlight` directive, with the ``linenothreshold``
 option::
 
    .. highlight:: python
@@ -78,7 +78,7 @@ option::
 
 This will produce line numbers for all code blocks longer than five lines.
 
-For :dir:`code-block` blocks, a ``linenos`` flag option can be given to switch
+For :rst:dir:`code-block` blocks, a ``linenos`` flag option can be given to switch
 on line numbers for the individual block::
 
    .. code-block:: ruby
@@ -90,7 +90,7 @@ on line numbers for the individual block::
 Includes
 ^^^^^^^^
 
-.. directive:: .. literalinclude:: filename
+.. rst:directive:: .. literalinclude:: filename
 
    Longer displays of verbatim text may be included by storing the example text in
    an external file containing only plain text.  The file may be included using the
@@ -103,6 +103,9 @@ Includes
    is absolute (starting with ``/``), it is relative to the top source
    directory.
 
+   Tabs in the input are expanded if you give a ``tab-width`` option with the
+   desired tab width.
+
    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::
@@ -143,11 +146,17 @@ Includes
    string option, only lines that precede the first lines containing that string
    are included.
 
+   You can prepend and/or append a line to the included code, using the
+   ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
+   highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
+
    .. versionadded:: 0.4.3
       The ``encoding`` option.
    .. versionadded:: 0.6
       The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options,
       as well as support for absolute filenames.
+   .. versionadded:: 1.0
+      The ``prepend`` and ``append`` options, as well as ``tab-width``.
 
 
 .. rubric:: Footnotes
diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst
deleted file mode 100644
index ec8ede37..00000000
--- a/doc/markup/desc.rst
+++ /dev/null
@@ -1,357 +0,0 @@
-.. highlight:: rest
-
-Module-specific markup
-----------------------
-
-The markup described in this section is used to provide information about a
-module being documented.  Normally this markup appears after a title heading; a
-typical module section might start like this::
-
-   :mod:`parrot` -- Dead parrot access
-   ===================================
-
-   .. module:: parrot
-      :platform: Unix, Windows
-      :synopsis: Analyze and reanimate dead parrots.
-   .. moduleauthor:: Eric Cleese <eric@python.invalid>
-   .. moduleauthor:: John Idle <john@python.invalid>
-
-
-The directives you can use for module declarations are:
-
-.. directive:: .. module:: name
-
-   This directive marks the beginning of the description of a module (or package
-   submodule, in which case the name should be fully qualified, including the
-   package name).  It does not create content (like e.g. :dir:`class` does).
-
-   This directive will also cause an entry in the global module index.
-
-   The ``platform`` option, if present, is a comma-separated list of the
-   platforms on which the module is available (if it is available on all
-   platforms, the option should be omitted).  The keys are short identifiers;
-   examples that are in use include "IRIX", "Mac", "Windows", and "Unix".  It is
-   important to use a key which has already been used when applicable.
-
-   The ``synopsis`` option should consist of one sentence describing the
-   module's purpose -- it is currently only used in the Global Module Index.
-
-   The ``deprecated`` option can be given (with no value) to mark a module as
-   deprecated; it will be designated as such in various locations then.
-
-
-.. directive:: .. currentmodule:: name
-
-   This directive tells Sphinx that the classes, functions etc. documented from
-   here are in the given module (like :dir:`module`), but it will not create
-   index entries, an entry in the Global Module Index, or a link target for
-   :role:`mod`.  This is helpful in situations where documentation for things in
-   a module is spread over multiple files or sections -- one location has the
-   :dir:`module` directive, the others only :dir:`currentmodule`.
-
-
-.. directive:: .. moduleauthor:: name <email>
-
-   The ``moduleauthor`` directive, which can appear multiple times, names the
-   authors of the module code, just like ``sectionauthor`` names the author(s)
-   of a piece of documentation.  It too only produces output if the
-   :confval:`show_authors` configuration value is True.
-
-
-.. note::
-
-   It is important to make the section title of a module-describing file
-   meaningful since that value will be inserted in the table-of-contents trees
-   in overview files.
-
-
-.. _desc-units:
-
-Object description units
-------------------------
-
-There are a number of directives used to describe specific features provided by
-modules.  Each directive requires one or more signatures to provide basic
-information about what is being described, and the content should be the
-description.  The basic version makes entries in the general index; if no index
-entry is desired, you can give the directive option flag ``:noindex:``.  The
-following example shows all of the features of this directive type::
-
-    .. function:: spam(eggs)
-                  ham(eggs)
-       :noindex:
-
-       Spam or ham the foo.
-
-The signatures of object methods or data attributes should always include the
-type name (``.. method:: FileInput.input(...)``), even if it is obvious from the
-context which type they belong to; this is to enable consistent
-cross-references.  If you describe methods belonging to an abstract protocol,
-such as "context managers", include a (pseudo-)type name too to make the
-index entries more informative.
-
-The directives are:
-
-.. directive:: .. cfunction:: type name(signature)
-
-   Describes a C function. The signature should be given as in C, e.g.::
-
-      .. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
-
-   This is also used to describe function-like preprocessor macros.  The names
-   of the arguments should be given so they may be used in the description.
-
-   Note that you don't have to backslash-escape asterisks in the signature,
-   as it is not parsed by the reST inliner.
-
-.. directive:: .. cmember:: type name
-
-   Describes a C struct member. Example signature::
-
-      .. cmember:: PyObject* PyTypeObject.tp_bases
-
-   The text of the description should include the range of values allowed, how
-   the value should be interpreted, and whether the value can be changed.
-   References to structure members in text should use the ``member`` role.
-
-.. directive:: .. cmacro:: name
-
-   Describes a "simple" C macro.  Simple macros are macros which are used
-   for code expansion, but which do not take arguments so cannot be described as
-   functions.  This is not to be used for simple constant definitions.  Examples
-   of its use in the Python documentation include :cmacro:`PyObject_HEAD` and
-   :cmacro:`Py_BEGIN_ALLOW_THREADS`.
-
-.. directive:: .. ctype:: name
-
-   Describes a C type. The signature should just be the type name.
-
-.. directive:: .. cvar:: type name
-
-   Describes a global C variable.  The signature should include the type, such
-   as::
-
-      .. cvar:: PyObject* PyClass_Type
-
-.. directive:: .. data:: name
-
-   Describes global data in a module, including both variables and values used
-   as "defined constants."  Class and object attributes are not documented
-   using this environment.
-
-.. directive:: .. exception:: name
-
-   Describes an exception class.  The signature can, but need not include
-   parentheses with constructor arguments.
-
-.. directive:: .. function:: name(signature)
-
-   Describes a module-level function.  The signature should include the
-   parameters, enclosing optional parameters in brackets.  Default values can be
-   given if it enhances clarity; see :ref:`signatures`.  For example::
-
-      .. function:: Timer.repeat([repeat=3[, number=1000000]])
-
-   Object methods are not documented using this directive. Bound object methods
-   placed in the module namespace as part of the public interface of the module
-   are documented using this, as they are equivalent to normal functions for
-   most purposes.
-
-   The description should include information about the parameters required and
-   how they are used (especially whether mutable objects passed as parameters
-   are modified), side effects, and possible exceptions.  A small example may be
-   provided.
-
-.. directive:: .. class:: name[(signature)]
-
-   Describes a class.  The signature can include parentheses with parameters
-   which will be shown as the constructor arguments.  See also
-   :ref:`signatures`.
-
-   Methods and attributes belonging to the class should be placed in this
-   directive's body.  If they are placed outside, the supplied name should
-   contain the class name so that cross-references still work.  Example::
-
-      .. class:: Foo
-         .. method:: quux()
-
-      -- or --
-
-      .. class:: Bar
-
-      .. method:: Bar.quux()
-
-   The first way is the preferred one.
-
-   .. versionadded:: 0.4
-      The standard reST directive ``class`` is now provided by Sphinx under
-      the name ``cssclass``.
-
-.. directive:: .. attribute:: name
-
-   Describes an object data attribute.  The description should include
-   information about the type of the data to be expected and whether it may be
-   changed directly.
-
-.. directive:: .. method:: name(signature)
-
-   Describes an object method.  The parameters should not include the ``self``
-   parameter.  The description should include similar information to that
-   described for ``function``.  See also :ref:`signatures`.
-
-.. directive:: .. staticmethod:: name(signature)
-
-   Like :dir:`method`, but indicates that the method is a static method.
-
-   .. versionadded:: 0.4
-
-.. directive:: .. classmethod:: name(signature)
-
-   Like :dir:`method`, but indicates that the method is a class method.
-
-   .. versionadded:: 0.6
-
-
-.. _signatures:
-
-Signatures
-~~~~~~~~~~
-
-Signatures of functions, methods and class constructors can be given like they
-would be written in Python, with the exception that optional parameters can be
-indicated by brackets::
-
-   .. function:: compile(source[, filename[, symbol]])
-
-It is customary to put the opening bracket before the comma.  In addition to
-this "nested" bracket style, a "flat" style can also be used, due to the fact
-that most optional parameters can be given independently::
-
-   .. function:: compile(source[, filename, symbol])
-
-Default values for optional arguments can be given (but if they contain commas,
-they will confuse the signature parser).  Python 3-style argument annotations
-can also be given as well as return type annotations::
-
-   .. function:: compile(source : string[, filename, symbol]) -> ast object
-
-
-Info field lists
-~~~~~~~~~~~~~~~~
-
-.. versionadded:: 0.4
-
-Inside description unit directives, reST field lists with these fields are
-recognized and formatted nicely:
-
-* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
-  Description of a parameter.
-* ``type``: Type of a parameter.
-* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific
-  exception is raised.
-* ``var``, ``ivar``, ``cvar``: Description of a variable.
-* ``returns``, ``return``: Description of the return value.
-* ``rtype``: Return type.
-
-The field names must consist of one of these keywords and an argument (except
-for ``returns`` and ``rtype``, which do not need an argument).  This is best
-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
-      :param limit: maximum number of stack frames to show
-      :type limit: integer or None
-      :rtype: list of strings
-
-This will render like this:
-
-   .. function:: format_exception(etype, value, tb[, limit=None])
-      :noindex:
-
-      Format the exception with a traceback.
-
-      :param etype: exception type
-      :param value: exception value
-      :param tb: traceback object
-      :param limit: maximum number of stack frames to show
-      :type limit: integer or None
-      :rtype: list of strings
-
-
-Command-line program markup
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There is a set of directives allowing documenting command-line programs:
-
-.. directive:: .. cmdoption:: name args, name args, ...
-
-   Describes a command line option or switch.  Option argument names should be
-   enclosed in angle brackets.  Example::
-
-      .. cmdoption:: -m <module>, --module <module>
-
-         Run a module as a script.
-
-   The directive will create a cross-reference target named after the *first*
-   option, referencable by :role:`option` (in the example case, you'd use
-   something like ``:option:`-m```).
-
-.. directive:: .. envvar:: name
-
-   Describes an environment variable that the documented code or program uses or
-   defines.
-
-
-.. directive:: .. program:: name
-
-   Like :dir:`currentmodule`, this directive produces no output.  Instead, it
-   serves to notify Sphinx that all following :dir:`cmdoption` directives
-   document options for the program called *name*.
-
-   If you use :dir:`program`, you have to qualify the references in your
-   :role:`option` roles by the program name, so if you have the following
-   situation ::
-
-      .. program:: rm
-
-      .. cmdoption:: -r
-
-         Work recursively.
-
-      .. program:: svn
-
-      .. cmdoption:: -r revision
-
-         Specify the revision to work upon.
-
-   then ``:option:`rm -r``` would refer to the first option, while
-   ``:option:`svn -r``` would refer to the second one.
-
-   The program name may contain spaces (in case you want to document subcommands
-   like ``svn add`` and ``svn commit`` separately).
-
-   .. versionadded:: 0.5
-
-
-Custom description units
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-There is also a generic version of these directives:
-
-.. directive:: .. describe:: text
-
-   This directive produces the same formatting as the specific ones explained
-   above but does not create index entries or cross-referencing targets.  It is
-   used, for example, to describe the directives in this document. Example::
-
-      .. describe:: opcode
-
-         Describes a Python bytecode instruction.
-
-Extensions may add more directives like that, using the
-:func:`~sphinx.application.Sphinx.add_description_unit` method.
diff --git a/doc/markup/index.rst b/doc/markup/index.rst
index 1127fa73..9492456d 100644
--- a/doc/markup/index.rst
+++ b/doc/markup/index.rst
@@ -1,3 +1,5 @@
+.. _sphinxmarkup:
+
 Sphinx Markup Constructs
 ========================
 
@@ -6,8 +8,10 @@ markup.  This section contains the reference material for these facilities.
 
 .. toctree::
 
-   desc
+   toctree
    para
    code
    inline
    misc
+
+More markup is added by :ref:`domains`.
diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index 9b4b26e3..558f813d 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -1,5 +1,7 @@
 .. highlight:: rest
 
+.. _inline-markup:
+
 Inline markup
 =============
 
@@ -12,11 +14,13 @@ They are written as ``:rolename:`content```.
    free to use it for anything you like, e.g. variable names; use the
    :confval:`default_role` config value to set it to a known role.
 
+See :ref:`domains` for roles added by domains.
+
 
 .. _xref-syntax:
 
 Cross-referencing syntax
-------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 Cross-references are generated by many semantic interpreted text roles.
 Basically, you only need to write ``:role:`target```, and a link will be created
@@ -32,195 +36,60 @@ more versatile:
 
 * If you prefix the content with ``!``, no reference/hyperlink will be created.
 
-* For the Python object roles, if you prefix the content with ``~``, the link
-  text will only be the last component of the target.  For example,
-  ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only
-  display ``get`` as the link text.
+* If you prefix the content with ``~``, the link text will only be the last
+  component of the target.  For example, ``:py:meth:`~Queue.Queue.get``` will
+  refer to ``Queue.Queue.get`` but only display ``get`` as the link text.
 
   In HTML output, the link's ``title`` attribute (that is e.g. shown as a
   tool-tip on mouse-hover) will always be the full target name.
 
 
-Cross-referencing Python objects
---------------------------------
-
-The following roles refer to objects in modules and are possibly hyperlinked if
-a matching identifier is found:
-
-.. role:: mod
-
-   The name of a module; a dotted name may be used.  This should also be used for
-   package names.
-
-.. role:: func
-
-   The name of a Python function; dotted names may be used.  The role text
-   needs not include trailing parentheses to enhance readability; they will be
-   added automatically by Sphinx if the :confval:`add_function_parentheses`
-   config value is true (the default).
-
-.. role:: data
-
-   The name of a module-level variable.
-
-.. role:: const
-
-   The name of a "defined" constant.  This may be a C-language ``#define``
-   or a Python variable that is not intended to be changed.
-
-.. role:: class
-
-   A class name; a dotted name may be used.
-
-.. role:: meth
-
-   The name of a method of an object.  The role text should include the type
-   name and the method name; if it occurs within the description of a type,
-   the type name can be omitted.  A dotted name may be used.
-
-.. role:: attr
-
-   The name of a data attribute of an object.
-
-.. role:: exc
-
-   The name of an exception. A dotted name may be used.
-
-.. role:: obj
-
-   The name of an object of unspecified type.  Useful e.g. as the
-   :confval:`default_role`.
-
-   .. versionadded:: 0.4
-
-The name enclosed in this markup can include a module name and/or a class name.
-For example, ``:func:`filter``` could refer to a function named ``filter`` in
-the current module, or the built-in function of that name.  In contrast,
-``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
-module.
-
-Normally, names in these roles are searched first without any further
-qualification, then with the current module name prepended, then with the
-current module and class name (if any) prepended.  If you prefix the name with a
-dot, this order is reversed.  For example, in the documentation of Python's
-:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
-while ``:func:`.open``` refers to :func:`codecs.open`.
-
-A similar heuristic is used to determine whether the name is an attribute of
-the currently documented class.
-
-
-Cross-referencing C constructs
-------------------------------
-
-The following roles create cross-references to C-language constructs if they
-are defined in the documentation:
-
-.. role:: cdata
-
-   The name of a C-language variable.
-
-.. role:: cfunc
-
-   The name of a C-language function. Should include trailing parentheses.
-
-.. role:: cmacro
-
-   The name of a "simple" C macro, as defined above.
-
-.. role:: ctype
-
-   The name of a C-language type.
-
-
-Cross-referencing other items of interest
------------------------------------------
-
-The following roles do possibly create a cross-reference, but do not refer to
-objects:
-
-.. role:: envvar
-
-   An environment variable.  Index entries are generated.  Also generates a link
-   to the matching :dir:`envvar` directive, if it exists.
-
-.. role:: token
-
-   The name of a grammar token (used to create links between
-   :dir:`productionlist` directives).
-
-.. role:: keyword
-
-   The name of a keyword in Python.  This creates a link to a reference label
-   with that name, if it exists.
-
-.. role:: option
-
-   A command-line option to an executable program.  The leading hyphen(s) must
-   be included.  This generates a link to a :dir:`cmdoption` directive, if it
-   exists.
-
-
-The following role creates a cross-reference to the term in the glossary:
-
-.. role:: term
-
-   Reference to a term in the glossary.  The glossary is created using the
-   ``glossary`` directive containing a definition list with terms and
-   definitions.  It does not have to be in the same file as the ``term`` markup,
-   for example the Python docs have one global glossary in the ``glossary.rst``
-   file.
-
-   If you use a term that's not explained in a glossary, you'll get a warning
-   during build.
-
-
 .. _ref-role:
 
 Cross-referencing arbitrary locations
 -------------------------------------
 
-.. index:: pair: ref; role
+.. rst:role:: ref
 
-To support cross-referencing to arbitrary locations in any document, the
-standard reST labels are used.  For this to work label names must be unique
-throughout the entire documentation.  There are two ways in which you can refer
-to labels:
+   To support cross-referencing to arbitrary locations in any document, the
+   standard reST labels are used.  For this to work label names must be unique
+   throughout the entire documentation.  There are two ways in which you can
+   refer to labels:
 
-* If you place a label directly before a section title, you can reference to it
-  with ``:ref:`label-name```.  Example::
+   * If you place a label directly before a section title, you can reference to
+     it with ``:ref:`label-name```.  Example::
 
-     .. _my-reference-label:
+        .. _my-reference-label:
 
-     Section to cross-reference
-     --------------------------
+        Section to cross-reference
+        --------------------------
 
-     This is the text of the section.
+        This is the text of the section.
 
-     It refers to the section itself, see :ref:`my-reference-label`.
+        It refers to the section itself, see :ref:`my-reference-label`.
 
-  The ``:ref:`` role would then generate a link to the section, with the link
-  title being "Section to cross-reference".  This works just as well when
-  section and reference are in different source files.
+     The ``:ref:`` role would then generate a link to the section, with the link
+     title being "Section to cross-reference".  This works just as well when
+     section and reference are in different source files.
 
-  Automatic labels also work with figures: given ::
+     Automatic labels also work with figures: given ::
 
-     .. _my-figure:
+        .. _my-figure:
 
-     .. figure:: whatever
+        .. figure:: whatever
 
-        Figure caption
+           Figure caption
 
-  a reference ``:ref:`my-figure``` would insert a reference to the figure with
-  link text "Figure caption".
+     a reference ``:ref:`my-figure``` would insert a reference to the figure
+     with link text "Figure caption".
 
-* Labels that aren't placed before a section title can still be referenced to,
-  but you must give the link an explicit title, using this syntax: ``:ref:`Link
-  title <label-name>```.
+   * Labels that aren't placed before a section title can still be referenced
+     to, but you must give the link an explicit title, using this syntax:
+     ``:ref:`Link title <label-name>```.
 
-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.
+   Using :rst: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
@@ -230,7 +99,7 @@ Cross-referencing documents
 
 There is also a way to directly link to documents:
 
-.. role:: doc
+.. rst:role:: doc
 
    Link to the specified document; the document name can be specified in
    absolute or relative fashion.  For example, if the reference
@@ -247,7 +116,7 @@ Referencing downloadable files
 
 .. versionadded:: 0.6
 
-.. role:: download
+.. rst: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.
@@ -275,7 +144,7 @@ Other semantic markup
 The following roles don't do anything special except formatting the text
 in a different style:
 
-.. role:: abbr
+.. rst: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
@@ -285,16 +154,16 @@ in a different style:
 
    .. versionadded:: 0.6
 
-.. role:: command
+.. rst:role:: command
 
    The name of an OS-level command, such as ``rm``.
 
-.. role:: dfn
+.. rst:role:: dfn
 
    Mark the defining instance of a term in the text.  (No index entries are
    generated.)
 
-.. role:: file
+.. rst:role:: file
 
    The name of a file or directory.  Within the contents, you can use curly
    braces to indicate a "variable" part, for example::
@@ -304,7 +173,7 @@ in a different style:
    In the built documentation, the ``x`` will be displayed differently to
    indicate that it is to be replaced by the Python minor version.
 
-.. role:: guilabel
+.. rst:role:: guilabel
 
    Labels presented as part of an interactive user interface should be marked
    using ``guilabel``.  This includes labels from text-based interfaces such as
@@ -313,7 +182,7 @@ in a different style:
    labels, window titles, field names, menu and menu selection names, and even
    values in selection lists.
 
-.. role:: kbd
+.. rst:role:: kbd
 
    Mark a sequence of keystrokes.  What form the key sequence takes may depend
    on platform- or application-specific conventions.  When there are no relevant
@@ -323,7 +192,7 @@ in a different style:
    reference to a specific application or platform, the same sequence should be
    marked as ``:kbd:`Control-x Control-f```.
 
-.. role:: mailheader
+.. rst:role:: mailheader
 
    The name of an RFC 822-style mail header.  This markup does not imply that
    the header is being used in an email message, but can be used to refer to any
@@ -333,16 +202,16 @@ in a different style:
    being preferred where there is more than one common usage. For example:
    ``:mailheader:`Content-Type```.
 
-.. role:: makevar
+.. rst:role:: makevar
 
    The name of a :command:`make` variable.
 
-.. role:: manpage
+.. rst:role:: manpage
 
    A reference to a Unix manual page including the section,
    e.g. ``:manpage:`ls(1)```.
 
-.. role:: menuselection
+.. rst:role:: menuselection
 
    Menu selections should be marked using the ``menuselection`` role.  This is
    used to mark a complete sequence of menu selections, including selecting
@@ -358,26 +227,26 @@ in a different style:
    ellipsis some operating systems use to indicate that the command opens a
    dialog, the indicator should be omitted from the selection name.
 
-.. role:: mimetype
+.. rst:role:: mimetype
 
    The name of a MIME type, or a component of a MIME type (the major or minor
    portion, taken alone).
 
-.. role:: newsgroup
+.. rst:role:: newsgroup
 
    The name of a Usenet newsgroup.
 
-.. role:: program
+.. rst:role:: program
 
    The name of an executable program.  This may differ from the file name for
    the executable for some platforms.  In particular, the ``.exe`` (or other)
    extension should be omitted for Windows programs.
 
-.. role:: regexp
+.. rst:role:: regexp
 
    A regular expression. Quotes should not be included.
 
-.. role:: samp
+.. rst:role:: samp
 
    A piece of literal text, such as code.  Within the contents, you can use
    curly braces to indicate a "variable" part, as in ``:file:``.
@@ -388,13 +257,13 @@ in a different style:
 
 The following roles generate external links:
 
-.. role:: pep
+.. rst:role:: pep
 
    A reference to a Python Enhancement Proposal.  This generates appropriate
    index entries. The text "PEP *number*\ " is generated; in the HTML output,
    this text is a hyperlink to an online copy of the specified PEP.
 
-.. role:: rfc
+.. rst:role:: rfc
 
    A reference to an Internet Request for Comments.  This generates appropriate
    index entries. The text "RFC *number*\ " is generated; in the HTML output,
@@ -405,6 +274,48 @@ Note that there are no special roles for including hyperlinks as you can use
 the standard reST markup for that purpose.
 
 
+Cross-referencing other items of interest
+-----------------------------------------
+
+The following roles do possibly create a cross-reference, but do not refer to
+objects:
+
+.. rst:role:: envvar
+
+   An environment variable.  Index entries are generated.  Also generates a link
+   to the matching :rst:dir:`envvar` directive, if it exists.
+
+.. rst:role:: token
+
+   The name of a grammar token (used to create links between
+   :rst:dir:`productionlist` directives).
+
+.. rst:role:: keyword
+
+   The name of a keyword in Python.  This creates a link to a reference label
+   with that name, if it exists.
+
+.. rst:role:: option
+
+   A command-line option to an executable program.  The leading hyphen(s) must
+   be included.  This generates a link to a :rst:dir:`option` directive, if it
+   exists.
+
+
+The following role creates a cross-reference to the term in the glossary:
+
+.. rst:role:: term
+
+   Reference to a term in the glossary.  The glossary is created using the
+   ``glossary`` directive containing a definition list with terms and
+   definitions.  It does not have to be in the same file as the ``term`` markup,
+   for example the Python docs have one global glossary in the ``glossary.rst``
+   file.
+
+   If you use a term that's not explained in a glossary, you'll get a warning
+   during build.
+
+
 .. _default-substitutions:
 
 Substitutions
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index 01e5a3f1..6173589b 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -11,12 +11,12 @@ File-wide metadata
 reST has the concept of "field lists"; these are a sequence of fields marked up
 like this::
 
-   :Field name: Field content
+   :fieldname: Field content
 
-A field list at the very top of a file is parsed as the "docinfo", which in
-normal documents can be used to record the author, date of publication and
-other metadata.  In Sphinx, the docinfo is used as metadata, too, but not
-displayed in the output.
+A field list at the very top of a file is parsed by docutils as the "docinfo",
+which is normally used to record the author, date of publication and other
+metadata.  *In Sphinx*, the docinfo is used as metadata, too, but not displayed
+in the output.
 
 At the moment, these metadata fields are recognized:
 
@@ -29,11 +29,17 @@ At the moment, these metadata fields are recognized:
    If set, the web application won't display a comment form for a page generated
    from this source file.
 
+``orphan``
+   If set, warnings about this file not being included in any toctree will be
+   suppressed.
+
+   .. versionadded:: 1.0
+
 
 Meta-information markup
 -----------------------
 
-.. directive:: sectionauthor
+.. rst:directive:: .. sectionauthor:: name <email>
 
    Identifies the author of the current section.  The argument should include
    the author's name such that it can be used for presentation and email
@@ -48,12 +54,20 @@ Meta-information markup
    output.
 
 
+.. rst:directive:: .. codeauthor:: name <email>
+
+   The :rst:dir:`codeauthor` directive, which can appear multiple times, names the
+   authors of the described code, just like :rst:dir:`sectionauthor` names the
+   author(s) of a piece of documentation.  It too only produces output if the
+   :confval:`show_authors` configuration value is True.
+
+
 .. _tags:
 
 Including content based on tags
 -------------------------------
 
-.. directive:: .. only:: <expression>
+.. rst:directive:: .. only:: <expression>
 
    Include the content of the directive only if the *expression* is true.  The
    expression should consist of tags, like this::
@@ -73,12 +87,12 @@ Including content based on tags
 Tables
 ------
 
-Use standard reStructuredText tables.  They work fine in HTML output, however
-there are some gotchas when using tables in LaTeX: the column width is hard to
-determine correctly automatically.  For this reason, the following directive
-exists:
+Use :ref:`standard reStructuredText tables <rst-tables>`.  They work fine in
+HTML output, however there are some gotchas when using tables in LaTeX: the
+column width is hard to determine correctly automatically.  For this reason, the
+following directive exists:
 
-.. directive:: .. tabularcolumns:: column spec
+.. rst:directive:: .. tabularcolumns:: column spec
 
    This directive gives a "column spec" for the next table occurring in the
    source file.  The spec is the second argument to the LaTeX ``tabulary``
@@ -114,5 +128,5 @@ exists:
    therefore set with the standard LaTeX ``tabular`` environment.  Also, the
    verbatim environment used for literal blocks only works in ``p{width}``
    columns, which means that by default, Sphinx generates such column specs for
-   such tables.  Use the :dir:`tabularcolumns` directive to get finer control
+   such tables.  Use the :rst:dir:`tabularcolumns` directive to get finer control
    over such tables.
diff --git a/doc/markup/para.rst b/doc/markup/para.rst
index 774b0f51..2fdc8d5a 100644
--- a/doc/markup/para.rst
+++ b/doc/markup/para.rst
@@ -9,7 +9,7 @@ Paragraph-level markup
 These directives create short paragraphs and can be used inside information
 units as well as normal text:
 
-.. directive:: note
+.. rst:directive:: .. note::
 
    An especially important bit of information about an API that a user should be
    aware of when using whatever bit of API the note pertains to.  The content of
@@ -22,15 +22,15 @@ units as well as normal text:
 
          This function is not suitable for sending spam e-mails.
 
-.. directive:: warning
+.. rst:directive:: .. warning::
 
    An important bit of information about an API that a user should be very aware
    of when using whatever bit of API the warning pertains to.  The content of
    the directive should be written in complete sentences and include all
-   appropriate punctuation. This differs from ``note`` in that it is recommended
-   over ``note`` for information regarding security.
+   appropriate punctuation. This differs from :rst:dir:`note` in that it is
+   recommended over :rst:dir:`note` for information regarding security.
 
-.. directive:: .. versionadded:: version
+.. rst:directive:: .. versionadded:: version
 
    This directive documents the version of the project which added the described
    feature to the library or C API. When this applies to an entire module, it
@@ -47,41 +47,42 @@ units as well as normal text:
    Note that there must be no blank line between the directive head and the
    explanation; this is to make these blocks visually continuous in the markup.
 
-.. directive:: .. versionchanged:: version
+.. rst:directive:: .. versionchanged:: version
 
-   Similar to ``versionadded``, but describes when and what changed in the named
+   Similar to :rst:dir:`versionadded`, but describes when and what changed in the named
    feature in some way (new parameters, changed side effects, etc.).
 
 --------------
 
-.. directive:: seealso
+.. rst:directive:: seealso
 
    Many sections include a list of references to module documentation or
-   external documents.  These lists are created using the ``seealso`` directive.
+   external documents.  These lists are created using the :rst:dir:`seealso`
+   directive.
 
-   The ``seealso`` directive is typically placed in a section just before any
+   The :rst:dir:`seealso` directive is typically placed in a section just before any
    sub-sections.  For the HTML output, it is shown boxed off from the main flow
    of the text.
 
-   The content of the ``seealso`` directive should be a reST definition list.
+   The content of the :rst:dir:`seealso` directive should be a reST definition list.
    Example::
 
       .. seealso::
 
-         Module :mod:`zipfile`
-            Documentation of the :mod:`zipfile` standard module.
+         Module :py:mod:`zipfile`
+            Documentation of the :py:mod:`zipfile` standard module.
 
          `GNU tar manual, Basic Tar Format <http://link>`_
             Documentation for tar archive files, including GNU tar extensions.
 
    There's also a "short form" allowed that looks like this::
 
-      .. seealso:: modules :mod:`zipfile`, :mod:`tarfile`
+      .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`
 
    .. versionadded:: 0.5
       The short form.
 
-.. directive:: .. rubric:: title
+.. rst:directive:: .. rubric:: title
 
    This directive creates a paragraph heading that is not used to create a
    table of contents node.
@@ -94,14 +95,15 @@ units as well as normal text:
       empty heading.
 
 
-.. directive:: centered
+.. rst:directive:: centered
 
-   This directive creates a centered boldfaced line of text.  Use it as follows::
+   This directive creates a centered boldfaced line of text.  Use it as
+   follows::
 
       .. centered:: LICENSE AGREEMENT
 
 
-.. directive:: hlist
+.. rst: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
@@ -125,23 +127,24 @@ units as well as normal text:
 Table-of-contents markup
 ------------------------
 
-The :dir:`toctree` directive, which generates tables of contents of
-subdocuments, is described in "Sphinx concepts".
+The :rst:dir:`toctree` directive, which generates tables of contents of
+subdocuments, is described in :ref:`toctree-directive`.
 
-For local tables of contents, use the standard reST :dir:`contents` directive.
+For local tables of contents, use the standard reST :rstdir:`contents directive
+<contents>`.
 
 
 Index-generating markup
 -----------------------
 
-Sphinx automatically creates index entries from all information units (like
-functions, classes or attributes) like discussed before.
+Sphinx automatically creates index entries from all object descriptions (like
+functions, classes or attributes) like discussed in :ref:`domains`.
 
 However, there is also an explicit directive available, to make the index more
 comprehensive and enable index entries in documents where information is not
 mainly contained in information units, such as the language reference.
 
-.. directive:: .. index:: <entries>
+.. rst:directive:: .. index:: <entries>
 
    This directive contains one or more index entries.  Each entry consists of a
    type and a value, separated by a colon.
@@ -159,9 +162,9 @@ mainly contained in information units, such as the language reference.
 
       ...
 
-   This directive contains five entries, which will be converted to entries in the
-   generated index which link to the exact location of the index statement (or, in
-   case of offline media, the corresponding page number).
+   This directive contains five entries, which will be converted to entries in
+   the generated index which link to the exact location of the index statement
+   (or, in case of offline media, the corresponding page number).
 
    Since index directives generate cross-reference targets at their location in
    the source, it makes sense to put them *before* the thing they refer to --
@@ -171,18 +174,19 @@ mainly contained in information units, such as the language reference.
 
    single
       Creates a single index entry.  Can be made a subentry by separating the
-      subentry text with a semicolon (this notation is also used below to describe
-      what entries are created).
+      subentry text with a semicolon (this notation is also used below to
+      describe what entries are created).
    pair
       ``pair: loop; statement`` is a shortcut that creates two index entries,
       namely ``loop; statement`` and ``statement; loop``.
    triple
-      Likewise, ``triple: module; search; path`` is a shortcut that creates three
-      index entries, which are ``module; search path``, ``search; path, module`` and
-      ``path; module search``.
+      Likewise, ``triple: module; search; path`` is a shortcut that creates
+      three index entries, which are ``module; search path``, ``search; path,
+      module`` and ``path; module search``.
    module, keyword, operator, object, exception, statement, builtin
-      These all create two index entries.  For example, ``module: hashlib`` creates
-      the entries ``module; hashlib`` and ``hashlib; module``.
+      These all create two index entries.  For example, ``module: hashlib``
+      creates the entries ``module; hashlib`` and ``hashlib; module``.  (These
+      are Python-specific and therefore deprecated.)
 
    For index directives containing only "single" entries, there is a shorthand
    notation::
@@ -195,10 +199,10 @@ mainly contained in information units, such as the language reference.
 Glossary
 --------
 
-.. directive:: glossary
+.. rst:directive:: .. glossary::
 
    This directive must contain a reST definition list with terms and
-   definitions.  The definitions will then be referencable with the :role:`term`
+   definitions.  The definitions will then be referencable with the :rst:role:`term`
    role.  Example::
 
       .. glossary::
@@ -227,7 +231,7 @@ derived forms), but provides enough to allow context-free grammars to be
 displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
 the definition of the symbol.  There is this directive:
 
-.. directive:: productionlist
+.. rst:directive:: .. productionlist:: [name]
 
    This directive is used to enclose a group of productions.  Each production is
    given on a single line and consists of a name, separated by a colon from the
@@ -235,17 +239,19 @@ the definition of the symbol.  There is this directive:
    continuation line must begin with a colon placed at the same column as in the
    first line.
 
+   The argument to :rst:dir:`productionlist` serves to distinguish different sets of
+   production lists that belong to different grammars.
+
    Blank lines are not allowed within ``productionlist`` directive arguments.
 
    The definition can contain token names which are marked as interpreted text
    (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
-   to the productions of these tokens.
+   to the productions of these tokens.  Outside of the production list, you can
+   reference to token productions using :rst:role:`token`.
 
    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
-
 The following is an example taken from the Python Reference Manual::
 
    .. productionlist::
diff --git a/doc/concepts.rst b/doc/markup/toctree.rst
index d9979d3f..9b987a2e 100644
--- a/doc/concepts.rst
+++ b/doc/markup/toctree.rst
@@ -1,27 +1,8 @@
-.. highlight:: rest
-
-.. _concepts:
-
-Sphinx concepts
-===============
-
-Document names
---------------
-
-Since the reST source files can have different extensions (some people like
-``.txt``, some like ``.rst`` -- the extension can be configured with
-:confval:`source_suffix`) and different OSes have different path separators,
-Sphinx abstracts them: all "document names" are relative to the :term:`source
-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.
-
+.. highlight:: rst
+.. _toctree-directive:
 
 The TOC tree
-------------
+============
 
 .. index:: pair: table of; contents
 
@@ -30,7 +11,7 @@ documents into multiple output files, Sphinx uses a custom directive to add
 relations between the single files the documentation is made of, as well as
 tables of contents.  The ``toctree`` directive is the central element.
 
-.. directive:: toctree
+.. rst:directive:: toctree
 
    This directive inserts a "TOC tree" at the current location, using the
    individual TOCs (including "sub-TOC trees") of the documents given in the
@@ -59,7 +40,7 @@ tables of contents.  The ``toctree`` directive is the central element.
      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
+   Document titles in the :rst:dir:`toctree` will be automatically read from the
    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
@@ -89,6 +70,15 @@ tables of contents.  The ``toctree`` directive is the central element.
    Numbering then starts at the heading of ``foo``.  Sub-toctrees are
    automatically numbered (don't give the ``numbered`` flag to those).
 
+   If you want only the titles of documents in the tree to show up, not other
+   headings of the same level, you can use the ``titlesonly`` option::
+
+      .. toctree::
+         :titlesonly:
+
+         foo
+         bar
+
    You can use "globbing" in toctree directives, by giving the ``glob`` flag
    option.  All entries are then matched against the list of available
    documents, and matches are inserted into the list alphabetically.  Example::
@@ -139,6 +129,9 @@ tables of contents.  The ``toctree`` directive is the central element.
       Added "numbered" and "hidden" options as well as external links and
       support for "self" references.
 
+   .. versionchanged:: 1.0
+      Added "titlesonly" option.
+
 
 Special names
 -------------
@@ -150,13 +143,14 @@ The special document names (and pages generated for them) are:
 
 * ``genindex``, ``modindex``, ``search``
 
-  These are used for the general index, the module index, and the search page,
-  respectively.
+  These are used for the general index, the Python module index, and the search
+  page, respectively.
 
   The general index is populated with entries from modules, all index-generating
-  :ref:`description units <desc-units>`, and from :dir:`index` directives.
+  :ref:`object descriptions <basic-domain-markup>`, and from :rst:dir:`index`
+  directives.
 
-  The module index contains one entry per :dir:`module` directive.
+  The module index contains one entry per :rst:dir:`module` directive.
 
   The search page contains a form that uses the generated JSON search index and
   JavaScript to full-text search the generated documents for search words; it
diff --git a/doc/more.png b/doc/more.png
new file mode 100644
index 00000000..3eb7b05c
--- /dev/null
+++ b/doc/more.png
diff --git a/doc/rest.rst b/doc/rest.rst
index e70fa105..6693c217 100644
--- a/doc/rest.rst
+++ b/doc/rest.rst
@@ -1,5 +1,7 @@
 .. highlightlang:: rest
 
+.. _rst-primer:
+
 reStructuredText Primer
 =======================
 
@@ -10,18 +12,22 @@ language, this will not take too long.
 
 .. seealso::
 
-    The authoritative `reStructuredText User
-    Documentation <http://docutils.sourceforge.net/rst.html>`_.
+   The authoritative `reStructuredText User Documentation
+   <http://docutils.sourceforge.net/rst.html>`_.  The "ref" links in this
+   document link to the description of the individual constructs in the reST
+   reference.
 
 
 Paragraphs
 ----------
 
-The paragraph is the most basic block in a reST document.  Paragraphs are simply
-chunks of text separated by one or more blank lines.  As in Python, indentation
-is significant in reST, so all lines of the same paragraph must be left-aligned
-to the same level of indentation.
+The paragraph (:rstref:`ref <paragraphs>`) is the most basic block in a reST
+document.  Paragraphs are simply chunks of text separated by one or more blank
+lines.  As in Python, indentation is significant in reST, so all lines of the
+same paragraph must be left-aligned to the same level of indentation.
+
 
+.. _inlinemarkup:
 
 Inline markup
 -------------
@@ -49,13 +55,25 @@ enclosed text should be interpreted in a specific way.  Sphinx uses this to
 provide semantic markup and cross-referencing of identifiers, as described in
 the appropriate section.  The general syntax is ``:rolename:`content```.
 
+Standard reST provides the following roles:
+
+* :rstrole:`emphasis` -- alternate spelling for ``*emphasis*``
+* :rstrole:`strong` -- alternate spelling for ``**strong**``
+* :rstrole:`literal` -- alternate spelling for ````literal````
+* :rstrole:`subscript` -- subscript text
+* :rstrole:`superscript` -- superscript text
+* :rstrole:`title-reference` -- for titles of books, periodicals, and other
+  materials
+
+See :ref:`inline-markup` for roles added by Sphinx.
+
 
-Lists and Quotes
-----------------
+Lists and Quote-like blocks
+---------------------------
 
-List markup is natural: just place an asterisk at the start of a paragraph and
-indent properly.  The same goes for numbered lists; they can also be
-autonumbered using a ``#`` sign::
+List markup (:rstref:`ref <bullet-lists>`) is natural: just place an asterisk at
+the start of a paragraph and indent properly.  The same goes for numbered lists;
+they can also be autonumbered using a ``#`` sign::
 
    * This is a bulleted list.
    * It has two items, the second
@@ -79,7 +97,7 @@ parent list items by blank lines::
 
    * and here the parent list continues
 
-Definition lists are created as follows::
+Definition lists (:rstref:`ref <definition-lists>`) are created as follows::
 
    term (up to a line of text)
       Definition of the term, which must be indented
@@ -89,17 +107,31 @@ Definition lists are created as follows::
    next term
       Description.
 
+Note that the term cannot have more than one line of text.
 
-Paragraphs are quoted by just indenting them more than the surrounding
-paragraphs.
+Quoted paragraphs (:rstref:`ref <block-quotes>`) are created by just indenting
+them more than the surrounding paragraphs.
+
+Line blocks (:rstref:`ref <line-blocks>`) are a way of preserving line breaks::
+
+   | These lines are
+   | broken exactly like in
+   | the source file.
+
+There are also several more special blocks available:
+
+* field lists (:rstref:`ref <field-lists>`)
+* option lists (:rstref:`ref <option-lists>`)
+* quoted literal blocks (:rstref:`ref <quoted-literal-blocks>`)
+* doctest blocks (:rstref:`ref <doctest-blocks>`)
 
 
 Source Code
 -----------
 
-Literal code blocks are introduced by ending a paragraph with the special marker
-``::``.  The literal block must be indented (and, like all paragraphs, separated
-from the surrounding ones by blank lines)::
+Literal code blocks (:rstref:`ref <literal-blocks>`) are introduced by ending a
+paragraph with the special marker ``::``.  The literal block must be indented
+(and, like all paragraphs, separated from the surrounding ones by blank lines)::
 
    This is a normal text paragraph. The next paragraph is a code sample::
 
@@ -122,28 +154,69 @@ That way, the second sentence in the above example's first paragraph would be
 rendered as "The next paragraph is a code sample:".
 
 
+.. _rst-tables:
+
+Tables
+------
+
+Two forms of tables are supported.  For *grid tables* (:rstref:`ref
+<grid-tables>`), you have to "paint" the cell grid yourself.  They look like
+this::
+
+   +------------------------+------------+----------+----------+
+   | Header row, column 1   | Header 2   | Header 3 | Header 4 |
+   | (header rows optional) |            |          |          |
+   +========================+============+==========+==========+
+   | body row 1, column 1   | column 2   | column 3 | column 4 |
+   +------------------------+------------+----------+----------+
+   | body row 2             | ...        | ...      |          |
+   +------------------------+------------+----------+----------+
+
+*Simple tables* (:rstref:`ref <simple-tables>`) are easier to write, but
+limited: they must contain more than one row, and the first column cannot
+contain multiple lines.  They look like this::
+
+   =====  =====  =======
+   A      B      A and B
+   =====  =====  =======
+   False  False  False
+   True   False  False
+   False  True   False
+   True   True   True
+   =====  =====  =======
+
+
 Hyperlinks
 ----------
 
 External links
 ^^^^^^^^^^^^^^
 
-Use ```Link text <http://target>`_`` for inline web links.  If the link text
-should be the web address, you don't need special markup at all, the parser
+Use ```Link text <http://example.com/>`_`` for inline web links.  If the link
+text should be the web address, you don't need special markup at all, the parser
 finds links and mail addresses in ordinary text.
 
+You can also separate the link and the target definition (:rstref:`ref
+<hyperlink-targets>`), like this::
+
+   This is a paragraph that contains `a link`_.
+
+   .. _a link: http://example.com/
+
+
 Internal links
 ^^^^^^^^^^^^^^
 
-Internal linking is done via a special reST role, see the section on specific
-markup, :ref:`ref-role`.
+Internal linking is done via a special reST role provided by Sphinx, see the
+section on specific markup, :ref:`ref-role`.
 
 
 Sections
 --------
 
-Section headers are created by underlining (and optionally overlining) the
-section title with a punctuation character, at least as long as the text::
+Section headers (:rstref:`ref <sections>`) are created by underlining (and
+optionally overlining) the section title with a punctuation character, at least
+as long as the text::
 
    =================
    This is a heading
@@ -168,9 +241,9 @@ target formats (HTML, LaTeX) have a limited supported nesting depth.
 Explicit Markup
 ---------------
 
-"Explicit markup" is used in reST for most constructs that need special
-handling, such as footnotes, specially-highlighted paragraphs, comments, and
-generic directives.
+"Explicit markup" (:rstref:`ref <explicit-markup-blocks>`) is used in reST for
+most constructs that need special handling, such as footnotes,
+specially-highlighted paragraphs, comments, and generic directives.
 
 An explicit markup block begins with a line starting with ``..`` followed by
 whitespace and is terminated by the next paragraph at the same level of
@@ -179,11 +252,70 @@ paragraphs.  This may all sound a bit complicated, but it is intuitive enough
 when you write it.)
 
 
+.. _directives:
+
 Directives
 ----------
 
-A directive is a generic block of explicit markup.  Besides roles, it is one of
-the extension mechanisms of reST, and Sphinx makes heavy use of it.
+A directive (:rstref:`ref <directives>`) is a generic block of explicit markup.
+Besides roles, it is one of the extension mechanisms of reST, and Sphinx makes
+heavy use of it.
+
+Docutils supports the following directives:
+
+* Admonitions: :rstdir:`attention`, :rstdir:`caution`, :rstdir:`danger`,
+  :rstdir:`error`, :rstdir:`hint`, :rstdir:`important`, :rstdir:`note`,
+  :rstdir:`tip`, :rstdir:`warning` and the generic :rstdir:`admonition`.
+  (Most themes style only "note" and "warning" specially.)
+
+* Images:
+
+  - :rstdir:`image` (see also Images_ below)
+  - :rstdir:`figure` (an image with caption and optional legend)
+
+* Additional body elements:
+
+  - :rstdir:`contents` (a local, i.e. for the current file only, table of
+    contents)
+  - :rstdir:`container` (a container with a custom class, useful to generate an
+    outer ``<div>`` in HTML)
+  - :rstdir:`rubric` (a heading without relation to the document sectioning)
+  - :rstdir:`topic`, :rstdir:`sidebar` (special highlighted body elements)
+  - :rstdir:`parsed-literal` (literal block that supports inline markup)
+  - :rstdir:`epigraph` (a block quote with optional attribution line)
+  - :rstdir:`highlights`, :rstdir:`pull-quote` (block quotes with their own
+    class attribute)
+  - :rstdir:`compound` (a compound paragraph)
+
+* Special tables:
+
+  - :rstdir:`table` (a table with title)
+  - :rstdir:`csv-table` (a table generated from comma-separated values)
+  - :rstdir:`list-table` (a table generated from a list of lists)
+
+* Special directives:
+
+  - :rstdir:`raw` (include raw target-format markup)
+  - :rstdir:`include` (include reStructuredText from another file)
+  - :rstdir:`class` (assign a class attribute to the next element) [1]_
+
+* HTML specifics:
+
+  - :rstdir:`meta` (generation of HTML ``<meta>`` tags)
+  - :rstdir:`title` (override document title)
+
+* Influencing markup:
+
+  - :rstdir:`default-role` (set a new default role)
+  - :rstdir:`role` (create a new role)
+
+  Since these are only per-file, better use Sphinx' facilities for setting the
+  :confval:`default_role`.
+
+Do *not* use the directives :rstdir:`sectnum`, :rstdir:`header` and
+:rstdir:`footer`.
+
+Directives added by Sphinx are described in :ref:`sphinxmarkup`.
 
 Basically, a directive consists of a name, arguments, options and content. (Keep
 this terminology in mind, it is used in the next chapter describing custom
@@ -207,7 +339,7 @@ directive start.
 Images
 ------
 
-reST supports an image directive, used like so::
+reST supports an image directive (:rstdir:`ref <image>`), used like so::
 
    .. image:: gnu.png
       (options)
@@ -247,9 +379,9 @@ the former, while the HTML builder would prefer the latter.
 Footnotes
 ---------
 
-For footnotes, use ``[#name]_`` to mark the footnote location, and add the
-footnote body at the bottom of the document after a "Footnotes" rubric heading,
-like so::
+For footnotes (:rstref:`ref <footnotes>`), use ``[#name]_`` to mark the footnote
+location, and add the footnote body at the bottom of the document after a
+"Footnotes" rubric heading, like so::
 
    Lorem ipsum [#f1]_ dolor sit amet ... [#f2]_
 
@@ -265,9 +397,9 @@ footnotes without names (``[#]_``).
 Citations
 ---------
 
-Standard reST citations are supported, with the additional feature that they are
-"global", i.e. all citations can be referenced from all files.  Use them like
-so::
+Standard reST citations (:rstref:`ref <citations>`) are supported, with the
+additional feature that they are "global", i.e. all citations can be referenced
+from all files.  Use them like so::
 
    Lorem ipsum [Ref]_ dolor sit amet.
 
@@ -280,19 +412,23 @@ numeric or begins with ``#``.
 Substitutions
 -------------
 
-reST supports "substitutions", which are pieces of text and/or markup referred
-to in the text by ``|name|``.  They are defined like footnotes with explicit
-markup blocks, like this::
+reST supports "substitutions" (:rstref:`ref <substitution-definitions>`), which
+are pieces of text and/or markup referred to in the text by ``|name|``.  They
+are defined like footnotes with explicit markup blocks, like this::
 
    .. |name| replace:: replacement *text*
 
-See the `reST reference for substitutions
-<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions>`_
+or this::
+
+   .. |caution| image:: warning.png
+                :alt: Warning!
+
+See the :rstref:`reST reference for substitutions <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
+the :rst:dir:`include` directive.  Be sure to give the include file a file name
 extension differing from that of other source files, to avoid Sphinx finding it
 as a standalone document.
 
@@ -303,7 +439,8 @@ Comments
 --------
 
 Every explicit markup block which isn't a valid markup construct (like the
-footnotes above) is regarded as a comment.  For example::
+footnotes above) is regarded as a comment (:rstref:`ref <comments>`).  For
+example::
 
    .. This is a comment.
 
@@ -331,10 +468,16 @@ Gotchas
 There are some problems one commonly runs into while authoring reST documents:
 
 * **Separation of inline markup:** As said above, inline markup spans must be
-  separated from the surrounding text by non-word characters, you have to use
-  a backslash-escaped space to get around that.
+  separated from the surrounding text by non-word characters, you have to use a
+  backslash-escaped space to get around that.  See `the reference
+  <http://docutils.sf.net/docs/ref/rst/restructuredtext.html#inline-markup>`_
+  for the details.
 
 * **No nested inline markup:** Something like ``*see :func:`foo`*`` is not
   possible.
 
-.. XXX more?
+
+.. rubric:: Footnotes
+
+.. [1] When the default domain contains a :rst:dir:`class` directive, this directive
+       will be shadowed.  Therefore, Sphinx re-exports it as :rst:dir:`rst-class`.
diff --git a/doc/sphinx-build.1 b/doc/sphinx-build.1
deleted file mode 100644
index 498771c9..00000000
--- a/doc/sphinx-build.1
+++ /dev/null
@@ -1,102 +0,0 @@
-.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
deleted file mode 100644
index 93b0a4a5..00000000
--- a/doc/sphinx-quickstart.1
+++ /dev/null
@@ -1,17 +0,0 @@
-.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 cccc0a77..5bf09dbd 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -139,23 +139,36 @@ The following blocks exist in the ``layout.html`` template:
     The logo location within the sidebar.  Override this if you want to place
     some content at the top of the sidebar.
 
+`footer`
+    The block for the footer div.  If you want a custom footer or markup before
+    or after it, override this one.
+
+The following four blocks are *only* used for pages that do not have assigned a
+list of custom sidebars in the :confval:`html_sidebars` config value.  Their use
+is deprecated in favor of separate sidebar templates, which can be included via
+:confval:`html_sidebars`.
+
 `sidebartoc`
     The table of contents within the sidebar.
 
+    .. deprecated:: 1.0
+
 `sidebarrel`
     The relation links (previous, next document) within the sidebar.
 
+    .. deprecated:: 1.0
+
 `sidebarsourcelink`
     The "Show source" link within the sidebar (normally only shown if this is
     enabled by :confval:`html_show_sourcelink`).
 
+    .. deprecated:: 1.0
+
 `sidebarsearch`
     The search box within the sidebar.  Override this if you want to place some
     content at the bottom of the sidebar.
 
-`footer`
-    The block for the footer div.  If you want a custom footer or markup before
-    or after it, override this one.
+    .. deprecated:: 1.0
 
 
 Configuration Variables
@@ -305,9 +318,9 @@ in the future.
 .. 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)``.
+   "prev".  This usually contains links to the general index and other indices,
+   such as the Python module index.  If you add something yourself, it must be a
+   tuple ``(pagename, link title, accesskey, link text)``.
 
 .. data:: shorttitle
 
@@ -364,6 +377,10 @@ are in HTML form), these variables are also available:
 .. 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
-   (the default), all TOC entries that are not ancestors of the current page are
-   collapsed.
+   as HTML bullet lists.  Optional keyword arguments:
+
+   * ``collapse`` (true by default): if true, all TOC entries that are not
+     ancestors of the current page are collapsed
+
+   * ``maxdepth`` (defaults to the max depth selected in the toctree directive):
+     the maximum depth of the tree; set it to ``-1`` to allow unlimited depth
diff --git a/doc/themes/agogo.png b/doc/themes/agogo.png
new file mode 100644
index 00000000..d29aa45c
--- /dev/null
+++ b/doc/themes/agogo.png
diff --git a/doc/themes/default.png b/doc/themes/default.png
new file mode 100644
index 00000000..93d8526c
--- /dev/null
+++ b/doc/themes/default.png
diff --git a/doc/themes/fullsize/agogo.png b/doc/themes/fullsize/agogo.png
new file mode 100644
index 00000000..93fadfcb
--- /dev/null
+++ b/doc/themes/fullsize/agogo.png
diff --git a/doc/themes/fullsize/default.png b/doc/themes/fullsize/default.png
new file mode 100644
index 00000000..b6af8bc3
--- /dev/null
+++ b/doc/themes/fullsize/default.png
diff --git a/doc/themes/fullsize/haiku.png b/doc/themes/fullsize/haiku.png
new file mode 100644
index 00000000..1590da5d
--- /dev/null
+++ b/doc/themes/fullsize/haiku.png
diff --git a/doc/themes/fullsize/nature.png b/doc/themes/fullsize/nature.png
new file mode 100644
index 00000000..d42957e3
--- /dev/null
+++ b/doc/themes/fullsize/nature.png
diff --git a/doc/themes/fullsize/scrolls.png b/doc/themes/fullsize/scrolls.png
new file mode 100644
index 00000000..7d46f7ed
--- /dev/null
+++ b/doc/themes/fullsize/scrolls.png
diff --git a/doc/themes/fullsize/sphinxdoc.png b/doc/themes/fullsize/sphinxdoc.png
new file mode 100644
index 00000000..722fb900
--- /dev/null
+++ b/doc/themes/fullsize/sphinxdoc.png
diff --git a/doc/themes/fullsize/traditional.png b/doc/themes/fullsize/traditional.png
new file mode 100644
index 00000000..103fd3ca
--- /dev/null
+++ b/doc/themes/fullsize/traditional.png
diff --git a/doc/themes/haiku.png b/doc/themes/haiku.png
new file mode 100644
index 00000000..a8ae8557
--- /dev/null
+++ b/doc/themes/haiku.png
diff --git a/doc/themes/nature.png b/doc/themes/nature.png
new file mode 100644
index 00000000..3d4f587f
--- /dev/null
+++ b/doc/themes/nature.png
diff --git a/doc/themes/scrolls.png b/doc/themes/scrolls.png
new file mode 100644
index 00000000..8073c10e
--- /dev/null
+++ b/doc/themes/scrolls.png
diff --git a/doc/themes/sphinxdoc.png b/doc/themes/sphinxdoc.png
new file mode 100644
index 00000000..f4b59ecd
--- /dev/null
+++ b/doc/themes/sphinxdoc.png
diff --git a/doc/themes/traditional.png b/doc/themes/traditional.png
new file mode 100644
index 00000000..4ad2b5ce
--- /dev/null
+++ b/doc/themes/traditional.png
diff --git a/doc/theming.rst b/doc/theming.rst
index d1d3b27a..3a00150b 100644
--- a/doc/theming.rst
+++ b/doc/theming.rst
@@ -52,17 +52,50 @@ file :file:`blue.zip`, you can put it right in the directory containing
 Builtin themes
 --------------
 
-Sphinx comes with a selection of themes to choose from:
+.. cssclass:: right
+
++--------------------+--------------------+
+| **Theme overview** |                    |
++--------------------+--------------------+
+| |default|          | |sphinxdoc|        |
+|                    |                    |
+| *default*          | *sphinxdoc*        |
++--------------------+--------------------+
+| |scrolls|          | |agogo|            |
+|                    |                    |
+| *scrolls*          | *agogo*            |
++--------------------+--------------------+
+| |traditional|      | |nature|           |
+|                    |                    |
+| *traditional*      | *nature*           |
++--------------------+--------------------+
+| |haiku|            |                    |
+|                    |                    |
+| *haiku*            |                    |
++--------------------+--------------------+
+
+.. |default|     image:: themes/default.png
+.. |sphinxdoc|   image:: themes/sphinxdoc.png
+.. |scrolls|     image:: themes/scrolls.png
+.. |agogo|       image:: themes/agogo.png
+.. |traditional| image:: themes/traditional.png
+.. |nature|      image:: themes/nature.png
+.. |haiku|       image:: themes/haiku.png
+
+Sphinx comes with a selection of themes to choose from.
+
+These themes are:
 
 * **basic** -- This is a basically unstyled layout used as the base for the
-  *default* and *sphinxdoc* themes, and usable as the base for custom themes as
-  well.  The HTML contains all important elements like sidebar and relation bar.
-  There is one option (which is inherited by *default* and *sphinxdoc*):
+  other 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 the other themes):
 
   - **nosidebar** (true or false): Don't include the sidebar.  Defaults to
     false.
 
-* **default** -- This is the default theme.  It can be customized via these
+* **default** -- This is the default theme, which looks like `the Python
+  documentation <http://docs.python.org/>`_.  It can be customized via these
   options:
 
   - **rightsidebar** (true or false): Put the sidebar on the right side.
@@ -86,6 +119,7 @@ Sphinx comes with a selection of themes to choose from:
   - **bgcolor** (CSS color): Body background color.
   - **textcolor** (CSS color): Body text color.
   - **linkcolor** (CSS color): Body link color.
+  - **visitedlinkcolor** (CSS color): Body color for visited links.
   - **headbgcolor** (CSS color): Background color for headings.
   - **headtextcolor** (CSS color): Text color for headings.
   - **headlinkcolor** (CSS color): Link color for headings.
@@ -99,9 +133,59 @@ Sphinx comes with a selection of themes to choose from:
 * **sphinxdoc** -- The theme used for this documentation.  It features a sidebar
   on the right side.  There are currently no options beyond *nosidebar*.
 
+* **scrolls** -- A more lightweight theme, based on `the Jinja documentation
+  <http://jinja.pocoo.org/2/documentation/>`_.  The following color options are
+  available:
+
+  - **headerbordercolor**
+  - **subheadlinecolor**
+  - **linkcolor**
+  - **visitedlinkcolor**
+  - **admonitioncolor**
+
+* **agogo** -- A theme created by Andi Albrecht.  The following options are
+  supported:
+
+  - **bodyfont** (CSS font family): Font for normal text.
+  - **headerfont** (CSS font family): Font for headings.
+  - **pagewidth** (CSS length): Width of the page content, default 70em.
+  - **documentwidth** (CSS length): Width of the document (without sidebar),
+    default 50em.
+  - **sidebarwidth** (CSS length): Width of the sidebar, default 20em.
+  - **bgcolor** (CSS color): Background color.
+  - **headerbg** (CSS value for "background"): background for the header area,
+    default a grayish gradient.
+  - **footerbg** (CSS value for "background"): background for the footer area,
+    default a light gray gradient.
+  - **linkcolor** (CSS color): Body link color.
+  - **headercolor1**, **headercolor2** (CSS color): colors for <h1> and <h2>
+    headings.
+  - **headerlinkcolor** (CSS color): Color for the backreference link in
+    headings.
+  - **textalign** (CSS *text-align* value): Text alignment for the body, default
+    is ``justify``.
+
+* **nature** -- A greenish theme.  There are currently no options beyond
+  *nosidebar*.
+
+* **haiku** -- A theme without sidebar inspired by the `Haiku OS user guide
+  <http://www.haiku-os.org/docs/userguide/en/contents.html>`_.  The following
+  options are supported:
+
+  - **full_logo** (true or false, default false): If this is true, the header
+    will only show the :confval:`html_logo`.  Use this for large logos.  If this
+    is false, the logo (if present) will be shown floating right, and the
+    documentation title will be put in the header.
+  - **textcolor**, **headingcolor**, **linkcolor**, **visitedlinkcolor**,
+    **hoverlinkcolor** (CSS colors): Colors for various body elements.
+
 * **traditional** -- A theme resembling the old Python documentation.  There are
   currently no options beyond *nosidebar*.
 
+* **epub** -- A theme for the epub builder.  There are currently no options.
+  This theme tries to save visual space which is a sparse resource on ebook
+  readers.
+
 
 Creating themes
 ---------------
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
new file mode 100644
index 00000000..fa6ee2ab
--- /dev/null
+++ b/doc/tutorial.rst
@@ -0,0 +1,262 @@
+.. highlight:: rst
+
+First Steps with Sphinx
+=======================
+
+This document is meant to give a tutorial-like overview of all common tasks
+while using Sphinx.
+
+The green arrows designate "more info" links leading to advanced sections about
+the described task.
+
+
+Setting up the documentation sources
+------------------------------------
+
+The root directory of a documentation collection is called the :term:`source
+directory`.  This directory also contains the Sphinx configuration file
+:file:`conf.py`, where you can configure all aspects of how Sphinx reads your
+sources and builds your documentation.  [#]_
+
+Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
+source directory and creates a default :file:`conf.py` with the most useful
+configuration values from a few questions it asks you.  Just run ::
+
+   $ sphinx-quickstart
+
+and answer its questions.  (Be sure to say yes to the "autodoc" extension.)
+
+
+Defining document structure
+---------------------------
+
+Let's assume you've run :program:`sphinx-quickstart`.  It created a source
+directory with :file:`conf.py` and a master document, :file:`index.rst` (if you
+accepted the defaults).  The main function of the :term:`master document` is to
+serve as a welcome page, and to contain the root of the "table of contents tree"
+(or *toctree*).  This is one of the main things that Sphinx adds to
+reStructuredText, a way to connect multiple files to a single hierarchy of
+documents.
+
+.. sidebar:: reStructuredText directives
+
+   ``toctree`` is a reStructuredText :dfn:`directive`, a very versatile piece of
+   markup.  Directives can have arguments, options and content.
+
+   *Arguments* are given directly after the double colon following the
+   directive's name.  Each directive decides whether it can have arguments, and
+   how many.
+
+   *Options* are given after the arguments, in form of a "field list".  The
+   ``maxdepth`` is such an option for the ``toctree`` directive.
+
+   *Content* follows the options or arguments after a blank line.  Each
+   directive decides whether to allow content, and what to do with it.
+
+   A common gotcha with directives is that **the first line of the content must
+   be indented to the same level as the options are**.
+
+
+The toctree directive initially is empty, and looks like this::
+
+   .. toctree::
+      :maxdepth: 2
+
+You add documents listing them in the *content* of the directive::
+
+   .. toctree::
+      :maxdepth: 2
+
+      intro
+      tutorial
+      ...
+
+This is exactly how the toctree for this documentation looks.  The documents to
+include are given as :term:`document name`\ s, which in short means that you
+leave off the file name extension and use slashes as directory separators.
+
+|more| Read more about :ref:`the toctree directive <toctree-directive>`.
+
+You can now create the files you listed in the toctree and add content, and
+their section titles will be inserted (up to the "maxdepth" level) at the place
+where the toctree directive is placed.  Also, Sphinx now knows about the order
+and hierarchy of your documents.  (They may contain ``toctree`` directives
+themselves, which means you can create deeply nested hierarchies if necessary.)
+
+
+Adding content
+--------------
+
+In Sphinx source files, you can use most features of standard reStructuredText.
+There are also several features added by Sphinx.  For example, you can add
+cross-file references in a portable way (which works for all output types) using
+the :rst:role:`ref` role.
+
+For an example, if you are viewing the HTML version you can look at the source
+for this document -- use the "Show Source" link in the sidebar.
+
+|more| See :ref:`rst-primer` for a more in-depth introduction to
+reStructuredText and :ref:`sphinxmarkup` for a full list of markup added by
+Sphinx.
+
+
+Running the build
+-----------------
+
+Now that you have added some files and content, let's make a first build of the
+docs.  A build is started with the :program:`sphinx-build` program, called like
+this::
+
+   $ sphinx-build -b html sourcedir builddir
+
+where *sourcedir* is the :term:`source directory`, and *builddir* is the
+directory in which you want to place the built documentation.  The :option:`-b`
+option selects a builder; in this example Sphinx will build HTML files.
+
+|more| See :ref:`invocation` for all options that :program:`sphinx-build`
+supports.
+
+However, :program:`sphinx-quickstart` script creates a :file:`Makefile` and a
+:file:`make.bat` which make life even easier for you:  with them you only need
+to run ::
+
+   $ make html
+
+to build HTML docs in the build directory you chose.  Execute ``make`` without
+an argument to see which targets are available.
+
+
+Documenting objects
+-------------------
+
+One of Sphinx' main objectives is easy documentation of :dfn:`objects` (in a
+very general sense) in any :dfn:`domain`.  A domain is a collection of object
+types that belong together, complete with markup to create and reference
+descriptions of these objects.
+
+The most prominent domain is the Python domain.  To e.g. document the Python
+built-in function ``enumerate()``, you would add this to one of your source
+files::
+
+   .. py:function:: enumerate(sequence[, start=0])
+
+      Return an iterator that yields tuples of an index and an item of the
+      *sequence*. (And so on.)
+
+This is rendered like this:
+
+.. py:function:: enumerate(sequence[, start=0])
+
+   Return an iterator that yields tuples of an index and an item of the
+   *sequence*. (And so on.)
+
+The argument of the directive is the :dfn:`signature` of the object you
+describe, the content is the documentation for it.  Multiple signatures can be
+given, each in its own line.
+
+The Python domain also happens to be the default domain, so you don't need to
+prefix the markup with the domain name::
+
+   .. function:: enumerate(sequence[, start=0])
+
+      ...
+
+does the same job if you keep the default setting for the default domain.
+
+There are several more directives for documenting other types of Python objects,
+for example :rst:dir:`py:class` or :rst:dir:`py:method`.  There is also a
+cross-referencing :dfn:`role` for each of these object types.  This markup will
+create a link to the documentation of ``enumerate()``::
+
+   The :py:func:`enumerate` function can be used for ...
+
+And here is the proof: A link to :func:`enumerate`.
+
+Again, the ``py:`` can be left out if the Python domain is the default one.  It
+doesn't matter which file contains the actual documentation for ``enumerate()``;
+Sphinx will find it and create a link to it.
+
+Each domain will have special rules for how the signatures can look like, and
+make the formatted output look pretty, or add specific features like links to
+parameter types, e.g. in the C/C++ domains.
+
+|more| See :ref:`domains` for all the available domains and their
+directives/roles.
+
+
+Basic configuration
+-------------------
+
+Earlier we mentioned that the :file:`conf.py` file controls how Sphinx processes
+your documents.  In that file, which is executed as a Python source file, you
+assign configuration values.  For advanced users: since it is executed by
+Sphinx, you can do non-trivial tasks in it, like extending :data:`sys.path` or
+importing a module to find out the version your are documenting.
+
+The config values that you probably want to change are already put into the
+:file:`conf.py` by :program:`sphinx-quickstart` and initially commented out
+(with standard Python syntax: a ``#`` comments the rest of the line).  To change
+the default value, remove the hash sign and modify the value.  To customize a
+config value that is not automatically added by :program:`sphinx-quickstart`,
+just add an additional assignment.
+
+Keep in mind that the file uses Python syntax for strings, numbers, lists and so
+on.  The file is saved in UTF-8 by default, as indicated by the encoding
+declaration in the first line.  If you use non-ASCII characters in any string
+value, you need to use Python Unicode strings (like ``project = u'Exposé'``).
+
+|more| See :ref:`build-config` for documentation of all available config values.
+
+
+Autodoc
+-------
+
+When documenting Python code, it is common to put a lot of documentation in the
+source files, in documentation strings.  Sphinx supports the inclusion of
+docstrings from your modules with an :dfn:`extension` (an extension is a Python
+module that provides additional features for Sphinx projects) called "autodoc".
+
+In order to use autodoc, you need to activate it in :file:`conf.py` by putting
+the string ``'sphinx.ext.autodoc'`` into the list assigned to the
+:confval:`extensions` config value.  Then, you have a few additional directives
+at your disposal.
+
+For example, to document the function ``io.open()``, reading its
+signature and docstring from the source file, you'd write this::
+
+   .. autofunction:: io.open
+
+You can also document whole classes or even modules automatically, using member
+options for the auto directives, like ::
+
+   .. automodule:: io
+      :members:
+
+autodoc needs to import your modules in order to extract the docstrings.
+Therefore, you must add the appropriate path to :py:data:`sys.path` in your
+:file:`conf.py`.
+
+|more| See :mod:`sphinx.ext.autodoc` for the complete description of the
+features of autodoc.
+
+
+More topics to be covered
+-------------------------
+
+- Other extensions (math, intersphinx, viewcode, doctest)
+- Static files
+- Selecting a theme
+- Templating
+- Using extensions
+- Writing extensions
+
+
+.. rubric:: Footnotes
+
+.. [#] This is the usual lay-out.  However, :file:`conf.py` can also live in
+       another directory, the :term:`configuration directory`.  See
+       :ref:`invocation`.
+
+.. |more| image:: more.png
+          :align: middle
+          :alt: more info