merge with 1.0

29 files changed, 1255 insertions, 155 deletions

diff --git a/doc/Makefile b/doc/Makefile
index 90fb5af2..0199ba47 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -29,6 +29,9 @@ help:
 	@echo "  epub       to make an epub file"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run pdflatex"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
 	@echo "  changes    to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck  to check all external links for integrity"
 
@@ -112,6 +115,11 @@ latexpdf:
 	make -C _build/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in _build/latex."
 
+gettext:
+	$(SPHINXBUILD) -b gettext $(ALLSPHINXOPTS) _build/locale
+	@echo
+	@echo "Build finished. The message catalogs are in _build/locale."
+
 changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) _build/changes
 	@echo
@@ -125,3 +133,16 @@ linkcheck:
 
 doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) _build/doctest
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) _build/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in _build/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) _build/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C _build/texinfo info
+	@echo "makeinfo finished; the Info files are in _build/texinfo."
diff --git a/doc/builders.rst b/doc/builders.rst
index 80203e75..4a95e120 100644
--- a/doc/builders.rst
+++ b/doc/builders.rst
@@ -144,6 +144,26 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf
 
    .. versionadded:: 1.0
 
+
+.. module:: sphinx.builders.texinfo
+.. class:: TexinfoBuilder
+
+   This builder produces Texinfo files that can be processed into Info files by
+   the :program:`makeinfo` program.  You have to specify which documents are to
+   be included in which Texinfo files via the :confval:`texinfo_documents`
+   configuration value.
+
+   The Info format is the basis of the on-line help system used by GNU Emacs and
+   the terminal-based program :program:`info`.  See :ref:`texinfo-faq` for more
+   details.  The Texinfo format is the official documentation system used by the
+   GNU project.  More information on Texinfo can be found at
+   `<http://www.gnu.org/software/texinfo/>`_.
+
+   Its name is ``texinfo``.
+
+   .. versionadded:: 1.1
+
+
 .. currentmodule:: sphinx.builders.html
 .. class:: SerializingHTMLBuilder
 
@@ -220,6 +240,18 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf
 
    .. versionadded:: 0.5
 
+.. module:: sphinx.builders.intl
+.. class:: MessageCatalogBuilder
+
+   This builder produces gettext-style message catalos.  Each top-level file or
+   subdirectory grows a single ``.pot`` catalog template.
+
+   See the documentation on :ref:`intl` for further reference.
+
+   Its name is ``gettext``.
+
+   .. versionadded:: 1.1
+
 .. module:: sphinx.builders.changes
 .. class:: ChangesBuilder
 
diff --git a/doc/conf.py b/doc/conf.py
index ee94ed9e..a1d0e8ce 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -44,6 +44,7 @@ latex_logo = '_static/sphinx.png'
 latex_elements = {
     'fontpkg': '\\usepackage{palatino}',
 }
+latex_show_urls = 'footnote'
 
 autodoc_member_order = 'groupwise'
 todo_include_todos = True
@@ -63,6 +64,12 @@ man_pages = [
      'template generator', '', 1),
 ]
 
+texinfo_documents = [
+    ('contents', 'sphinx', 'Sphinx Documentation', 'Georg Brandl',
+     'Sphinx', 'The Sphinx documentation builder.', 'Documentation tools',
+     1),
+]
+
 # We're not using intersphinx right now, but if we did, this would be part of
 # the mapping:
 intersphinx_mapping = {'python': ('http://docs.python.org/dev', None)}
diff --git a/doc/config.rst b/doc/config.rst
index 80464768..a1f550dd 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -143,20 +143,6 @@ General configuration
    .. deprecated:: 1.0
       Use :confval:`exclude_patterns` instead.
 
-.. confval:: locale_dirs
-
-   .. versionadded:: 0.5
-
-   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 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 ``[]``.
-
 .. confval:: templates_path
 
    A list of paths that contain extra templates (or templates that overwrite
@@ -272,39 +258,6 @@ Project information
    If you don't need the separation provided between :confval:`version` and
    :confval:`release`, just set them both to the same value.
 
-.. confval:: language
-
-   The code for the language the docs are written in.  Any text automatically
-   generated by Sphinx will be in that language.  Also, in the LaTeX builder, a
-   suitable language will be selected as an option for the *Babel* package.
-   Default is ``None``, which means that no translation will be done.
-
-   .. versionadded:: 0.5
-
-   Currently supported languages are:
-
-   * ``bn`` -- Bengali
-   * ``ca`` -- Catalan
-   * ``cs`` -- Czech
-   * ``da`` -- Danish
-   * ``de`` -- German
-   * ``en`` -- English
-   * ``es`` -- Spanish
-   * ``fi`` -- Finnish
-   * ``fr`` -- French
-   * ``hr`` -- Croatian
-   * ``it`` -- Italian
-   * ``lt`` -- Lithuanian
-   * ``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
              today_fmt
 
@@ -380,6 +333,69 @@ Project information
    .. versionadded:: 1.0
 
 
+.. _intl-options:
+
+Options for internationalization
+--------------------------------
+
+These options influence Sphinx' *Native Language Support*.  See the
+documentation on :ref:`intl` for details.
+
+.. confval:: language
+
+   The code for the language the docs are written in.  Any text automatically
+   generated by Sphinx will be in that language.  Also, Sphinx will try to
+   substitute individual paragraphs from your documents with the translation
+   sets obtained from :confval:`locale_dirs`.  In the LaTeX builder, a suitable
+   language will be selected as an option for the *Babel* package.  Default is
+   ``None``, which means that no translation will be done.
+
+   .. versionadded:: 0.5
+
+   Currently supported languages by Sphinx are:
+
+   * ``bn`` -- Bengali
+   * ``ca`` -- Catalan
+   * ``cs`` -- Czech
+   * ``da`` -- Danish
+   * ``de`` -- German
+   * ``en`` -- English
+   * ``es`` -- Spanish
+   * ``fa`` -- Iranian
+   * ``fi`` -- Finnish
+   * ``fr`` -- French
+   * ``hr`` -- Croatian
+   * ``it`` -- Italian
+   * ``lt`` -- Lithuanian
+   * ``nl`` -- Dutch
+   * ``pl`` -- Polish
+   * ``pt_BR`` -- Brazilian Portuguese
+   * ``ru`` -- Russian
+   * ``sl`` -- Slovenian
+   * ``sv`` -- Swedish
+   * ``tr`` -- Turkish
+   * ``uk_UA`` -- Ukrainian
+   * ``zh_CN`` -- Simplified Chinese
+   * ``zh_TW`` -- Traditional Chinese
+
+.. confval:: locale_dirs
+
+   .. versionadded:: 0.5
+
+   Directories in which to search for additional message catalogs (see
+   :confval:`language`), relative to the source directory.  The directories on
+   this path are searched by the standard :mod:`gettext` module.
+
+   Internal messages are fetched from 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 text domain of
+   individual documents depends on their docname if they are top-level project
+   files and on their base directory otherwise.
+
+   The default is ``[]``.
+
+
 .. _html-options:
 
 Options for HTML output
@@ -483,13 +499,19 @@ that use Sphinx' HTMLWriter class.
 
 .. confval:: html_add_permalinks
 
-   If true, Sphinx will add "permalinks" for each heading and description
-   environment as paragraph signs that become visible when the mouse hovers over
-   them.  Default: ``True``.
+   Sphinx will add "permalinks" for each heading and description environment as
+   paragraph signs that become visible when the mouse hovers over them.
+
+   This value determines the text for the permalink; it defaults to ``"¶"``.
+   Set it to ``None`` or the empty string to disable permalinks.
 
    .. versionadded:: 0.6
       Previously, this was always activated.
 
+   .. versionchanged:: 1.1
+      This can now be a string to select the actual text of the link.
+      Previously, only boolean values were accepted.
+
 .. confval:: html_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to
@@ -672,6 +694,38 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 1.0
 
+.. confval:: html_search_language
+
+   Language to be used for generating the HTML full-text search index.  This
+   defaults to the global language selected with :confval:`language`.  If there
+   is no support for this language, ``"en"`` is used which selects the English
+   language.
+
+   Support is present for these languages:
+
+   * ``en`` -- English
+   * ``ja`` -- Japanese
+
+   .. versionadded:: 1.1
+
+.. confval:: html_search_options
+
+   A dictionary with options for the search language support, empty by default.
+   The meaning of these options depends on the language selected.
+
+   The English support has no options.
+
+   The Japanese support has these options:
+
+   * ``type`` -- ``'mecab'`` or ``'default'`` (selects either MeCab or
+     TinySegmenter word splitter algorithm)
+   * ``dic_enc`` -- the encoding for the MeCab algorithm
+   * ``dict`` -- the dictionary to use for the MeCab algorithm
+   * ``lib`` -- the library name for finding the MeCab library via ctypes if the
+     Python binding is not installed
+
+   .. versionadded:: 1.1
+
 .. confval:: htmlhelp_basename
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.
@@ -743,6 +797,22 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    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_cover
+
+   The cover page information.  This is a tuple containing the filenames of
+   the cover image and the html template.  The rendered html cover page is
+   inserted as the first item in the spine in :file:`content.opf`.  If the
+   template filename is empty, no html cover page is created.  No cover at all
+   is created if the tuple is empty.  Examples::
+
+      epub_cover = ('_static/cover.png', 'epub-cover.html')
+      epub_cover = ('_static/cover.png', '')
+      epub_cover = ()
+
+   The default value is ``()``.
+
+   .. versionadded:: 1.1
+
 .. confval:: epub_pre_files
 
    Additional files that should be inserted before the text generated by
@@ -780,6 +850,7 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    a chapter, but can be confusing because it mixes entries of differnet
    depth in one list.  The default value is ``True``.
 
+
 .. _latex-options:
 
 Options for LaTeX output
@@ -862,10 +933,18 @@ These options influence LaTeX output.
 
 .. confval:: latex_show_urls
 
-   If true, add URL addresses after links.  This is very useful for printed
-   copies of the manual.  Default is ``False``.
+   Control whether to display URL addresses.  This is very useful for printed
+   copies of the manual.  The setting can have the following values:
+
+   * ``'no'`` -- do not display URLs (default)
+   * ``'footnote'`` -- display URLs in footnotes
+   * ``'inline'`` -- display URLs inline in parentheses
 
    .. versionadded:: 1.0
+   .. versionchanged:: 1.1
+      This value is now a string; previously it was a boolean value, and a true
+      value selected the ``'inline'`` display.  For backwards compatibility,
+      ``True`` is still accepted.
 
 .. confval:: latex_elements
 
@@ -978,6 +1057,37 @@ These options influence LaTeX output.
       Use the ``'pointsize'`` key in the :confval:`latex_elements` value.
 
 
+.. _text-options:
+
+Options for text output
+-----------------------
+
+These options influence text output.
+
+.. confval:: text_newlines
+
+   Determines which end-of-line character(s) are used in text output.
+
+   * ``'unix'``: use Unix-style line endings (``\n``)
+   * ``'windows'``: use Windows-style line endings (``\r\n``)
+   * ``'native'``: use the line ending style of the platform the documentation
+     is built on
+
+   Default: ``'unix'``.
+
+   .. versionadded:: 1.1
+
+.. confval:: text_sectionchars
+
+   A string of 7 characters that should be used for underlining sections.
+   The first character is used for first-level headings, the second for
+   second-level headings and so on.
+
+   The default is ``'*=-~"+`'``.
+
+   .. versionadded:: 1.1
+
+
 .. _man-options:
 
 Options for manual page output
@@ -1000,14 +1110,121 @@ These options influence manual page output.
      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.
+   * *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
 
+.. confval:: man_show_urls
+
+   If true, add URL addresses after links.  Default is ``False``.
+
+   .. versionadded:: 1.1
+
+
+.. _texinfo-options:
+
+Options for Texinfo output
+--------------------------
+
+These options influence Texinfo output.
+
+.. confval:: texinfo_documents
+
+   This value determines how to group the document tree into Texinfo source
+   files.  It must be a list of tuples ``(startdocname, targetname, title,
+   author, dir_entry, description, category, toctree_only)``, where the items
+   are:
+
+   * *startdocname*: document name that is the "root" of the Texinfo file.  All
+     documents referenced by it in TOC trees will be included in the Texinfo
+     file too.  (If you want only one Texinfo file, use your
+     :confval:`master_doc` here.)
+   * *targetname*: file name (no extension) of the Texinfo file in the output
+     directory.
+   * *title*: Texinfo document title.  Can be empty to use the title of the
+     *startdoc*.
+   * *author*: Author for the Texinfo document.  Use ``\and`` to separate
+     multiple authors, as in: ``'John \and Sarah'``.
+   * *dir_entry*: The name that will appear in the top-level ``DIR`` menu file.
+   * *description*: Descriptive text to appear in the top-level ``DIR`` menu
+     file.
+   * *category*: Specifies the section which this entry will appear in the
+     top-level ``DIR`` menu file.
+   * *toctree_only*: Must be ``True`` or ``False``.  If ``True``, the *startdoc*
+     document itself is not included in the output, only the documents
+     referenced by it via TOC trees.  With this option, you can put extra stuff
+     in the master document that shows up in the HTML, but not the Texinfo
+     output.
+
+   .. versionadded:: 1.1
+
+
+.. confval:: texinfo_appendices
+
+   A list of document names to append as an appendix to all manuals.
+
+   .. versionadded:: 1.1
+
+
+.. confval:: texinfo_elements
+
+   A dictionary that contains Texinfo snippets that override those Sphinx
+   usually puts into the generated ``.texi`` files.
+
+   * Keys that you may want to override include:
+
+     ``'paragraphindent'``
+        Number of spaces to indent the first line of each paragraph, default
+        ``2``.  Specify ``0`` for no indentation.
+
+     ``'exampleindent'``
+        Number of spaces to indent the lines for examples or literal blocks,
+        default ``4``.  Specify ``0`` for no indentation.
+
+     ``'preamble'``
+        Text inserted as is near the beginning of the file.
+
+   * Keys that are set by other options and therefore should not be overridden
+     are:
+
+     ``'filename'``
+     ``'title'``
+     ``'direntry'``
+
+   .. versionadded:: 1.1
+
+
+Options for the linkcheck builder
+---------------------------------
+
+.. confval:: linkcheck_ignore
+
+   A list of regular expressions that match URIs that should not be checked
+   when doing a ``linkcheck`` build.  Example::
+
+      linkcheck_ignore = [r'http://localhost:\d+/']
+
+   .. versionadded:: 1.1
+
+.. confval:: linkcheck_timeout
+
+   A timeout value, in seconds, for the linkcheck builder.  **Only works in
+   Python 2.6 and higher.**  The default is to use Python's global socket
+   timeout.
+
+   .. versionadded:: 1.1
+
+.. confval:: linkcheck_workers
+
+   The number of worker threads to use when checking links.  Default is 5
+   threads.
+
+   .. versionadded:: 1.1
+
 
 .. rubric:: Footnotes
 
diff --git a/doc/contents.rst b/doc/contents.rst
index 079f93f2..3bbc2835 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -14,9 +14,11 @@ Sphinx documentation contents
    domains
    builders
    config
+   intl
    theming
    templating
    extensions
+   websupport
 
    faq
    glossary
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 302013da..d43a90eb 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -76,9 +76,9 @@ the following public API:
 
    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:
+   ``'html'``, ``'latex'``, ``'text'``, ``'man'``, ``'texinfo'``, 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
 
@@ -287,6 +287,15 @@ the following public API:
 
    .. versionadded:: 0.6
 
+.. method:: Sphinx.add_search_language(cls)
+
+   Add *cls*, which must be a subclass of :class:`sphinx.search.SearchLanguage`,
+   as a support language for building the HTML full-text search index.  The
+   class must have a *lang* attribute that indicates the language it should be
+   used for.  See :confval:`html_search_language`.
+
+   .. versionadded:: 1.1
+
 .. method:: Sphinx.connect(event, callback)
 
    Register *callback* to be called when *event* is emitted.  For details on
@@ -344,6 +353,15 @@ registered event handlers.
    Emitted when the builder object has been created.  It is available as
    ``app.builder``.
 
+.. event:: env-get-outdated (app, env, added, changed, removed)
+
+   Emitted when the environment determines which source files have changed and
+   should be re-read.  *added*, *changed* and *removed* are sets of docnames
+   that the environment has determined.  You can return a list of docnames to
+   re-read in addition to these.
+
+   .. versionadded:: 1.1
+
 .. event:: env-purge-doc (app, env, docname)
 
    Emitted when all traces of a source file should be cleaned from the
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index a1d9d98f..6c4a147a 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -93,8 +93,8 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
         .. autoclass:: Noodle
            :members: eat, slurp
 
-   * If you want to make the ``members`` option the default, see
-     :confval:`autodoc_default_flags`.
+   * If you want to make the ``members`` option (or other flag options described
+     below) the default, see :confval:`autodoc_default_flags`.
 
    * Members without docstrings will be left out, unless you give the
      ``undoc-members`` flag option::
@@ -103,6 +103,23 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
            :members:
            :undoc-members:
 
+   * "Private" members (that is, those named like ``_private`` or ``__private``)
+     will be included if the ``private-members`` flag option is given.
+
+     .. versionadded:: 1.1
+
+   * Python "special" members (that is, those named like ``__special__``) will
+     be included if the ``special-members`` flag option is given::
+
+        .. autoclass:: my.Class
+           :members:
+           :private-members:
+           :special-members:
+
+     would document both "private" and "special" members of the class.
+
+     .. versionadded:: 1.1
+
    * For classes and exceptions, members inherited from base classes will be
      left out, unless you give the ``inherited-members`` flag option, in
      addition to ``members``::
@@ -152,8 +169,8 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
      .. versionadded:: 0.5
 
-   * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` option
-     that can be used to override the global value of
+   * :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.
 
      .. versionadded:: 0.6
@@ -173,9 +190,9 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
 
 .. rst:directive:: autofunction
-               autodata
-               automethod
-               autoattribute
+                   autodata
+                   automethod
+                   autoattribute
 
    These work exactly like :rst:dir:`autoclass` etc., but do not offer the options
    used for automatic member documentation.
@@ -183,16 +200,23 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
    For module data members and class attributes, documentation can either be put
    into a special-formatted comment *before* the attribute definition, or in a
    docstring *after* the definition.  This means that in the following class
-   definition, both attributes can be autodocumented::
+   definition, all attributes can be autodocumented::
 
       class Foo:
           """Docstring for class Foo."""
 
-          #: Doc comment for attribute Foo.bar.
+          #: Doc comment for class attribute Foo.bar.
           bar = 1
 
           baz = 2
-          """Docstring for attribute Foo.baz."""
+          """Docstring for class attribute Foo.baz."""
+
+          def __init__(self):
+              #: Doc comment for instance attribute qux.
+              self.qux = 3
+
+              self.spam = 4
+              """Docstring for instance attribute spam."""
 
    .. versionchanged:: 0.6
       :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract docstrings.
@@ -246,7 +270,8 @@ There are also new config values that you can set:
 
    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'``.
+   ``'undoc-members'``, ``'private-members'``, ``'special-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.
@@ -260,6 +285,20 @@ There are also new config values that you can set:
 
    .. versionadded:: 1.0
 
+.. confval:: autodoc_docstring_signature
+
+   Functions imported from C modules cannot be introspected, and therefore the
+   signature for such functions cannot be automatically determined.  However, it
+   is an often-used convention to put the signature into the first line of the
+   function's docstring.
+
+   If this boolean value is set to ``True`` (which is the default), autodoc will
+   look at the first line of the docstring for functions and methods, and if it
+   looks like a signature, use the line as the signature and remove it from the
+   docstring content.
+
+   .. versionadded:: 1.1
+
 
 Docstring preprocessing
 -----------------------
diff --git a/doc/ext/coverage.rst b/doc/ext/coverage.rst
index 13294f8b..839478fe 100644
--- a/doc/ext/coverage.rst
+++ b/doc/ext/coverage.rst
@@ -14,6 +14,7 @@ This extension features one additional builder, the :class:`CoverageBuilder`.
 
 .. todo:: Write this section.
 
+
 Several new configuration values can be used to specify what the builder
 should check:
 
@@ -28,3 +29,16 @@ should check:
 .. confval:: coverage_c_regexes
 
 .. confval:: coverage_ignore_c_items
+
+.. confval:: coverage_write_headline
+
+   Set to ``False`` to not write headlines.
+
+   .. versionadded:: 1.1
+
+.. confval:: coverage_skip_undoc_in_source
+
+   Skip objects that are not documented in the source with a docstring.
+   ``False`` by default.
+
+   .. versionadded:: 1.1
diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst
index 20e747de..c884a10d 100644
--- a/doc/ext/doctest.rst
+++ b/doc/ext/doctest.rst
@@ -45,6 +45,14 @@ names.
    but executed before the doctests of the group(s) it belongs to.
 
 
+.. rst:directive:: .. testcleanup:: [group]
+
+   A cleanup code block.  This code is not shown in the output for other
+   builders, but executed after the doctests of the group(s) it belongs to.
+
+   .. versionadded:: 1.1
+
+
 .. rst:directive:: .. doctest:: [group]
 
    A doctest-style code block.  You can use standard :mod:`doctest` flags for
@@ -181,6 +189,14 @@ There are also these config values for customizing the doctest extension:
 
    .. versionadded:: 0.6
 
+.. confval:: doctest_global_cleanup
+
+   Python code that is treated like it were put in a ``testcleanup`` directive
+   for *every* file that is tested, and for every group.  You can use this to
+   e.g. remove any temporary files that the tests leave behind.
+
+   .. versionadded:: 1.1
+
 .. confval:: doctest_test_doctest_blocks
 
    If this is a nonempty string (the default is ``'default'``), standard reST
diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst
index 3741cec6..3a6d7c30 100644
--- a/doc/ext/graphviz.rst
+++ b/doc/ext/graphviz.rst
@@ -29,6 +29,17 @@ It adds these directives:
    :confval:`graphviz_output_format`).  In LaTeX output, the code will be
    rendered to an embeddable PDF file.
 
+   You can also embed external dot files, by giving the file name as an
+   argument to :rst:dir:`graphviz` and no additional content::
+
+      .. graphviz:: external.dot
+
+   As for all file references in Sphinx, if the filename is absolute, it is
+   taken as relative to the source directory.
+
+   .. versionchanged:: 1.1
+      Added support for external files.
+
 
 .. rst:directive:: graph
 
@@ -61,6 +72,11 @@ It adds these directives:
    alternate text for HTML output.  If not given, the alternate text defaults to
    the graphviz code.
 
+.. versionadded:: 1.1
+   All three directives support an ``inline`` flag that controls
+   paragraph breaks in the output.  When set, the graph is inserted
+   into the current paragraph.  If the flag is not given, paragraph
+   breaks are introduced before and after the image (the default).
 
 There are also these new config values:
 
diff --git a/doc/ext/math.rst b/doc/ext/math.rst
index f2896c39..ae91875d 100644
--- a/doc/ext/math.rst
+++ b/doc/ext/math.rst
@@ -171,20 +171,51 @@ There are various config values you can set to influence how the images are buil
    installed.  Therefore, the default for this option is ``False``.
 
 
-:mod:`sphinx.ext.jsmath` -- Render math via JavaScript
-------------------------------------------------------
+:mod:`sphinx.ext.mathjax` -- Render math via JavaScript
+-------------------------------------------------------
 
-.. module:: sphinx.ext.jsmath
-   :synopsis: Render math via JavaScript.
+.. module:: sphinx.ext.mathjax
+   :synopsis: Render math using JavaScript via MathJax.
+
+.. versionadded:: 1.1
 
 This extension puts math as-is into the HTML files.  The JavaScript package
-jsMath_ is then loaded and transforms the LaTeX markup to readable math live in
+MathJax_ is then loaded and transforms the LaTeX markup to readable math live in
 the browser.
 
-Because jsMath (and the necessary fonts) is very large, it is not included in
+Because MathJax (and the necessary fonts) is very large, it is not included in
 Sphinx.  You must install it yourself, and give Sphinx its path in this config
 value:
 
+.. confval:: mathjax_path
+
+   The path to the JavaScript file to include in the HTML files in order to load
+   JSMath.  There is no default.
+
+   The path can be absolute or relative; if it is relative, it is relative to
+   the ``_static`` directory of the built docs.
+
+   For example, if you put JSMath into the static path of the Sphinx docs, this
+   value would be ``MathJax/MathJax.js``.  If you host more than one Sphinx
+   documentation set on one server, it is advisable to install MathJax in a
+   shared location.
+
+   You can also give a full ``http://`` URL.  Kevin Dunn maintains a MathJax
+   installation on a public server, which he offers for use by development and
+   production servers::
+
+      mathjax_path = 'http://mathjax.connectmv.com/MathJax.js'
+
+
+:mod:`sphinx.ext.jsmath` -- Render math via JavaScript
+------------------------------------------------------
+
+.. module:: sphinx.ext.jsmath
+   :synopsis: Render math using JavaScript via JSMath.
+
+This extension works just as the MathJax extension does, but uses the older
+package jsMath_.  It provides this config value:
+
 .. confval:: jsmath_path
 
    The path to the JavaScript file to include in the HTML files in order to load
@@ -200,6 +231,7 @@ value:
 
 
 .. _dvipng: http://savannah.nongnu.org/projects/dvipng/
+.. _MathJax: http://www.mathjax.org/
 .. _jsMath: http://www.math.union.edu/~dpvc/jsmath/
 .. _preview-latex package: http://www.gnu.org/software/auctex/preview-latex.html
 .. _AmSMath LaTeX package: http://www.ams.org/tex/amslatex.html
diff --git a/doc/faq.rst b/doc/faq.rst
index f53e79db..a0f00855 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -60,9 +60,11 @@ PyPI
    Sphinx documentation to the PyPI package documentation area at
    http://packages.python.org/.
 
-github pages
-   You'll have to opt out of processing your pages with the "Jekyll" preprocessor
-   as described in http://pages.github.com/#using_jekyll_for_complex_layouts.
+GitHub Pages
+   Directories starting with underscores are ignored by default which breaks
+   static files in Sphinx.  GitHub's preprocessor can be `disabled
+   <https://github.com/blog/572-bypassing-jekyll-on-github-pages>`_ to support
+   Sphinx HTML output properly.
 
 Google Analytics
    You can use a custom ``layout.html`` template, like this:
@@ -147,3 +149,109 @@ some notes:
 .. _Calibre: http://calibre-ebook.com/
 .. _FBreader: http://www.fbreader.org/
 .. _Bookworm: http://bookworm.oreilly.com/
+
+
+.. _texinfo-faq:
+
+Texinfo info
+------------
+
+The Texinfo builder is currently in an experimental stage but has successfully
+been used to build the documentation for both Sphinx and Python.  The intended
+use of this builder is to generate Texinfo that is then processed into Info
+files.
+
+There are two main programs for reading Info files, ``info`` and GNU Emacs.  The
+``info`` program has less features but is available in most Unix environments
+and can be quickly accessed from the terminal.  Emacs provides better font and
+color display and supports extensive customization (of course).
+
+
+.. _texinfo-links:
+
+Displaying Links
+~~~~~~~~~~~~~~~~
+
+One noticeable problem you may encounter with the generated Info files is how
+references are displayed.  If you read the source of an Info file, a reference
+to this section would look like::
+
+    * note Displaying Links: target-id
+
+In the stand-alone reader, ``info``, references are displayed just as they
+appear in the source.  Emacs, on the other-hand, will by default replace
+``\*note:`` with ``see`` and hide the ``target-id``.  For example:
+
+    :ref:`texinfo-links`
+
+The exact behavior of how Emacs displays references is dependent on the variable
+``Info-hide-note-references``.  If set to the value of ``hide``, Emacs will hide
+both the ``\*note:`` part and the ``target-id``.  This is generally the best way
+to view Sphinx-based documents since they often make frequent use of links and
+do not take this limitation into account.  However, changing this variable
+affects how all Info documents are displayed and most due take this behavior
+into account.
+
+If you want Emacs to display Info files produced by Sphinx using the value
+``hide`` for ``Info-hide-note-references`` and the default value for all other
+Info files, try adding the following Emacs Lisp code to your start-up file,
+``~/.emacs.d/init.el``.
+
+::
+
+   (defadvice info-insert-file-contents (after
+                                         sphinx-info-insert-file-contents
+                                         activate)
+     "Hack to make `Info-hide-note-references' buffer-local and
+   automatically set to `hide' iff it can be determined that this file
+   was created from a Texinfo file generated by Docutils or Sphinx."
+     (set (make-local-variable 'Info-hide-note-references)
+          (default-value 'Info-hide-note-references))
+     (save-excursion
+       (save-restriction
+         (widen) (goto-char (point-min))
+         (when (re-search-forward
+                "^Generated by \\(Sphinx\\|Docutils\\)"
+                (save-excursion (search-forward "^_" nil t)) t)
+           (set (make-local-variable 'Info-hide-note-references)
+                'hide)))))
+
+
+Notes
+~~~~~
+
+The following notes may be helpful if you want to create Texinfo files:
+
+- Each section corresponds to a different ``node`` in the Info file.
+
+- Some characters cannot be properly escaped in menu entries and xrefs.  The
+  following characters are replaced by spaces in these contexts: ``@``, ``{``,
+  ``}``, ``.``, ``,``, and ``:``.
+
+- In the HTML and Tex output, the word ``see`` is automatically inserted before
+  all xrefs.
+
+- Links to external Info files can be created using the somewhat official URI
+  scheme ``info``.  For example::
+
+     info:Texinfo#makeinfo_options
+
+  which produces:
+
+     info:Texinfo#makeinfo_options
+
+- Inline markup appears as follows in Info:
+
+  * strong -- \*strong\*
+  * emphasis -- _emphasis_
+  * literal -- \`literal'
+
+  It is possible to change this behavior using the Texinfo command
+  ``@definfoenclose``.  For example, to make inline markup more closely resemble
+  reST, add the following to your :file:`conf.py`::
+
+     texinfo_elements = {'preamble': """\
+     @definfoenclose strong,**,**
+     @definfoenclose emph,*,*
+     @definfoenclose code,`@w{}`,`@w{}`
+     """}
diff --git a/doc/glossary.rst b/doc/glossary.rst
index 2a82e20f..8bc393eb 100644
--- a/doc/glossary.rst
+++ b/doc/glossary.rst
@@ -23,7 +23,9 @@ Glossary
       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::
+      syntax looks like this:
+
+      .. sourcecode:: rst
 
          .. directivename:: argument ...
             :option: value
diff --git a/doc/intl.rst b/doc/intl.rst
new file mode 100644
index 00000000..3a9e32f2
--- /dev/null
+++ b/doc/intl.rst
@@ -0,0 +1,69 @@
+.. _intl:
+
+Internationalization
+====================
+
+.. versionadded:: 1.1
+
+Complementary to translations provided for Sphinx-generated messages such as
+navigation bars, Sphinx provides mechanisms facilitating *document* translations
+in itself.  See the :ref:`intl-options` for details on configuration.
+
+.. figure:: translation.png
+   :width: 100%
+
+   Workflow visualization of translations in Sphinx.  (The stick-figure is taken
+   from an `XKCD comic <http://xkcd.com/779/>`_.)
+
+**gettext** [1]_ is an established standard for internationalization and
+localization.  It naïvely maps messages in a program to a translated string.
+Sphinx uses these facilities to translate whole documents.
+
+Initially project maintainers have to collect all translatable strings (also
+referred to as *messages*) to make them known to translators.  Sphinx extracts
+these through invocation of ``sphinx-build -b gettext``.
+
+Every single element in the doctree will end up in a single message which
+results in lists being equally split into different chunks while large
+paragraphs will remain as coarsely-grained as they were in the original
+document.  This grants seamless document updates while still providing a little
+bit of context for translators in free-text passages.  It is the maintainer's
+task to split up paragraphs which are too large as there is no sane automated
+way to do that.
+
+After Sphinx successfully ran the
+:class:`~sphinx.builders.intl.MessageCatalogBuilder` you will find a collection
+of ``.pot`` files in your output directory.  These are **catalog templates**
+and contain messages in your original language *only*.
+
+They can be delivered to translators which will transform them to ``.po`` files
+--- so called **message catalogs** --- containing a mapping from the original
+messages to foreign-language strings.
+
+Gettext compiles them into a binary format known as **binary catalogs** through
+:program:`msgfmt` for efficiency reasons.  If you make these files discoverable
+with :confval:`locale_dirs` for your :confval:`language`, Sphinx will pick them
+up automatically.
+
+An example: you have a document ``usage.rst`` in your Sphinx project.  The
+gettext builder will put its messages into ``usage.pot``.  Image you have
+Spanish translations [2]_ on your hands in ``usage.po`` --- for your builds to
+be translated you need to follow these instructions:
+
+* Compile your message catalog to a locale directory, say ``translated``, so it
+  ends up in ``./translated/es/LC_MESSAGES/usage.mo`` in your source directory
+  (where ``es`` is the language code for Spanish.) ::
+
+        msgfmt "usage.po" -o "translated/es/LC_MESSAGES/usage.mo"
+
+* Set :confval:`locale_dirs` to ``["translated/"]``.
+* Set :confval:`language` to ``es`` (also possible via :option:`-D`).
+* Run your desired build.
+
+
+.. rubric:: Footnotes
+
+.. [1] See the `GNU gettext utilites
+       <http://www.gnu.org/software/gettext/manual/gettext.html#Introduction>`_
+       for details on that software suite.
+.. [2] Because nobody expects the Spanish Inquisition!
diff --git a/doc/intro.rst b/doc/intro.rst
index 1a39e266..caff141d 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -45,15 +45,19 @@ See the :ref:`pertinent section in the FAQ list <usingwith>`.
 Prerequisites
 -------------
 
-Sphinx needs at least **Python 2.4** to run, as well as the docutils_ and
-Jinja2_ libraries.  Sphinx should work with docutils version 0.5 or some
-(not broken) SVN trunk snapshot.  If you like to have source code highlighting
-support, you must also install the Pygments_ library.
+Sphinx needs at least **Python 2.4** or **Python 3.1** to run, as well as the
+docutils_ and Jinja2_ libraries.  Sphinx should work with docutils version 0.5
+or some (not broken) SVN trunk snapshot.  If you like to have source code
+highlighting support, you must also install the Pygments_ library.
+
+If you use **Python 2.4** you also need uuid_.
 
 .. _reStructuredText: http://docutils.sf.net/rst.html
 .. _docutils: http://docutils.sf.net/
 .. _Jinja2: http://jinja.pocoo.org/2/
 .. _Pygments: http://pygments.org/
+.. The given homepage is only a directory listing so I'm using the pypi site.
+.. _uuid: http://pypi.python.org/pypi/uuid/
 
 
 Usage
diff --git a/doc/invocation.rst b/doc/invocation.rst
index 6b8b9ee3..c8e9a61f 100644
--- a/doc/invocation.rst
+++ b/doc/invocation.rst
@@ -40,9 +40,16 @@ The :program:`sphinx-build` script has several options:
    **man**
       Build manual pages in groff format for UNIX systems.
 
+   **texinfo**
+      Build Texinfo files that can be processed into Info files using
+      :program:`makeinfo`.
+
    **text**
       Build plain text files.
 
+   **gettext**
+      Build gettext-style message catalogs (``.pot`` files).
+
    **doctest**
       Run all doctests in the documentation, if the :mod:`~sphinx.ext.doctest`
       extension is enabled.
diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst
index 4f90a6a7..69dd832f 100644
--- a/doc/markup/inline.rst
+++ b/doc/markup/inline.rst
@@ -321,6 +321,7 @@ in a different style:
    If you don't need the "variable part" indication, use the standard
    ````code```` instead.
 
+There is also an :rst:role:`index` role to generate index entries.
 
 The following roles generate external links:
 
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index 39109a58..95899ef3 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -64,6 +64,105 @@ Meta-information markup
    :confval:`show_authors` configuration value is True.
 
 
+Index-generating markup
+-----------------------
+
+Sphinx automatically creates index entries from all object descriptions (like
+functions, classes or attributes) like discussed in :ref:`domains`.
+
+However, there is also explicit markup 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.
+
+.. 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.
+
+   For example::
+
+      .. index::
+         single: execution; context
+         module: __main__
+         module: sys
+         triple: module; search; path
+
+      The execution context
+      ---------------------
+
+      ...
+
+   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 --
+   e.g. a heading, as in the example above.
+
+   The possible entry types are:
+
+   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).
+   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``.
+   see
+      ``see: entry; other`` creates an index entry that refers from ``entry`` to
+      ``other``.
+   seealso
+      Like ``see``, but inserts "see also" instead of "see".
+   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
+      are Python-specific and therefore deprecated.)
+
+   You can mark up "main" index entries by prefixing them with an exclamation
+   mark.  The references to "main" entries are emphasized in the generated
+   index.  For example, if two pages contain ::
+
+      .. index:: Python
+
+   and one page contains ::
+
+      .. index:: ! Python
+
+   then the backlink to the latter page is emphasized among the three backlinks.
+
+   For index directives containing only "single" entries, there is a shorthand
+   notation::
+
+      .. index:: BNF, grammar, syntax, notation
+
+   This creates four index entries.
+
+   .. versionchanged:: 1.1
+      Added ``see`` and ``seealso`` types, as well as marking main entries.
+
+.. rst:role:: index
+
+   While the :rst:dir:`index` directive is a block-level markup and links to the
+   beginning of the next paragraph, there is also a corresponding role that sets
+   the link target directly where it is used.
+
+   The content of the role can be a simple phrase, which is then kept in the
+   text and used as an index entry.  It can also be a combination of text and
+   index entry, styled like with explicit targets of cross-references.  In that
+   case, the "target" part can be a full entry as described for the directive
+   above.  For example::
+
+      This is a normal reST :index:`paragraph` that contains several
+      :index:`index entries <pair: index; entry>`.
+
+   .. versionadded:: 1.1
+
+
 .. _tags:
 
 Including content based on tags
diff --git a/doc/markup/para.rst b/doc/markup/para.rst
index ecc6b4a6..ced18d81 100644
--- a/doc/markup/para.rst
+++ b/doc/markup/para.rst
@@ -52,7 +52,7 @@ units as well as normal text:
    Similar to :rst:dir:`versionadded`, but describes when and what changed in
    the named feature in some way (new parameters, changed side effects, etc.).
 
-.. rst:directive:: .. deprecated:: vesion
+.. rst:directive:: .. deprecated:: version
 
    Similar to :rst:dir:`versionchanged`, but describes when the feature was
    deprecated.  An explanation can also be given, for example to inform the
@@ -112,6 +112,10 @@ units as well as normal text:
 
       .. centered:: LICENSE AGREEMENT
 
+   .. deprecated:: 1.1
+      This presentation-only directive is a legacy from older versions.  Use a
+      :rst:dir:`rst-class` directive instead and add an appropriate style.
+
 
 .. rst:directive:: hlist
 
@@ -144,76 +148,14 @@ For local tables of contents, use the standard reST :dudir:`contents directive
 <contents>`.
 
 
-Index-generating markup
------------------------
-
-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.
-
-.. 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.
-
-   For example::
-
-      .. index::
-         single: execution; context
-         module: __main__
-         module: sys
-         triple: module; search; path
-
-      The execution context
-      ---------------------
-
-      ...
-
-   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 --
-   e.g. a heading, as in the example above.
-
-   The possible entry types are:
-
-   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).
-   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``.
-   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
-      are Python-specific and therefore deprecated.)
-
-   For index directives containing only "single" entries, there is a shorthand
-   notation::
-
-      .. index:: BNF, grammar, syntax, notation
-
-   This creates four index entries.
-
-
 Glossary
 --------
 
 .. rst:directive:: .. glossary::
 
-   This directive must contain a reST definition list with terms and
-   definitions.  The definitions will then be referencable with the :rst:role:`term`
-   role.  Example::
+   This directive must contain a reST definition-list-like markup with terms and
+   definitions.  The definitions will then be referencable with the
+   :rst:role:`term` role.  Example::
 
       .. glossary::
 
@@ -227,10 +169,25 @@ Glossary
             The directory which, including its subdirectories, contains all
             source files for one Sphinx project.
 
+   In contrast to regular definition lists, *multiple* terms per entry are
+   allowed, and inline markup is allowed in terms.  You can link to all of the
+   terms.  For example::
+
+      .. glossary::
+
+         term 1
+         term 2
+            Definition of both terms.
+
+   (When the glossary is sorted, the first term determines the sort order.)
+
    .. versionadded:: 0.6
       You can now give the glossary directive a ``:sorted:`` flag that will
       automatically sort the entries alphabetically.
 
+   .. versionchanged:: 1.1
+      Now supports multiple terms and inline markup in terms.
+
 
 Grammar production displays
 ---------------------------
diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index 2c0a418a..0b6a46c1 100644
--- a/doc/markup/toctree.rst
+++ b/doc/markup/toctree.rst
@@ -41,6 +41,8 @@ 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.
 
+   **Entries**
+
    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
@@ -59,8 +61,10 @@ tables of contents.  The ``toctree`` directive is the central element.
    You can also add external links, by giving an HTTP URL instead of a document
    name.
 
+   **Section numbering**
+
    If you want to have section numbers even in HTML output, give the toctree a
-   ``numbered`` flag option.  For example::
+   ``numbered`` option.  For example::
 
       .. toctree::
          :numbered:
@@ -71,6 +75,11 @@ 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).
 
+   Numbering up to a specific depth is also possible, by giving the depth as a
+   numeric argument to ``numbered``.
+
+   **Additional options**
+
    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::
 
@@ -133,6 +142,9 @@ tables of contents.  The ``toctree`` directive is the central element.
    .. versionchanged:: 1.0
       Added "titlesonly" option.
 
+   .. versionchanged:: 1.1
+      Added numeric argument to "numbered".
+
 
 Special names
 -------------
diff --git a/doc/themes/fullsize/pyramid.png b/doc/themes/fullsize/pyramid.png
new file mode 100644
index 00000000..429a8b7e
--- /dev/null
+++ b/doc/themes/fullsize/pyramid.png
diff --git a/doc/themes/pyramid.png b/doc/themes/pyramid.png
new file mode 100644
index 00000000..b16095c9
--- /dev/null
+++ b/doc/themes/pyramid.png
diff --git a/doc/theming.rst b/doc/theming.rst
index 716eb50a..216118c1 100644
--- a/doc/theming.rst
+++ b/doc/theming.rst
@@ -69,9 +69,9 @@ Builtin themes
 |                    |                    |
 | *traditional*      | *nature*           |
 +--------------------+--------------------+
-| |haiku|            |                    |
+| |haiku|            | |pyramid|          |
 |                    |                    |
-| *haiku*            |                    |
+| *haiku*            | *pyramid*          |
 +--------------------+--------------------+
 
 .. |default|     image:: themes/default.png
@@ -81,6 +81,7 @@ Builtin themes
 .. |traditional| image:: themes/traditional.png
 .. |nature|      image:: themes/nature.png
 .. |haiku|       image:: themes/haiku.png
+.. |pyramid|     image:: themes/pyramid.png
 
 Sphinx comes with a selection of themes to choose from.
 
@@ -144,8 +145,7 @@ These themes are:
   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:
+  <http://jinja.pocoo.org/>`_.  The following color options are available:
 
   - **headerbordercolor**
   - **subheadlinecolor**
@@ -178,6 +178,9 @@ These themes are:
 * **nature** -- A greenish theme.  There are currently no options beyond
   *nosidebar*.
 
+* **pyramid** -- A theme from the Pyramid web framework project, designed by
+  Blais Laflamme.  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:
@@ -206,7 +209,7 @@ name), containing the following:
 * A :file:`theme.conf` file, see below.
 * HTML templates, if needed.
 * A ``static/`` directory containing any static files that will be copied to the
-  output statid directory on build.  These can be images, styles, script files.
+  output static directory on build.  These can be images, styles, script files.
 
 The :file:`theme.conf` file is in INI format [1]_ (readable by the standard
 Python :mod:`ConfigParser` module) and has the following structure:
diff --git a/doc/translation.png b/doc/translation.png
new file mode 100644
index 00000000..aa368b67
--- /dev/null
+++ b/doc/translation.png
diff --git a/doc/web/api.rst b/doc/web/api.rst
new file mode 100644
index 00000000..070cd3a2
--- /dev/null
+++ b/doc/web/api.rst
@@ -0,0 +1,65 @@
+.. _websupportapi:
+
+.. currentmodule:: sphinx.websupport
+
+The WebSupport Class
+====================
+
+.. class:: WebSupport
+
+   The main API class for the web support package.  All interactions with the
+   web support package should occur through this class.
+
+   The class takes the following keyword arguments:
+
+   srcdir
+      The directory containing reStructuredText source files.
+
+   builddir
+      The directory that build data and static files should be placed in.  This
+      should be used when creating a :class:`WebSupport` object that will be
+      used to build data.
+
+   datadir
+      The directory that the web support data is in.  This should be used when
+      creating a :class:`WebSupport` object that will be used to retrieve data.
+
+   search
+       This may contain either a string (e.g. 'xapian') referencing a built-in
+       search adapter to use, or an instance of a subclass of
+       :class:`~.search.BaseSearch`.
+
+   storage
+       This may contain either a string representing a database uri, or an
+       instance of a subclass of :class:`~.storage.StorageBackend`.  If this is
+       not provided, a new sqlite database will be created.
+
+   moderation_callback
+       A callable to be called when a new comment is added that is not
+       displayed.  It must accept one argument: a dictionary representing the
+       comment that was added.
+
+   staticdir
+       If static files are served from a location besides ``'/static'``, this
+       should be a string with the name of that location
+       (e.g. ``'/static_files'``).
+
+   docroot
+       If the documentation is not served from the base path of a URL, this
+       should be a string specifying that path (e.g. ``'docs'``).
+
+
+Methods
+~~~~~~~
+
+.. automethod:: sphinx.websupport.WebSupport.build
+
+.. automethod:: sphinx.websupport.WebSupport.get_document
+
+.. automethod:: sphinx.websupport.WebSupport.get_data
+
+.. automethod:: sphinx.websupport.WebSupport.add_comment
+
+.. automethod:: sphinx.websupport.WebSupport.process_vote
+
+.. automethod:: sphinx.websupport.WebSupport.get_search_results
diff --git a/doc/web/quickstart.rst b/doc/web/quickstart.rst
new file mode 100644
index 00000000..bd0f71a7
--- /dev/null
+++ b/doc/web/quickstart.rst
@@ -0,0 +1,254 @@
+.. _websupportquickstart:
+
+Web Support Quick Start
+=======================
+
+Building Documentation Data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To make use of the web support package in your application you'll need to build
+the data it uses.  This data includes pickle files representing documents,
+search indices, and node data that is used to track where comments and other
+things are in a document.  To do this you will need to create an instance of the
+:class:`~.WebSupport` class and call its :meth:`~.WebSupport.build` method::
+
+   from sphinx.websupport import WebSupport
+
+   support = WebSupport(srcdir='/path/to/rst/sources/',
+                        builddir='/path/to/build/outdir',
+                        search='xapian')
+
+   support.build()
+
+This will read reStructuredText sources from `srcdir` and place the necessary
+data in `builddir`.  The `builddir` will contain two sub-directories: one named
+"data" that contains all the data needed to display documents, search through
+documents, and add comments to documents.  The other directory will be called
+"static" and contains static files that should be served from "/static".
+
+.. note::
+
+   If you wish to serve static files from a path other than "/static", you can
+   do so by providing the *staticdir* keyword argument when creating the
+   :class:`~.WebSupport` object.
+
+
+Integrating Sphinx Documents Into Your Webapp
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that the data is built, it's time to do something useful with it.  Start off
+by creating a :class:`~.WebSupport` object for your application::
+
+   from sphinx.websupport import WebSupport
+
+   support = WebSupport(datadir='/path/to/the/data',
+                        search='xapian')
+
+You'll only need one of these for each set of documentation you will be working
+with.  You can then call it's :meth:`~.WebSupport.get_document` method to access
+individual documents::
+
+   contents = support.get_document('contents')
+
+This will return a dictionary containing the following items:
+
+* **body**: The main body of the document as HTML
+* **sidebar**: The sidebar of the document as HTML
+* **relbar**: A div containing links to related documents
+* **title**: The title of the document
+* **css**: Links to css files used by Sphinx
+* **js**: Javascript containing comment options
+
+This dict can then be used as context for templates.  The goal is to be easy to
+integrate with your existing templating system.  An example using `Jinja2
+<http://jinja.pocoo.org/2/>`_ is:
+
+.. sourcecode:: html+jinja
+
+   {%- extends "layout.html" %}
+
+   {%- block title %}
+       {{ document.title }}
+   {%- endblock %}
+
+   {% block css %}
+       {{ super() }}
+       {{ document.css|safe }}
+       <link rel="stylesheet" href="/static/websupport-custom.css" type="text/css">
+   {% endblock %}
+
+   {%- block js %}
+       {{ super() }}
+       {{ document.js|safe }}
+   {%- endblock %}
+
+   {%- block relbar %}
+       {{ document.relbar|safe }}
+   {%- endblock %}
+
+   {%- block body %}
+       {{ document.body|safe }}
+   {%- endblock %}
+
+   {%- block sidebar %}
+       {{ document.sidebar|safe }}
+   {%- endblock %}
+
+
+Authentication
+--------------
+
+To use certain features such as voting, it must be possible to authenticate
+users.  The details of the authentication are left to your application.  Once a
+user has been authenticated you can pass the user's details to certain
+:class:`~.WebSupport` methods using the *username* and *moderator* keyword
+arguments.  The web support package will store the username with comments and
+votes.  The only caveat is that if you allow users to change their username you
+must update the websupport package's data::
+
+   support.update_username(old_username, new_username)
+
+*username* should be a unique string which identifies a user, and *moderator*
+should be a boolean representing whether the user has moderation privilieges.
+The default value for *moderator* is *False*.
+
+An example `Flask <http://flask.pocoo.org/>`_ function that checks whether a
+user is logged in and then retrieves a document is::
+
+   from sphinx.websupport.errors import *
+
+   @app.route('/<path:docname>')
+   def doc(docname):
+       username = g.user.name if g.user else ''
+       moderator = g.user.moderator if g.user else False
+       try:
+           document = support.get_document(docname, username, moderator)
+       except DocumentNotFoundError:
+           abort(404)
+       return render_template('doc.html', document=document)
+
+The first thing to notice is that the *docname* is just the request path.  This
+makes accessing the correct document easy from a single view.  If the user is
+authenticated, then the username and moderation status are passed along with the
+docname to :meth:`~.WebSupport.get_document`.  The web support package will then
+add this data to the ``COMMENT_OPTIONS`` that are used in the template.
+
+.. note::
+
+   This only works works if your documentation is served from your
+   document root. If it is served from another directory, you will
+   need to prefix the url route with that directory, and give the `docroot`
+   keyword argument when creating the web support object::
+
+      support = WebSupport(..., docroot='docs')
+
+      @app.route('/docs/<path:docname>')
+
+
+Performing Searches
+~~~~~~~~~~~~~~~~~~~
+
+To use the search form built-in to the Sphinx sidebar, create a function to
+handle requests to the url 'search' relative to the documentation root.  The
+user's search query will be in the GET parameters, with the key `q`.  Then use
+the :meth:`~sphinx.websupport.WebSupport.get_search_results` method to retrieve
+search results. In `Flask <http://flask.pocoo.org/>`_ that would be like this::
+
+   @app.route('/search')
+   def search():
+       q = request.args.get('q')
+       document = support.get_search_results(q)
+       return render_template('doc.html', document=document)
+
+Note that we used the same template to render our search results as we did to
+render our documents.  That's because :meth:`~.WebSupport.get_search_results`
+returns a context dict in the same format that :meth:`~.WebSupport.get_document`
+does.
+
+
+Comments & Proposals
+~~~~~~~~~~~~~~~~~~~~
+
+Now that this is done it's time to define the functions that handle the AJAX
+calls from the script.  You will need three functions.  The first function is
+used to add a new comment, and will call the web support method
+:meth:`~.WebSupport.add_comment`::
+
+   @app.route('/docs/add_comment', methods=['POST'])
+   def add_comment():
+       parent_id = request.form.get('parent', '')
+       node_id = request.form.get('node', '')
+       text = request.form.get('text', '')
+       proposal = request.form.get('proposal', '')
+       username = g.user.name if g.user is not None else 'Anonymous'
+       comment = support.add_comment(text, node_id='node_id',
+                                     parent_id='parent_id',
+                                     username=username, proposal=proposal)
+       return jsonify(comment=comment)
+
+You'll notice that both a `parent_id` and `node_id` are sent with the
+request. If the comment is being attached directly to a node, `parent_id`
+will be empty. If the comment is a child of another comment, then `node_id`
+will be empty. Then next function handles the retrieval of comments for a
+specific node, and is aptly named
+:meth:`~sphinx.websupport.WebSupport.get_data`::
+
+    @app.route('/docs/get_comments')
+    def get_comments():
+        username = g.user.name if g.user else None
+        moderator = g.user.moderator if g.user else False
+        node_id = request.args.get('node', '')
+        data = support.get_data(parent_id, user_id)
+        return jsonify(**data)
+
+The final function that is needed will call :meth:`~.WebSupport.process_vote`,
+and will handle user votes on comments::
+
+   @app.route('/docs/process_vote', methods=['POST'])
+   def process_vote():
+       if g.user is None:
+           abort(401)
+       comment_id = request.form.get('comment_id')
+       value = request.form.get('value')
+       if value is None or comment_id is None:
+           abort(400)
+       support.process_vote(comment_id, g.user.id, value)
+       return "success"
+
+
+Comment Moderation
+~~~~~~~~~~~~~~~~~~
+
+By default, all comments added through :meth:`~.WebSupport.add_comment` are
+automatically displayed.  If you wish to have some form of moderation, you can
+pass the `displayed` keyword argument::
+
+   comment = support.add_comment(text, node_id='node_id',
+                                 parent_id='parent_id',
+                                 username=username, proposal=proposal,
+                                 displayed=False)
+
+You can then create a new view to handle the moderation of comments.  It
+will be called when a moderator decides a comment should be accepted and
+displayed::
+
+   @app.route('/docs/accept_comment', methods=['POST'])
+   def accept_comment():
+       moderator = g.user.moderator if g.user else False
+       comment_id = request.form.get('id')
+       support.accept_comment(comment_id, moderator=moderator)
+       return 'OK'
+
+Rejecting comments happens via comment deletion.
+
+To perform a custom action (such as emailing a moderator) when a new comment is
+added but not displayed, you can pass callable to the :class:`~.WebSupport`
+class when instantiating your support object::
+
+   def moderation_callback(comment):
+       """Do something..."""
+
+   support = WebSupport(..., moderation_callback=moderation_callback)
+
+The moderation callback must take one argument, which will be the same comment
+dict that is returned by :meth:`add_comment`.
diff --git a/doc/web/searchadapters.rst b/doc/web/searchadapters.rst
new file mode 100644
index 00000000..7d8634f7
--- /dev/null
+++ b/doc/web/searchadapters.rst
@@ -0,0 +1,45 @@
+.. _searchadapters:
+
+.. currentmodule:: sphinx.websupport.search
+
+Search Adapters
+===============
+
+To create a custom search adapter you will need to subclass the
+:class:`BaseSearch` class.  Then create an instance of the new class and pass
+that as the `search` keyword argument when you create the :class:`~.WebSupport`
+object::
+
+   support = WebSupport(srcdir=srcdir,
+                        builddir=builddir,
+                        search=MySearch())
+
+For more information about creating a custom search adapter, please see the
+documentation of the :class:`BaseSearch` class below.
+
+.. class:: BaseSearch
+
+   Defines an interface for search adapters.
+
+
+BaseSearch Methods
+~~~~~~~~~~~~~~~~~~
+
+   The following methods are defined in the BaseSearch class. Some methods do
+   not need to be overridden, but some (:meth:`~BaseSearch.add_document` and
+   :meth:`~BaseSearch.handle_query`) must be overridden in your subclass. For a
+   working example, look at the built-in adapter for whoosh.
+
+.. automethod:: BaseSearch.init_indexing
+
+.. automethod:: BaseSearch.finish_indexing
+
+.. automethod:: BaseSearch.feed
+
+.. automethod:: BaseSearch.add_document
+
+.. automethod:: BaseSearch.query
+
+.. automethod:: BaseSearch.handle_query
+
+.. automethod:: BaseSearch.extract_context
diff --git a/doc/web/storagebackends.rst b/doc/web/storagebackends.rst
new file mode 100644
index 00000000..d191b43e
--- /dev/null
+++ b/doc/web/storagebackends.rst
@@ -0,0 +1,44 @@
+.. _storagebackends:
+
+.. currentmodule:: sphinx.websupport.storage
+
+Storage Backends
+================
+
+To create a custom storage backend you will need to subclass the
+:class:`StorageBackend` class.  Then create an instance of the new class and
+pass that as the `storage` keyword argument when you create the
+:class:`~.WebSupport` object::
+
+   support = WebSupport(srcdir=srcdir,
+                        builddir=builddir,
+                        storage=MyStorage())
+
+For more information about creating a custom storage backend, please see the
+documentation of the :class:`StorageBackend` class below.
+
+.. class:: StorageBackend
+
+   Defines an interface for storage backends.
+
+
+StorageBackend Methods
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. automethod:: StorageBackend.pre_build
+
+.. automethod:: StorageBackend.add_node
+
+.. automethod:: StorageBackend.post_build
+
+.. automethod:: StorageBackend.add_comment
+
+.. automethod:: StorageBackend.delete_comment
+
+.. automethod:: StorageBackend.get_data
+
+.. automethod:: StorageBackend.process_vote
+
+.. automethod:: StorageBackend.update_username
+
+.. automethod:: StorageBackend.accept_comment
diff --git a/doc/websupport.rst b/doc/websupport.rst
new file mode 100644
index 00000000..3ccae246
--- /dev/null
+++ b/doc/websupport.rst
@@ -0,0 +1,16 @@
+.. _websupport:
+
+Sphinx Web Support
+==================
+
+.. versionadded:: 1.1
+
+Sphinx provides a Python API to easily integrate Sphinx documentation into your
+web application.  To learn more read the :ref:`websupportquickstart`.
+
+.. toctree::
+
+   web/quickstart
+   web/api
+   web/searchadapters
+   web/storagebackends