merge heads

21 files changed, 247 insertions, 184 deletions

diff --git a/doc/_templates/index.html b/doc/_templates/index.html
index 0739191e..e6ef9178 100644
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -21,7 +21,7 @@
   </p>
   <ul>
     <li>{%trans%}<b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for
-      printable PDF versions), Texinfo, manual pages, plain text{%endtrans%}</li>
+      printable PDF versions), ePub, Texinfo, manual pages, plain text{%endtrans%}</li>
     <li>{%trans%}<b>Extensive cross-references:</b> semantic markup and automatic links
       for functions, classes, citations, glossary terms and similar pieces of
       information{%endtrans%}</li>
@@ -85,7 +85,16 @@
     of this documentation, thanks to the Japanese Sphinx user group.{%endtrans%}</p>
   <p>{%trans%}A Japanese book about Sphinx has been published by O'Reilly:
     <a href="http://www.oreilly.co.jp/books/9784873116488/">Sphinxをはじめよう /
-      Learning Sphinx</a>:{%endtrans%}</p>
-  <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p>
+      Learning Sphinx</a>.{%endtrans%}</p>
+  <!-- <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p> -->
+
+
+  <h2>{%trans%}Hosting{%endtrans%}</h2>
+
+  <p>{%trans%}Need a place to host your Sphinx docs?
+    <a href="http://readthedocs.org">readthedocs.org</a> hosts a lot of Sphinx docs
+    already, and integrates well with projects' source control.  It also features a
+    powerful built-in search that exceeds the possibilities of Sphinx' JavaScript-based
+    offline search.{%endtrans%}</p>
 
 {% endblock %}
diff --git a/doc/builders.rst b/doc/builders.rst
index e449e110..b7afd569 100644
--- a/doc/builders.rst
+++ b/doc/builders.rst
@@ -64,13 +64,13 @@ The builder's "name" must be given to the **-b** command-line option of
 
    Its name is ``qthelp``.
 
-   .. _Qt help: http://doc.trolltech.com/4.6/qthelp-framework.html
+   .. _Qt help: http://qt-project.org/doc/qt-4.8/qthelp-framework.html
 
 .. module:: sphinx.builders.devhelp
 .. class:: DevhelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
-   also generates `GNOME Devhelp <http://live.gnome.org/devhelp>`__
+   also generates `GNOME Devhelp <https://wiki.gnome.org/Apps/Devhelp>`__
    support file that allows the GNOME Devhelp reader to view them.
 
    Its name is ``devhelp``.
@@ -110,8 +110,8 @@ The builder's "name" must be given to the **-b** command-line option of
 Note that a direct PDF builder using ReportLab is available in `rst2pdf
 <http://rst2pdf.googlecode.com>`_ version 0.12 or greater.  You need to add
 ``'rst2pdf.pdfbuilder'`` to your :confval:`extensions` to enable it, its name is
-``pdf``.  Refer to the `rst2pdf manual
-<http://lateral.netmanagers.com.ar/static/manual.pdf>`_ for details.
+``pdf``.  Refer to the `rst2pdf manual <http://ralsina.me/static/manual.pdf>`_
+for details.
 
 .. module:: sphinx.builders.text
 .. class:: TextBuilder
@@ -178,7 +178,7 @@ Note that a direct PDF builder using ReportLab is available in `rst2pdf
             globalcontext_filename = 'globalcontext.phpdump'
             searchindex_filename = 'searchindex.phpdump'
 
-   .. _PHP serialization: http://pypi.python.org/pypi/phpserialize
+   .. _PHP serialization: https://pypi.python.org/pypi/phpserialize
 
    .. attribute:: implementation
 
diff --git a/doc/config.rst b/doc/config.rst
index 70ccd26e..181ef2a4 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -40,6 +40,8 @@ Important points to note:
   delete them from the namespace with ``del`` if appropriate.  Modules are
   removed automatically, so you don't need to ``del`` your imports after use.
 
+.. _conf-tags:
+
 * 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')``
@@ -118,7 +120,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
 
@@ -236,7 +238,8 @@ General configuration
 
    A list of ``(type, target)`` tuples (by default empty) that should be ignored
    when generating warnings in "nitpicky mode".  Note that ``type`` should
-   include the domain name.  An example entry would be ``('py:func', 'int')``.
+   include the domain name if present.  Example entries would be ``('py:func',
+   'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``.
 
    .. versionadded:: 1.1
 
@@ -472,8 +475,8 @@ that use Sphinx' HTMLWriter class.
    The "title" for HTML documentation generated with Sphinx' own templates.
    This is appended to the ``<title>`` tag of individual pages, and used in the
    navigation bar as the "topmost" element.  It defaults to :samp:`'{<project>}
-   v{<revision>} documentation'`, where the placeholders are replaced by the
-   config values of the same name.
+   v{<revision>} documentation'` (with the values coming from the config
+   values).
 
 .. confval:: html_short_title
 
diff --git a/doc/develop.rst b/doc/develop.rst
index 95a615cb..faece78d 100644
--- a/doc/develop.rst
+++ b/doc/develop.rst
@@ -6,11 +6,11 @@ Sphinx development
 Sphinx is a maintained by a group of volunteers.  We value every contribution!
 
 * The code can be found in a Mercurial repository, at
-  http://bitbucket.org/birkenfeld/sphinx/.
+  https://bitbucket.org/birkenfeld/sphinx/.
 * Issues and feature requests should be raised in the `tracker
-  <http://bitbucket.org/birkenfeld/sphinx/issues/>`_.
+  <https://bitbucket.org/birkenfeld/sphinx/issues/>`_.
 * The mailing list for development is at `Google Groups
-  <http://groups.google.com/group/sphinx-dev/>`_.
+  <https://groups.google.com/group/sphinx-dev/>`_.
 * There is also the #sphinx-doc IRC channel on `freenode
   <http://freenode.net/>`_.
 
@@ -82,24 +82,24 @@ own extensions.
 .. _gnuplot: http://www.gnuplot.info/
 .. _paver: http://www.blueskyonmars.com/projects/paver/
 .. _Sword: http://www.crosswire.org/sword/
-.. _Lilypond: http://lilypond.org/web/
+.. _Lilypond: http://lilypond.org/
 .. _sdedit: http://sdedit.sourceforge.net/
 .. _Trac: http://trac.edgewall.org
 .. _TracLinks: http://trac.edgewall.org/wiki/TracLinks
 .. _OmegaT: http://www.omegat.org/
 .. _PlantUML: http://plantuml.sourceforge.net/
 .. _PyEnchant: http://www.rfk.id.au/software/pyenchant/
-.. _sadisplay: http://bitbucket.org/estin/sadisplay/wiki/Home
-.. _blockdiag: http://blockdiag.com/
-.. _seqdiag: http://blockdiag.com/
-.. _actdiag: http://blockdiag.com/
-.. _nwdiag: http://blockdiag.com/
-.. _Google Chart: http://code.google.com/intl/ja/apis/chart/
-.. _Google Maps: http://maps.google.com/
+.. _sadisplay: https://bitbucket.org/estin/sadisplay/wiki/Home
+.. _blockdiag: http://blockdiag.com/en/
+.. _seqdiag: http://blockdiag.com/en/
+.. _actdiag: http://blockdiag.com/en/
+.. _nwdiag: http://blockdiag.com/en/
+.. _Google Chart: https://developers.google.com/chart/
+.. _Google Maps: https://maps.google.com/
 .. _hyphenator: http://code.google.com/p/hyphenator/
-.. _exceltable: http://packages.python.org/sphinxcontrib-exceltable/
+.. _exceltable: http://pythonhosted.org/sphinxcontrib-exceltable/
 .. _YouTube: http://www.youtube.com/
-.. _ClearQuest: http://www-01.ibm.com/software/awdtools/clearquest/
+.. _ClearQuest: http://www-03.ibm.com/software/products/en/clearquest
 .. _Zope interfaces: http://docs.zope.org/zope.interface/README.html
 .. _slideshare: http://www.slideshare.net/
 .. _TikZ/PGF LaTeX package: http://sourceforge.net/projects/pgf/
diff --git a/doc/devguide.rst b/doc/devguide.rst
index 0e3563b8..b23acb1c 100644
--- a/doc/devguide.rst
+++ b/doc/devguide.rst
@@ -23,7 +23,7 @@ sphinx-dev <sphinx-dev@googlegroups.com>
 #sphinx-doc on irc.freenode.net
     IRC channel for development questions and user support.
 
-.. _`BitBucket`: http://bitbucket.org
+.. _`BitBucket`: https://bitbucket.org/
 .. _`Mercurial`: http://mercurial.selenic.com/
 
 
@@ -43,7 +43,7 @@ Including or providing a link to the source files involved may help us fix the
 issue.  If possible, try to create a minimal project that produces the error
 and post that instead.
 
-.. _`issue tracker`: http://bitbucket.org/birkenfeld/sphinx/issues
+.. _`issue tracker`: https://bitbucket.org/birkenfeld/sphinx/issues
 
 
 Contributing to Sphinx
@@ -126,7 +126,7 @@ These are the basic steps needed to start developing on Sphinx.
 
    would close issue #42.
 
-   __ https://confluence.atlassian.com/display/BITBUCKET/Automatically+Resolving+Issues+when+Users+Push+Code
+   __ https://confluence.atlassian.com/display/BITBUCKET/Resolve+issues+automatically+when+users+push+code
 
 #. Push changes to your forked repository on BitBucket. ::
 
@@ -190,7 +190,7 @@ identifier and put ``sphinx.po`` in there.  Don't forget to update the possible
 values for :confval:`language` in ``doc/config.rst``.
 
 The Sphinx core messages can also be translated on `Transifex
-<http://transifex.com>`_.  There exists a client tool named ``tx`` in the Python
+<https://www.transifex.com/>`_.  There exists a client tool named ``tx`` in the Python
 package "transifex_client", which can be used to pull translations in ``.po``
 format from Transifex.  To do this, go to ``sphinx/locale`` and then run
 ``tx pull -f -l LANG`` where LANG is an existing language identifier.  It is
diff --git a/doc/domains.rst b/doc/domains.rst
index 57b10c3b..6c3c4359 100644
--- a/doc/domains.rst
+++ b/doc/domains.rst
@@ -157,6 +157,23 @@ declarations:
 
 The following directives are provided for module and class contents:
 
+.. rst:directive:: .. py:function:: name(parameters)
+
+   Describes a module-level function.  The signature should include the
+   parameters as given in the Python function definition, see :ref:`signatures`.
+   For example::
+
+      .. py:function:: Timer.repeat(repeat=3, number=1000000)
+
+   For methods you should use :rst:dir:`py:method`.
+
+   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
@@ -168,24 +185,6 @@ The following directives are provided for module and class contents:
    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
-   parameters, enclosing optional parameters in brackets.  Default values can be
-   given if it enhances clarity; see :ref:`signatures`.  For example::
-
-      .. py:function:: Timer.repeat([repeat=3[, number=1000000]])
-
-   Object methods are not documented using this directive. Bound object methods
-   placed in the module namespace as part of the public interface of the module
-   are documented using this, as they are equivalent to normal functions for
-   most purposes.
-
-   The description should include information about the parameters required and
-   how they are used (especially whether mutable objects passed as parameters
-   are modified), side effects, and possible exceptions.  A small example may be
-   provided.
-
 .. rst:directive:: .. py:class:: name
                    .. py:class:: name(parameters)
 
@@ -198,6 +197,7 @@ The following directives are provided for module and class contents:
    contain the class name so that cross-references still work.  Example::
 
       .. py:class:: Foo
+
          .. py:method:: quux()
 
       -- or --
@@ -218,7 +218,8 @@ The following directives are provided for module and class contents:
 
    Describes an object method.  The parameters should not include the ``self``
    parameter.  The description should include similar information to that
-   described for ``function``.  See also :ref:`signatures`.
+   described for ``function``.  See also :ref:`signatures` and
+   :ref:`info-field-lists`.
 
 .. rst:directive:: .. py:staticmethod:: name(parameters)
 
@@ -235,9 +236,8 @@ The following directives are provided for module and class contents:
 .. rst:directive:: .. py:decorator:: name
                    .. py:decorator:: name(parameters)
 
-   Describes a decorator function.  The signature should *not* represent the
-   signature of the actual function, but the usage as a decorator.  For example,
-   given the functions
+   Describes a decorator function.  The signature should represent the usage as
+   a decorator.  For example, given the functions
 
    .. code-block:: python
 
@@ -280,23 +280,24 @@ Python Signatures
 ~~~~~~~~~~~~~~~~~
 
 Signatures of functions, methods and class constructors can be given like they
-would be written in Python, with the exception that optional parameters can be
-indicated by brackets::
-
-   .. py:function:: compile(source[, filename[, symbol]])
-
-It is customary to put the opening bracket before the comma.  In addition to
-this "nested" bracket style, a "flat" style can also be used, due to the fact
-that most optional parameters can be given independently::
-
-   .. py:function:: compile(source[, filename, symbol])
+would be written in Python.
 
 Default values for optional arguments can be given (but if they contain commas,
 they will confuse the signature parser).  Python 3-style argument annotations
 can also be given as well as return type annotations::
 
-   .. py:function:: compile(source : string[, filename, symbol]) -> ast object
+   .. py:function:: compile(source : string, filename, symbol='file') -> ast object
+
+For functions with optional parameters that don't have default values (typically
+functions implemented in C extension modules without keyword argument support),
+you can use brackets to specify the optional parts:
+
+   .. py:function:: compile(source[, filename[, symbol]])
+
+It is customary to put the opening bracket before the comma.
+
 
+.. _info-field-lists:
 
 Info field lists
 ~~~~~~~~~~~~~~~~
@@ -382,8 +383,8 @@ a matching identifier is found:
 
 .. rst:role:: py:const
 
-   Reference a "defined" constant.  This may be a C-language ``#define`` or a
-   Python variable that is not intended to be changed.
+   Reference a "defined" constant.  This may be a Python variable that is not
+   intended to be changed.
 
 .. rst:role:: py:class
 
@@ -471,8 +472,8 @@ The C domain (name **c**) is suited for documentation of C API.
 
    Describes a "simple" C macro.  Simple macros are macros which are used for
    code expansion, but which do not take arguments so cannot be described as
-   functions.  This is not to be used for simple constant definitions.  Examples
-   of its use in the Python documentation include :c:macro:`PyObject_HEAD` and
+   functions.  This is a simple C-language ``#define``.  Examples of its use in
+   the Python documentation include :c:macro:`PyObject_HEAD` and
    :c:macro:`Py_BEGIN_ALLOW_THREADS`.
 
 .. rst:directive:: .. c:type:: name
@@ -712,24 +713,24 @@ The JavaScript domain (name **js**) provides the following directives:
       .. js:function:: $.getJSON(href, callback[, errback])
 
          :param string href: An URI to the location of the resource.
-         :param callback: Get's called with the object.
+         :param callback: Gets called with the object.
          :param errback:
-             Get's called in case the request fails. And a lot of other
-             text so we need multiple lines
+             Gets called in case the request fails. And a lot of other
+             text so we need multiple lines.
          :throws SomeError: For whatever reason in that case.
-         :returns: Something
+         :returns: Something.
 
    This is rendered as:
 
       .. js:function:: $.getJSON(href, callback[, errback])
 
         :param string href: An URI to the location of the resource.
-        :param callback: Get's called with the object.
+        :param callback: Gets called with the object.
         :param errback:
-            Get's called in case the request fails. And a lot of other
+            Gets called in case the request fails. And a lot of other
             text so we need multiple lines.
         :throws SomeError: For whatever reason in that case.
-        :returns: Something
+        :returns: Something.
 
 .. rst:directive:: .. js:class:: name
 
@@ -828,17 +829,17 @@ Operation_, and Scala_.
 
 .. _sphinx-contrib: https://bitbucket.org/birkenfeld/sphinx-contrib/
 
-.. _Ada: http://pypi.python.org/pypi/sphinxcontrib-adadomain
-.. _CoffeeScript: http://pypi.python.org/pypi/sphinxcontrib-coffee
-.. _Common Lisp: http://pypi.python.org/pypi/sphinxcontrib-cldomain
-.. _dqn: http://pypi.python.org/pypi/sphinxcontrib-dqndomain
-.. _Erlang: http://pypi.python.org/pypi/sphinxcontrib-erlangdomain
-.. _Go: http://pypi.python.org/pypi/sphinxcontrib-golangdomain
-.. _HTTP: http://pypi.python.org/pypi/sphinxcontrib-httpdomain
-.. _Jinja: http://pypi.python.org/pypi/sphinxcontrib-jinjadomain
-.. _Lasso: http://pypi.python.org/pypi/sphinxcontrib-lassodomain
-.. _MATLAB: http://pypi.python.org/pypi/sphinxcontrib-matlabdomain
-.. _Operation: http://pypi.python.org/pypi/sphinxcontrib-operationdomain
-.. _PHP: http://pypi.python.org/pypi/sphinxcontrib-phpdomain
-.. _Ruby: http://bitbucket.org/birkenfeld/sphinx-contrib/src/default/rubydomain
-.. _Scala: http://pypi.python.org/pypi/sphinxcontrib-scaladomain
+.. _Ada: https://pypi.python.org/pypi/sphinxcontrib-adadomain
+.. _CoffeeScript: https://pypi.python.org/pypi/sphinxcontrib-coffee
+.. _Common Lisp: https://pypi.python.org/pypi/sphinxcontrib-cldomain
+.. _dqn: https://pypi.python.org/pypi/sphinxcontrib-dqndomain
+.. _Erlang: https://pypi.python.org/pypi/sphinxcontrib-erlangdomain
+.. _Go: https://pypi.python.org/pypi/sphinxcontrib-golangdomain
+.. _HTTP: https://pypi.python.org/pypi/sphinxcontrib-httpdomain
+.. _Jinja: https://pypi.python.org/pypi/sphinxcontrib-jinjadomain
+.. _Lasso: https://pypi.python.org/pypi/sphinxcontrib-lassodomain
+.. _MATLAB: https://pypi.python.org/pypi/sphinxcontrib-matlabdomain
+.. _Operation: https://pypi.python.org/pypi/sphinxcontrib-operationdomain
+.. _PHP: https://pypi.python.org/pypi/sphinxcontrib-phpdomain
+.. _Ruby: https://bitbucket.org/birkenfeld/sphinx-contrib/src/default/rubydomain
+.. _Scala: https://pypi.python.org/pypi/sphinxcontrib-scaladomain
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/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 b2ac3791..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
@@ -68,10 +67,10 @@ maintains a list of those.
 
 If you write an extension that you think others will find useful or you think
 should be included as a part of Sphinx, please write to the project mailing
-list (`join here <http://groups.google.com/group/sphinx-dev>`_).
+list (`join here <https://groups.google.com/group/sphinx-dev>`_).
 
-.. _Wiki at BitBucket: https://www.bitbucket.org/birkenfeld/sphinx/wiki/Home
-.. _Sphinx Contrib: https://www.bitbucket.org/birkenfeld/sphinx-contrib
+.. _Wiki at BitBucket: https://bitbucket.org/birkenfeld/sphinx/wiki/Home
+.. _Sphinx Contrib: https://bitbucket.org/birkenfeld/sphinx-contrib
 
 
 Where to put your own extensions?
diff --git a/doc/faq.rst b/doc/faq.rst
index ff74be1c..7aa35d1f 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -37,7 +37,7 @@ How do I...
    come through cleanly.
 
 ... create HTML slides from Sphinx documents?
-   See the "Hieroglyph" package at http://github.com/nyergler/hieroglyph.
+   See the "Hieroglyph" package at https://github.com/nyergler/hieroglyph.
 
 For many more extensions and other contributed stuff, see the sphinx-contrib_
 repository.
@@ -50,7 +50,7 @@ Using Sphinx with...
 --------------------
 
 Read the Docs
-    http://readthedocs.org is a documentation hosting service based around Sphinx.
+    https://readthedocs.org is a documentation hosting service based around Sphinx.
     They will host sphinx documentation, along with supporting a number of other
     features including version support, PDF generation, and more. The `Getting
     Started <http://read-the-docs.readthedocs.org/en/latest/getting_started.html>`_
@@ -62,7 +62,7 @@ Epydoc
 
 Doxygen
    Michael Jones is developing a reST/Sphinx bridge to doxygen called `breathe
-   <http://github.com/michaeljones/breathe/tree/master>`_.
+   <https://github.com/michaeljones/breathe/tree/master>`_.
 
 SCons
    Glenn Hutchings has written a SCons build script to build Sphinx
@@ -70,9 +70,9 @@ SCons
 
 PyPI
    Jannis Leidel wrote a `setuptools command
-   <http://pypi.python.org/pypi/Sphinx-PyPI-upload>`_ that automatically uploads
+   <https://pypi.python.org/pypi/Sphinx-PyPI-upload>`_ that automatically uploads
    Sphinx documentation to the PyPI package documentation area at
-   http://packages.python.org/.
+   http://pythonhosted.org/.
 
 GitHub Pages
    Directories starting with underscores are ignored by default which breaks
@@ -139,7 +139,7 @@ The following list gives some hints for the creation of epub files:
   are often cut at the right margin.  The default Courier font (or variant) is
   quite wide and you can only display up to 60 characters on a line.  If you
   replace it with a narrower font, you can get more characters on a line.  You
-  may even use `FontForge <http://fontforge.sourceforge.net/>`_ and create
+  may even use `FontForge <http://fontforge.org/>`_ and create
   narrow variants of some free font.  In my case I get up to 70 characters on a
   line.
 
@@ -168,8 +168,8 @@ The following list gives some hints for the creation of epub files:
 
 .. _Epubcheck: http://code.google.com/p/epubcheck/
 .. _Calibre: http://calibre-ebook.com/
-.. _FBreader: http://www.fbreader.org/
-.. _Bookworm: http://bookworm.oreilly.com/
+.. _FBreader: http://fbreader.org/
+.. _Bookworm: http://oreilly.com/bookworm/index.html
 
 
 .. _texinfo-faq:
diff --git a/doc/install.rst b/doc/install.rst
index bc969b0b..71e37e9c 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -7,7 +7,7 @@ Since Sphinx is written in the Python language, you need to install Python
 (the required version is at least 2.6) and Sphinx.
 
 Sphinx packages are available on the `Python Package Index
-<http://pypi.python.org/pypi/Sphinx>`_.
+<https://pypi.python.org/pypi/Sphinx>`_.
 
 You can also download a snapshot from the Mercurial development repository:
 
@@ -118,7 +118,7 @@ Install the easy_install command
 
 Python has a very useful :command:`easy_install` command which can download and
 install 3rd-party libraries with a single command.  This is provided by the
-"setuptools" project: http://pypi.python.org/pypi/setuptools.
+"setuptools" project: https://pypi.python.org/pypi/setuptools.
 
 To install setuptools, download
 https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py and
diff --git a/doc/intl.rst b/doc/intl.rst
index 5f969d51..6f74deb0 100644
--- a/doc/intl.rst
+++ b/doc/intl.rst
@@ -71,7 +71,7 @@ Translating with sphinx-intl
 ----------------------------
 
 Quick guide
-^^^^^^^^^^^^
+^^^^^^^^^^^
 
 `sphinx-intl`_ is a useful tool to work with Sphinx translation flow.
 This section describe a easy way to translate with sphinx-intl.
@@ -81,8 +81,8 @@ This section describe a easy way to translate with sphinx-intl.
 
 #. Add configurations to your `conf.py`::
 
-      locale_dirs = ['locale/']   #path is example but recommended.
-      gettext_compact = False     #optional.
+      locale_dirs = ['locale/']   # path is example but recommended.
+      gettext_compact = False     # optional.
 
    This case-study assumes that :confval:`locale_dirs` is set to 'locale/' and
    :confval:`gettext_compact` is set to `False` (the Sphinx document is
@@ -108,19 +108,18 @@ This section describe a easy way to translate with sphinx-intl.
 
 #. Build mo files and make translated document.
 
-   You need :confval:`language` parameter in ``conf.py`` or you may also
+   You need a :confval:`language` parameter in ``conf.py`` or you may also
    specify the parameter on the command line::
 
       $ sphinx-intl build
       $ make -e SPHINXOPTS="-D language='de'" html
 
-
-Congratulations!! You got the translated document in ``_build/html``
+Congratulations! You got the translated documentation in the ``_build/html``
 directory.
 
 
 Translating
-^^^^^^^^^^^^
+^^^^^^^^^^^
 
 Translate po file under ``./locale/de/LC_MESSAGES`` directory.
 The case of builders.po file for sphinx document:
@@ -146,16 +145,17 @@ syntax:
    "FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
    "BY TARGET LANGUAGE :ref:`EXTENSIONS <extensions>` FILL HERE."
 
-Please be careful not to break reST notation.
+Please be careful not to break reST notation.  Most po-editors will help you
+with that.
 
 
 Update your po files by new pot files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If the document is updated, it is necessary to generate updated pot files
+If a document is updated, it is necessary to generate updated pot files
 and to apply differences to translated po files.
 In order to apply the updating difference of a pot file to po file,
-using :command:`sphinx-intl update` command.
+use the :command:`sphinx-intl update` command.
 
 .. code-block:: bash
 
@@ -165,6 +165,10 @@ using :command:`sphinx-intl update` command.
 Using Transifex service for team translation
 --------------------------------------------
 
+Transifex_ is one of several services that allow collaborative translation via a
+web interface.  It has a nifty Python-based command line client that makes it
+easy to fetch and push translations.
+
 .. TODO: why use transifex?
 
 
@@ -181,9 +185,9 @@ Using Transifex service for team translation
 
 #. Create your transifex_ account and create new project for your document
 
-   Currently, transifex does not allow for a translation project to
-   have more than one version of document, so you'd better include a
-   version number in your project name.
+   Currently, transifex does not allow for a translation project to have more
+   than one version of the document, so you'd better include a version number in
+   your project name.
 
    For example:
 
@@ -193,8 +197,8 @@ Using Transifex service for team translation
 
 #. Create config files for tx command
 
-   This process will create ``.tx/config`` in the current directory, as
-   well as ``~/.transifexrc`` file that includes auth information.
+   This process will create ``.tx/config`` in the current directory, as well as
+   a ``~/.transifexrc`` file that includes auth information.
 
    .. code-block:: bash
 
@@ -253,11 +257,11 @@ Using Transifex service for team translation
 That's all!
 
 
-.. tip:: Translating on local and Transifex
+.. tip:: Translating locally and on Transifex
 
    If you want to push all language's po files, you can be done by using
    :command:`tx push -t` command.
-   Watch out! this operation overwrites translations in transifex.
+   Watch out! This operation overwrites translations in transifex.
 
    In other words, if you have updated each in the service and local po files,
    it would take much time and effort to integrate them.
@@ -270,7 +274,7 @@ Contributing to Sphinx reference translation
 The recommended way for new contributors to translate Sphinx reference
 is to join the translation team on Transifex.
 
-There is `sphinx translation page`_ for Sphinx-1.2 document.
+There is `sphinx translation page`_ for Sphinx-1.2 documentation.
 
 1. Login to transifex_ service.
 2. Go to `sphinx translation page`_.
diff --git a/doc/intro.rst b/doc/intro.rst
index 43e37b54..a796d937 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -16,6 +16,10 @@ Though there is support for that kind of docs as well (which is intended to be
 freely mixed with hand-written content), if you need pure API docs have a look
 at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST.
 
+For a great "introduction" to writing docs in general -- the whys and hows, see
+also `Write the docs <http://write-the-docs.readthedocs.org/>`_, written by Eric
+Holscher.
+
 
 Conversion from other systems
 -----------------------------
@@ -24,7 +28,7 @@ This section is intended to collect helpful hints for those wanting to migrate
 to reStructuredText/Sphinx from other documentation systems.
 
 * Gerard Flanagan has written a script to convert pure HTML to reST; it can be
-  found at the `Python Package Index <http://pypi.python.org/pypi/html2rest>`_.
+  found at the `Python Package Index <https://pypi.python.org/pypi/html2rest>`_.
 
 * For converting the old Python docs to Sphinx, a converter was written which
   can be found at `the Python SVN repository
@@ -35,7 +39,7 @@ to reStructuredText/Sphinx from other documentation systems.
   markup; it is at `Google Code <http://code.google.com/p/db2rst/>`_.
 
 * Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents
-  to Sphinx: `odt2sphinx <http://pypi.python.org/pypi/odt2sphinx/>`_.
+  to Sphinx: `odt2sphinx <https://pypi.python.org/pypi/odt2sphinx/>`_.
 
 * To convert different markups, `Pandoc <http://johnmacfarlane.net/pandoc/>`_ is
   a very helpful tool.
diff --git a/doc/invocation.rst b/doc/invocation.rst
index c6125ecc..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.
@@ -140,7 +149,8 @@ The :program:`sphinx-build` script has several options:
 .. option:: -n
 
    Run in nit-picky mode.  Currently, this generates warnings for all missing
-   references.
+   references.  See the config value :confval:`nitpick_ignore` for a way to
+   exclude some references as "known missing".
 
 .. option:: -N
 
@@ -269,7 +279,7 @@ The :program:`sphinx-apidoc` script has several options:
    filesystem to discover packages and modules. You may need it if you want
    to generate documentation from a source directory managed by
    `collective.recipe.omelette
-   <http://pypi.python.org/pypi/collective.recipe.omelette/>`_.
+   <https://pypi.python.org/pypi/collective.recipe.omelette/>`_.
    By default, symbolic links are skipped.
 
    .. versionadded:: 1.2
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst
index 0a5d4abb..aa1d71c6 100644
--- a/doc/man/sphinx-build.rst
+++ b/doc/man/sphinx-build.rst
@@ -32,6 +32,13 @@ List of available builders:
 html
    HTML file generation.  This is the default builder.
 
+dirhtml
+   HTML file generation with every HTML file named "index.html" in a separate
+   directory.
+
+singlehtml
+   HTML file generation with all content in a single HTML file.
+
 htmlhelp
    Generates files for CHM (compiled help files) generation.
 
@@ -51,9 +58,15 @@ texinfo
    Generates Texinfo output that can be processed by :program:`makeinfo` to
    generate an Info document.
 
+epub
+   Generates an ePub e-book version of the HTML output.
+
 text
    Generates a plain-text version of the documentation.
 
+gettext
+   Generates Gettext message catalogs for content translation.
+
 changes
    Generates HTML files listing changed/added/deprecated items for
    the current version of the documented project.
@@ -81,20 +94,24 @@ Options
                       output for new and changed files is generated.
 -E                    Ignore cached files, forces to re-read all source files
                       from disk.
+-d <path>             Path to cached files; defaults to <outdir>/.doctrees.
+-j <N>                Build in parallel with N processes where possible.
 -c <path>             Locate the conf.py file in the specified path instead of
                       <sourcedir>.
 -C                    Specify that no conf.py file at all is to be used.
                       Configuration can only be set with the -D option.
 -D <setting=value>    Override a setting from the configuration file.
--d <path>             Path to cached files; defaults to <outdir>/.doctrees.
+-t <tag>              Define *tag* for use in "only" blocks.
 -A <name=value>       Pass a value into the HTML templates (only for HTML builders).
 -n                    Run in nit-picky mode, warn about all missing references.
+-v                    Increase verbosity (can be repeated).
 -N                    Prevent colored output.
 -q                    Quiet operation, just print warnings and errors on stderr.
 -Q                    Very quiet operation, don't print anything except for errors.
 -w <file>             Write warnings and errors into the given file, in addition
                       to stderr.
 -W                    Turn warnings into errors.
+-T                    Show full traceback on exception.
 -P                    Run Pdb on exception.
 
 
diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index c0e7e8eb..6e707e00 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -62,8 +62,8 @@ installed) and handled in a smart way:
   * ``c``
   * ... and any other lexer name that Pygments supports.
 
-* If highlighting with the selected language fails, the block is not highlighted
-  in any way.
+* If highlighting with the selected language fails (i.e. Pygments emits an
+  "Error" token), the block is not highlighted in any way.
 
 Line numbers
 ^^^^^^^^^^^^
@@ -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
diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst
index 10ba491e..b2e9051f 100644
--- a/doc/markup/misc.rst
+++ b/doc/markup/misc.rst
@@ -176,8 +176,9 @@ Including content based on tags
       .. only:: html and draft
 
    Undefined tags are false, defined tags (via the ``-t`` command-line option or
-   within :file:`conf.py`) are true.  Boolean expressions, also using
-   parentheses (like ``html and (latex or draft)``) are supported.
+   within :file:`conf.py`, see :ref:`here <conf-tags>`) are true.  Boolean
+   expressions, also using parentheses (like ``html and (latex or draft)``) are
+   supported.
 
    The *format* and the *name* of the current builder (``html``, ``latex`` or
    ``text``) are always set as a tag [#]_.  To make the distinction between
@@ -185,6 +186,9 @@ Including content based on tags
    ``builder_``, e.g. the epub builder defines the tags  ``html``, ``epub``,
    ``format_html`` and ``builder_epub``.
 
+   These standard tags are set *after* the configuration file is read, so they
+   are not available there.
+
    .. versionadded:: 0.6
    .. versionchanged:: 1.2
       Added the name of the builder and the prefixes.
@@ -212,9 +216,9 @@ following directive exists:
    ``p{width}`` construct, or tabulary's automatic specifiers:
 
    +-----+------------------------------------------+
-   |``L``| ragged-left column with automatic width  |
+   |``L``| flush left column with automatic width   |
    +-----+------------------------------------------+
-   |``R``| ragged-right column with automatic width |
+   |``R``| flush right column with automatic width  |
    +-----+------------------------------------------+
    |``C``| centered column with automatic width     |
    +-----+------------------------------------------+
diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index c17fb9b0..fdecc37d 100644
--- a/doc/markup/toctree.rst
+++ b/doc/markup/toctree.rst
@@ -68,8 +68,8 @@ tables of contents.  The ``toctree`` directive is the central element.
 
    **Section numbering**
 
-   If you want to have section numbers even in HTML output, give the toctree a
-   ``numbered`` option.  For example::
+   If you want to have section numbers even in HTML output, give the
+   **toplevel** toctree a ``numbered`` option.  For example::
 
       .. toctree::
          :numbered:
@@ -141,9 +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:`unused_docs` to
-   explicitly exclude documents from building, and :confval:`exclude_trees` to
-   exclude whole directories.
+   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
diff --git a/doc/rest.rst b/doc/rest.rst
index ccfdf11d..b35ebc91 100644
--- a/doc/rest.rst
+++ b/doc/rest.rst
@@ -373,6 +373,8 @@ For instance, if the file name ``gnu.*`` was given and two files :file:`gnu.pdf`
 and :file:`gnu.png` existed in the source tree, the LaTeX builder would choose
 the former, while the HTML builder would prefer the latter.
 
+Note that image file names should not contain spaces.
+
 .. versionchanged:: 0.4
    Added the support for file names ending in an asterisk.
 
diff --git a/doc/templating.rst b/doc/templating.rst
index b9dfc683..b9561b69 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -251,7 +251,8 @@ in the future.
 
 .. data:: docstitle
 
-   The title of the documentation (the value of :confval:`html_title`).
+   The title of the documentation (the value of :confval:`html_title`), except
+   when the "single-file" builder is used, when it is set to ``None``.
 
 .. data:: embedded
 
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 9fea11db..8e949d4c 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -248,11 +248,40 @@ Therefore, you must add the appropriate path to :py:data:`sys.path` in your
 |more| See :mod:`sphinx.ext.autodoc` for the complete description of the
 features of autodoc.
 
+Intersphinx
+-----------
+
+Many Sphinx documents including the `Python documentation`_ are published on the
+internet.  When you want to make links to such documents from your
+documentation, you can do it with :mod:`sphinx.ext.intersphinx`.
+
+.. _Python documentation: http://docs.python.org/3
+
+In order to use intersphinx, you need to activate it in :file:`conf.py` by
+putting the string ``'sphinx.ext.intersphinx'`` into the :confval:`extensions`
+list and set up the :confval:`intersphinx_mapping` config value.
+
+For example, to link to ``io.open()`` in the Python library manual, you need to
+setup your :confval:`intersphinx_mapping` like::
+
+   intersphinx_mapping = {'python': ('http://docs.python.org/3', None)}
+
+And now, you can write a cross-reference like ``:py:func:`io.open```.  Any
+cross-reference that has no matching target in the current documentation set,
+will be looked up in the documentation sets configured in
+:confval:`intersphinx_mapping` (this needs access to the URL in order to
+download the list of valid targets).  Intersphinx also works for some other
+:ref:`domains' <domains>` roles including ``:ref:``, however it doesn't work for
+``:doc:`` as that is non-domain role.
+
+|more| See :mod:`sphinx.ext.intersphinx` for the complete description of the
+features of intersphinx.
+
 
 More topics to be covered
 -------------------------
 
-- Other extensions (math, intersphinx, viewcode, doctest)
+- Other extensions (math, viewcode, doctest)
 - Static files
 - Selecting a theme
 - Templating