merge pre-domain state with tip from 0.6

12 files changed, 356 insertions, 8 deletions

diff --git a/doc/builders.rst b/doc/builders.rst
index bee0094c..9b001105 100644
--- a/doc/builders.rst
+++ b/doc/builders.rst
@@ -36,6 +36,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionadded:: 0.6
 
+.. module:: sphinx.builders.htmlhelp
 .. class:: HTMLHelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
@@ -44,6 +45,24 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``htmlhelp``.
 
+.. module:: sphinx.builders.qthelp
+.. class:: QtHelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates Qt help collection support files that allow
+   the Qt collection generator to compile them.
+
+   Its name is ``qthelp``.
+
+.. module:: sphinx.builders.devhelp
+.. class:: DevhelpBuilder
+
+   This builder produces the same output as the standalone HTML builder, but
+   also generates `GNOME Devhelp <http://live.gnome.org/devhelp>`__ 
+   support file that allows the GNOME Devhelp reader to view them.
+
+   Its name is ``devhelp``.
+
 .. module:: sphinx.builders.latex
 .. class:: LaTeXBuilder
 
diff --git a/doc/concepts.rst b/doc/concepts.rst
index e6d5fa02..27767211 100644
--- a/doc/concepts.rst
+++ b/doc/concepts.rst
@@ -89,6 +89,15 @@ tables of contents.  The ``toctree`` directive is the central element.
    Numbering then starts at the heading of ``foo``.  Sub-toctrees are
    automatically numbered (don't give the ``numbered`` flag to those).
 
+   If you want only the titles of documents in the tree to show up, not other
+   headings of the same level, you can use the ``titlesonly`` option::
+
+      .. toctree::
+         :titlesonly:
+
+         foo
+         bar
+
    You can use "globbing" in toctree directives, by giving the ``glob`` flag
    option.  All entries are then matched against the list of available
    documents, and matches are inserted into the list alphabetically.  Example::
@@ -139,6 +148,9 @@ tables of contents.  The ``toctree`` directive is the central element.
       Added "numbered" and "hidden" options as well as external links and
       support for "self" references.
 
+   .. versionchanged:: 1.0
+      Added "titlesonly" option.
+
 
 Special names
 -------------
diff --git a/doc/conf.py b/doc/conf.py
index e1a48aa2..e3952a0b 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -6,7 +6,10 @@ import sys, os, re
 
 # 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']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
+              'sphinx.ext.autosummary']
+
+extlinks = {'issue': ('http://bugs.python.org/issue', 'issue ')}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -71,7 +74,7 @@ latex_logo = '_static/sphinx.png'
 
 # Additional stuff for the LaTeX preamble.
 latex_elements = {
-    'fontpkg': '\\usepackage{palatino}'
+    'fontpkg': '\\usepackage{palatino}',
 }
 
 # Put TODOs into the output.
diff --git a/doc/config.rst b/doc/config.rst
index 2e96a749..3ce8d53b 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -185,7 +185,6 @@ General configuration
 
    .. versionadded:: 0.5
 
-
 .. confval:: modindex_common_prefix
 
    A list of prefixes that are ignored for sorting the module index (e.g.,
@@ -195,6 +194,15 @@ General configuration
 
    .. versionadded:: 0.6
 
+.. confval:: trim_doctest_flags
+
+   If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
+   the ends of lines are removed for all code blocks showing interactive Python
+   sessions (i.e. doctests).  Default is true.  See the extension
+   :mod:`~sphinx.ext.doctest` for more possibilities of including doctests.
+
+   .. versionadded:: 1.0
+
 
 Project information
 -------------------
@@ -245,6 +253,7 @@ Project information
    * ``ru`` -- Russian
    * ``sl`` -- Slovenian
    * ``uk_UA`` -- Ukrainian
+   * ``zh_CN`` -- Simplified Chinese
    * ``zh_TW`` -- Traditional Chinese
 
 .. confval:: today
@@ -514,6 +523,12 @@ that use Sphinx' HTMLWriter class.
    to translate document trees to HTML.  Default is ``None`` (use the builtin
    translator).
 
+.. confval:: html_show_copyright
+
+   If true, "(C) Copyright ..." is shown in the HTML footer. Default is ``True``.
+
+   .. versionadded:: 1.0
+
 .. confval:: html_show_sphinx
 
    If true, "Created using Sphinx" is shown in the HTML footer.  Default is
@@ -521,6 +536,14 @@ that use Sphinx' HTMLWriter class.
 
    .. versionadded:: 0.4
 
+.. confval:: html_output_encoding
+
+   Encoding of HTML output files. Default is ``'utf-8'``.  Note that this
+   encoding name must both be a valid Python encoding name and a valid HTML
+   ``charset`` value.
+
+   .. versionadded:: 1.0
+
 .. confval:: htmlhelp_basename
 
    Output file base name for HTML help builder.  Default is ``'pydoc'``.
@@ -653,6 +676,14 @@ These options influence LaTeX output.
      ``'shorthandoff'``
      ``'printmodindex'``
 
+.. confval:: latex_docclass
+
+   A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document
+   classes that will be used as the base for the two Sphinx classes.  Default
+   is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``.
+
+   .. versionadded:: 1.0
+
 .. confval:: latex_additional_files
 
    A list of file names, relative to the configuration directory, to copy to the
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 6864d6ba..0a3dae8f 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -205,6 +205,14 @@ the following public API:
 
    .. versionadded:: 0.5
 
+.. method:: Sphinx.add_stylesheet(filename)
+
+   Add *filename* to the list of CSS files that the default HTML template will
+   include.  Like for :meth:`add_javascript`, the filename must be relative to
+   the HTML static path.
+
+   .. versionadded:: 1.0
+
 .. method:: Sphinx.add_lexer(alias, lexer)
 
    Use *lexer*, which must be an instance of a Pygments lexer class, to
diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst
index a9255857..57abd616 100644
--- a/doc/ext/autosummary.rst
+++ b/doc/ext/autosummary.rst
@@ -6,4 +6,220 @@
 .. module:: sphinx.ext.autosummary
    :synopsis: Generate autodoc summaries
 
-TBW.
+.. versionadded:: 0.6
+
+This extension generates function/method/attribute summary lists, similar to
+those output e.g. by Epydoc and other API doc generation tools.  This is
+especially useful when your docstrings are long and detailed, and putting each
+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
+   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.
+   These by default contain only the corresponding :mod:`sphinx.ext.autodoc`
+   directive.
+
+
+.. 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`
+   entry for the included items.
+
+   For example, ::
+
+       .. currentmodule:: sphinx
+
+       .. autosummary::
+
+          environment.BuildEnvironment
+          util.relative_uri
+
+   produces a table like this:
+
+       .. currentmodule:: sphinx
+
+       .. autosummary::
+
+          environment.BuildEnvironment
+          util.relative_uri
+
+       .. currentmodule:: sphinx.ext.autosummary
+
+   Autosummary preprocesses the docstrings and signatures with the same
+   :event:`autodoc-process-docstring` and :event:`autodoc-process-signature`
+   hooks as :mod:`~sphinx.ext.autodoc`.
+
+
+   **Options**
+
+   * If you want the :dir:`autosummary` table to also serve as a :dir:`toctree`
+     entry, use the ``toctree`` option, for example::
+
+         .. autosummary::
+            :toctree: DIRNAME
+
+            sphinx.environment.BuildEnvironment
+            sphinx.util.relative_uri
+
+     The ``toctree`` option also signals to the :program:`sphinx-autogen` script
+     that stub pages should be generated for the entries listed in this
+     directive.  The option accepts a directory name as an argument;
+     :program:`sphinx-autogen` will by default place its output in this
+     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
+     listing, include the ``nosignatures`` option::
+
+         .. autosummary::
+            :nosignatures:
+
+            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.
+
+
+: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.
+
+For example, the command ::
+
+    $ sphinx-autogen -o generated *.rst
+
+will read all :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::
+
+    sphinx.util.relative_uri
+    ========================
+
+    .. autofunction:: sphinx.util.relative_uri
+
+If the ``-o`` option is not given, the script will place the output files in the
+directories specified in the ``:toctree:`` options.
+
+
+Generating stub pages automatically
+-----------------------------------
+
+If you do not want to create stub pages with :program:`sphinx-autogen`, you can
+also use this new config value:
+
+.. confval:: autosummary_generate
+
+   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
+---------------------
+
+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:
+
+.. 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:: methods
+
+   List containing names of "public" attributes in the class.  Only available
+   for classes.
+
+.. note::
+   
+   You can use the :dir:`autosummary` directive in the stub pages.
+   Stub pages are generated also based on these directives.
diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst
index 19905dc7..1ef2e807 100644
--- a/doc/ext/doctest.rst
+++ b/doc/ext/doctest.rst
@@ -173,9 +173,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::
@@ -196,4 +196,5 @@ There are also these config values for customizing the doctest extension:
    Note though that you can't have blank lines in reST doctest blocks.  They
    will be interpreted as one block ending and another one starting.  Also,
    removal of ``<BLANKLINE>`` and ``# doctest:`` options only works in
-   :dir:`doctest` blocks.
+   :dir:`doctest` blocks, though you may set :confval:`trim_doctest_flags` to
+   achieve the latter in all code blocks with Python console content.
diff --git a/doc/ext/extlinks.rst b/doc/ext/extlinks.rst
new file mode 100644
index 00000000..fb101ff3
--- /dev/null
+++ b/doc/ext/extlinks.rst
@@ -0,0 +1,47 @@
+: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/',
+                            '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.
+
+   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.
diff --git a/doc/extensions.rst b/doc/extensions.rst
index 5eb26c14..0bc9b5b7 100644
--- a/doc/extensions.rst
+++ b/doc/extensions.rst
@@ -51,6 +51,7 @@ These extensions are built in and can be activated by respective entries in the
    ext/ifconfig
    ext/coverage
    ext/todo
+   ext/extlinks
 
 
 Third-party extensions
diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index 93cd127b..8c223297 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -143,11 +143,17 @@ Includes
    string option, only lines that precede the first lines containing that string
    are included.
 
+   You can prepend and/or append a line to the included code, using the
+   ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
+   highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.
+
    .. versionadded:: 0.4.3
       The ``encoding`` option.
    .. versionadded:: 0.6
       The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options,
       as well as support for absolute filenames.
+   .. versionadded:: 1.0
+      The ``prepend`` and ``append`` options.
 
 
 .. rubric:: Footnotes
diff --git a/doc/sphinx-build.1 b/doc/sphinx-build.1
index 498771c9..a3df16d0 100644
--- a/doc/sphinx-build.1
+++ b/doc/sphinx-build.1
@@ -31,6 +31,9 @@ Generates files for CHM generation.
 \fBqthelp\fR
 Generates files for Qt help collection generation.
 .TP
+\fBdevhelp\fR
+Generates files for GNOME Devhelp help viewer.
+.TP
 \fBlatex\fR
 Generates a LaTeX version of the documentation.
 .TP
diff --git a/doc/theming.rst b/doc/theming.rst
index d1d3b27a..5b4b648c 100644
--- a/doc/theming.rst
+++ b/doc/theming.rst
@@ -86,6 +86,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.