merge with stable

11 files changed, 95 insertions, 71 deletions

diff --git a/doc/config.rst b/doc/config.rst
index 82ecdfdf..e4d9feaf 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -45,7 +45,8 @@ Important points to note:
 * There is a special object named ``tags`` available in the config file.
   It can be used to query and change the tags (see :ref:`tags`).  Use
   ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')``
-  to change.
+  to change. Only tags set via the ``-t`` command-line option or via
+  ``tags.add('tag')`` can be queried using ``tags.has('tag')``.
 
 
 General configuration
@@ -120,7 +121,7 @@ General configuration
    in that case.
 
    .. deprecated:: 1.0
-      Use :confval:`exclude_patterns` instead.
+      Use :confval:`exclude_patterns` or :ref:`metadata` instead.
 
 .. confval:: exclude_trees
 
diff --git a/doc/domains.rst b/doc/domains.rst
index 024edc9a..6c3c4359 100644
--- a/doc/domains.rst
+++ b/doc/domains.rst
@@ -157,17 +157,6 @@ declarations:
 
 The following directives are provided for module and class contents:
 
-.. rst:directive:: .. py:data:: name
-
-   Describes global data in a module, including both variables and values used
-   as "defined constants."  Class and object attributes are not documented
-   using this environment.
-
-.. rst:directive:: .. py:exception:: name
-
-   Describes an exception class.  The signature can, but need not include
-   parentheses with constructor arguments.
-
 .. rst:directive:: .. py:function:: name(parameters)
 
    Describes a module-level function.  The signature should include the
@@ -178,11 +167,23 @@ The following directives are provided for module and class contents:
 
    For methods you should use :rst:dir:`py:method`.
 
-   The description should include information about the parameters required and
-   how they are used (especially whether mutable objects passed as parameters
-   are modified), side effects, and possible exceptions.  This information can
-   optionally be given in a structured form, see :ref:`info-field-lists`.  A
-   small example may be provided.
+   The description normally includes information about the parameters required
+   and how they are used (especially whether mutable objects passed as
+   parameters are modified), side effects, and possible exceptions.
+
+   This information can (in any ``py`` directive) optionally be given in a
+   structured form, see :ref:`info-field-lists`.
+
+.. rst:directive:: .. py:data:: name
+
+   Describes global data in a module, including both variables and values used
+   as "defined constants."  Class and object attributes are not documented
+   using this environment.
+
+.. rst:directive:: .. py:exception:: name
+
+   Describes an exception class.  The signature can, but need not include
+   parentheses with constructor arguments.
 
 .. rst:directive:: .. py:class:: name
                    .. py:class:: name(parameters)
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index a6393d40..156dede8 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -199,10 +199,13 @@ the following public API:
       .. index:: pair: function; directive
 
    The reference node will be of class ``literal`` (so it will be rendered in a
-   proportional font, as appropriate for code) unless you give the *ref_nodeclass*
-   argument, which must be a docutils node class (most useful are
-   ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also use
-   ``docutils.nodes.generated`` if you want no further text decoration).
+   proportional font, as appropriate for code) unless you give the
+   *ref_nodeclass* argument, which must be a docutils node class.  Most useful
+   are ``docutils.nodes.emphasis`` or ``docutils.nodes.strong`` -- you can also
+   use ``docutils.nodes.generated`` if you want no further text decoration.  If
+   the text should be treated as literal (e.g. no smart quote replacement), but
+   not have typewriter styling, use ``sphinx.addnodes.literal_emphasis`` or
+   ``sphinx.addnodes.literal_strong``.     
 
    For the role content, you have the same syntactical possibilities as for
    standard Sphinx roles (see :ref:`xref-syntax`).
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index c92fe0c4..94b05423 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -195,6 +195,12 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
      .. versionadded:: 1.2
 
+   * Add a list of modules in the :confval:`autodoc_mock_imports` to prevent
+     import errors to halt the building process when some external dependencies
+     are not importable at build time.
+
+     .. versionadded:: 1.3
+
 
 .. rst:directive:: autofunction
                    autodata
@@ -335,6 +341,14 @@ There are also new config values that you can set:
 
    .. versionadded:: 1.1
 
+.. confval:: autodoc_mock_imports
+
+   This value contains a list of modules to be mocked up. This is useful when
+   some external dependencies are not met at build time and break the building
+   process.
+
+   .. versionadded:: 1.3
+
 
 Docstring preprocessing
 -----------------------
diff --git a/doc/ext/oldcmarkup.rst b/doc/ext/oldcmarkup.rst
deleted file mode 100644
index 0fdd9fec..00000000
--- a/doc/ext/oldcmarkup.rst
+++ /dev/null
@@ -1,35 +0,0 @@
-:mod:`sphinx.ext.oldcmarkup` -- Compatibility extension for old C markup
-========================================================================
-
-.. module:: sphinx.ext.oldcmarkup
-   :synopsis: Allow further use of the pre-domain C markup
-.. moduleauthor:: Georg Brandl
-
-.. versionadded:: 1.0
-
-
-This extension is a transition helper for projects that used the old
-(pre-domain) C markup, i.e. the directives like ``cfunction`` and roles like
-``cfunc``.  Since the introduction of domains, they must be called by their
-fully-qualified name (``c:function`` and ``c:func``, respectively) or, with the
-default domain set to ``c``, by their new name (``function`` and ``func``).
-(See :ref:`c-domain` for the details.)
-
-If you activate this extension, it will register the old names, and you can
-use them like before Sphinx 1.0.  The directives are:
-
-- ``cfunction``
-- ``cmember``
-- ``cmacro``
-- ``ctype``
-- ``cvar``
-
-The roles are:
-
-- ``cdata``
-- ``cfunc``
-- ``cmacro``
-- ``ctype``
-
-However, it is advised to migrate to the new markup -- this extension is a
-compatibility convenience and will disappear in a future version of Sphinx.
diff --git a/doc/extensions.rst b/doc/extensions.rst
index 334e5039..7597f281 100644
--- a/doc/extensions.rst
+++ b/doc/extensions.rst
@@ -53,7 +53,6 @@ These extensions are built in and can be activated by respective entries in the
    ext/extlinks
    ext/viewcode
    ext/linkcode
-   ext/oldcmarkup
 
 
 Third-party extensions
diff --git a/doc/install.rst b/doc/install.rst
index bf653872..71e37e9c 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -4,7 +4,7 @@ Installing Sphinx
 =================
 
 Since Sphinx is written in the Python language, you need to install Python
-(the required version is at least 2.5) and Sphinx.
+(the required version is at least 2.6) and Sphinx.
 
 Sphinx packages are available on the `Python Package Index
 <https://pypi.python.org/pypi/Sphinx>`_.
@@ -79,8 +79,8 @@ sidebar and under "Quick Links", click "Windows Installer" to download.
 
 .. note::
 
-   Currently, Python offers two major versions, 2.x and 3.x. Sphinx 1.2 can run
-   under Python 2.5 to 2.7 and 3.1 to 3.3, with the recommended version being
+   Currently, Python offers two major versions, 2.x and 3.x. Sphinx 1.3 can run
+   under Python 2.6, 2.7, 3.2, 3.3, with the recommended version being
    2.7.  This chapter assumes you have installed Python 2.7.
 
 Follow the Windows installer for Python.
diff --git a/doc/intro.rst b/doc/intro.rst
index 66d0c58d..dd541bf1 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -54,7 +54,7 @@ See the :ref:`pertinent section in the FAQ list <usingwith>`.
 Prerequisites
 -------------
 
-Sphinx needs at least **Python 2.5** or **Python 3.1** to run, as well as the
+Sphinx needs at least **Python 2.6** or **Python 3.2** to run, as well as the
 docutils_ and Jinja2_ libraries.  Sphinx should work with docutils version 0.7
 or some (not broken) SVN trunk snapshot.  If you like to have source code
 highlighting support, you must also install the Pygments_ library.
diff --git a/doc/invocation.rst b/doc/invocation.rst
index 52ee803f..f831dc0a 100644
--- a/doc/invocation.rst
+++ b/doc/invocation.rst
@@ -124,13 +124,22 @@ The :program:`sphinx-build` script has several options:
 .. option:: -D setting=value
 
    Override a configuration value set in the :file:`conf.py` file.  The value
-   must be a string or dictionary value.  For the latter, supply the setting
-   name and key like this: ``-D latex_elements.docclass=scrartcl``.  For boolean
-   values, use ``0`` or ``1`` as the value.
+   must be a number, string, list or dictionary value.
+
+   For lists, you can separate elements with a comma like this: ``-D
+   html_theme_path=path1,path2``.
+
+   For dictionary values, supply the setting name and key like this:
+   ``-D latex_elements.docclass=scrartcl``.
+
+   For boolean values, use ``0`` or ``1`` as the value.
 
    .. versionchanged:: 0.6
       The value can now be a dictionary value.
 
+   .. versionchanged:: 1.3
+      The value can now also be a list value.
+
 .. option:: -A name=value
 
    Make the *name* assigned to *value* in the HTML templates.
diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index 98fdad7d..e9f8f1da 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -86,6 +86,14 @@ on line numbers for the individual block::
 
       Some more Ruby code.
 
+The first line number can be selected with the ``lineno-start`` option.  If
+present, ``linenos`` is automatically activated as well.
+
+   .. code-block:: ruby
+      :lineno-start: 10
+
+      Some more Ruby code, with line numbering starting at 10.
+
 Additionally, an ``emphasize-lines`` option can be given to have Pygments
 emphasize particular lines::
 
@@ -101,6 +109,9 @@ emphasize particular lines::
 .. versionchanged:: 1.1
    ``emphasize-lines`` has been added.
 
+.. versionchanged:: 1.3
+   ``lineno-start`` has been added.
+
 
 Includes
 ^^^^^^^^
@@ -121,10 +132,11 @@ Includes
    Tabs in the input are expanded if you give a ``tab-width`` option with the
    desired tab width.
 
-   The directive also supports the ``linenos`` flag option to switch on line
-   numbers, the ``emphasize-lines`` option to emphasize particular lines, and
-   a ``language`` option to select a language different from the current
-   file's standard language.  Example with options::
+   Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag
+   option to switch on line numbers, the ``lineno-start`` option to select the
+   first line number, the ``emphasize-lines`` option to emphasize particular
+   lines, and a ``language`` option to select a language different from the
+   current file's standard language.  Example with options::
 
       .. literalinclude:: example.rb
          :language: ruby
@@ -176,6 +188,25 @@ Includes
       The ``prepend`` and ``append`` options, as well as ``tab-width``.
 
 
+Showing a file name
+^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 1.3
+
+A ``filename`` option can be given to show that name before the code block.  For
+example::
+
+   .. code-block:: python
+      :filename: this.py
+
+      print 'Explicit is better than implicit.'
+
+
+:rst:dir:`literalinclude` also supports the ``filename`` option, with the
+additional feature that if you leave the value empty, the shown filename will be
+exactly the one given as an argument.
+
+
 .. rubric:: Footnotes
 
 .. [1] There is a standard ``.. include`` directive, but it raises errors if the
diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index 9316e69a..fdecc37d 100644
--- a/doc/markup/toctree.rst
+++ b/doc/markup/toctree.rst
@@ -141,8 +141,9 @@ tables of contents.  The ``toctree`` directive is the central element.
    In the end, all documents in the :term:`source directory` (or subdirectories)
    must occur in some ``toctree`` directive; Sphinx will emit a warning if it
    finds a file that is not included, because that means that this file will not
-   be reachable through standard navigation.  Use :confval:`exclude_patterns` to
-   explicitly exclude documents or directories from building.
+   be reachable through standard navigation.  Use :ref:`metadata` to remove the
+   warning, and :confval:`exclude_patterns` to explicitly exclude documents or
+   directories from building.
 
    The "master document" (selected by :confval:`master_doc`) is the "root" of
    the TOC tree hierarchy.  It can be used as the documentation's main page, or