merge with 1.0

6 files changed, 155 insertions, 20 deletions

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