Merge branch '3.x' into 4422_support_GenericAlias

15 files changed, 867 insertions, 697 deletions

diff --git a/CHANGES b/CHANGES
index 8d82ad985..2cbffbd4f 100644
--- a/CHANGES
+++ b/CHANGES
@@ -49,6 +49,7 @@ Features added
 * #7143: autodoc: Support final classes and methods
 * #7384: autodoc: Support signatures defined by ``__new__()``, metaclasses and
   builtin base classes
+* #2106: autodoc: Support multiple signatures on docstring
 * #4422: autodoc: Support GenericAlias in Python 3.7 or above
 * #7466: autosummary: headings in generated documents are not translated
 * #7490: autosummary: Add ``:caption:`` option to autosummary directive to set a
diff --git a/doc/contents.rst b/doc/contents.rst
index 7e87cfffa..f58655cbf 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -1,4 +1,3 @@
-
 .. _contents:
 
 Sphinx documentation contents
@@ -7,26 +6,14 @@ Sphinx documentation contents
 .. toctree::
    :maxdepth: 2
 
-   intro
-
-   usage/installation
-   usage/quickstart
-   usage/restructuredtext/index
-   usage/markdown
-   usage/configuration
-   usage/builders/index
-   usage/extensions/index
-   usage/theming
-   usage/advanced/intl
-   usage/advanced/setuptools
-   usage/advanced/websupport/index
-
+   usage/index
+   development/index
    man/index
+
    theming
    templating
    latex
    extdev/index
-   development/tutorials/index
 
    faq
    glossary
diff --git a/doc/development/index.rst b/doc/development/index.rst
new file mode 100644
index 000000000..6a3406a20
--- /dev/null
+++ b/doc/development/index.rst
@@ -0,0 +1,13 @@
+================
+Extending Sphinx
+================
+
+This guide is aimed at those wishing to develop their own extensions for
+Sphinx. Sphinx possesses significant extensibility capabilities including the
+ability to hook into almost every point of the build process.  If you simply
+wish to use Sphinx with existing extensions, refer to :doc:`/usage/index`.
+
+.. toctree::
+   :maxdepth: 2
+
+   tutorials/index
diff --git a/doc/faq.rst b/doc/faq.rst
index 28d14d79e..49723d134 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -148,6 +148,43 @@ Google Search
 .. _xhtml to reST: http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py
 
 
+Sphinx vs. Docutils
+-------------------
+
+tl;dr: *docutils* converts reStructuredText to multiple output formats. Sphinx
+builds upon docutils to allow construction of cross-referenced and indexed
+bodies of documentation.
+
+`docutils`__ is a text processing system for converting plain text
+documentation into other, richer formats. As noted in the `docutils
+documentation`__, docutils uses *readers* to read a document, *parsers* for
+parsing plain text formats into an internal tree representation made up of
+different types of *nodes*, and *writers* to output this tree in various
+document formats.  docutils provides parsers for one plain text format -
+`reStructuredText`__ - though other, *out-of-tree* parsers have been
+implemented including Sphinx's :doc:`Markdown parser </usage/markdown>`. On the
+other hand, it provides writers for many different formats including HTML,
+LaTeX, man pages, Open Document Format and XML.
+
+docutils exposes all of its functionality through a variety of `front-end
+tools`__, such as ``rst2html``, ``rst2odt`` and ``rst2xml``. Crucially though,
+all of these tools, and docutils itself, are concerned with individual
+documents.  They don't support concepts such as cross-referencing, indexing of
+documents, or the construction of a document hierarchy (typically manifesting
+in a table of contents).
+
+Sphinx builds upon docutils by harnessing docutils' readers and parsers and
+providing its own :doc:`/usage/builders/index`. As a result, Sphinx wraps some
+of the *writers* provided by docutils. This allows Sphinx to provide many
+features that would simply not be possible with docutils, such as those
+outlined above.
+
+__ http://docutils.sourceforge.io/
+__ http://docutils.sourceforge.io/docs/dev/hacking.html
+__ http://docutils.sourceforge.io/rst.html
+__ http://docutils.sourceforge.net/docs/user/tools.html
+
+
 .. _epub-faq:
 
 Epub info
diff --git a/doc/intro.rst b/doc/intro.rst
deleted file mode 100644
index 3e684a974..000000000
--- a/doc/intro.rst
+++ /dev/null
@@ -1,71 +0,0 @@
-Introduction
-============
-
-This is the documentation for the Sphinx documentation builder.  Sphinx is a
-tool that translates a set of reStructuredText_ source files into various output
-formats, automatically producing cross-references, indices, etc.  That is, if
-you have a directory containing a bunch of reST-formatted documents (and
-possibly subdirectories of docs in there as well), Sphinx can generate a
-nicely-organized arrangement of HTML files (in some other directory) for easy
-browsing and navigation.  But from the same source, it can also generate a PDF
-file using LaTeX.
-
-The focus is on hand-written documentation, rather than auto-generated API docs.
-Though there is support for that kind of documentation 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.sourceforge.net/>`_, which also
-understands reST.
-
-For a great "introduction" to writing docs in general -- the whys and hows, see
-also `Write the docs`_, written by Eric Holscher.
-
-.. _rinohtype: https://github.com/brechtm/rinohtype
-.. _Write the docs: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
-
-Conversion from other systems
------------------------------
-
-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 <https://pypi.org/project/html2rest/>`_.
-
-* For converting the old Python docs to Sphinx, a converter was written which
-  can be found at `the Python SVN repository
-  <https://svn.python.org/projects/doctools/converter/>`_.  It contains generic
-  code to convert Python-doc-style LaTeX markup to Sphinx reST.
-
-* Marcin Wojdyr has written a script to convert Docbook to reST with Sphinx
-  markup; it is at `GitHub <https://github.com/wojdyr/db2rst>`_.
-
-* Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents
-  to Sphinx: `odt2sphinx <https://pypi.org/project/odt2sphinx/>`_.
-
-* To convert different markups, `Pandoc <https://pandoc.org/>`_ is
-  a very helpful tool.
-
-
-Use with other systems
-----------------------
-
-See the :ref:`pertinent section in the FAQ list <usingwith>`.
-
-
-Prerequisites
--------------
-
-Sphinx needs at least **Python 3.5** to run.
-It also depends on 3rd party libraries such as docutils_ and jinja2_, but they
-are automatically installed when sphinx is installed.
-
-.. _reStructuredText: http://docutils.sourceforge.net/rst.html
-.. _docutils: http://docutils.sourceforge.net/
-.. _Jinja2: http://jinja.pocoo.org/
-
-
-Usage
------
-
-See :doc:`/usage/quickstart` for an introduction.  It also contains links to
-more advanced sections in this manual for the topics it discusses.
diff --git a/doc/latex.rst b/doc/latex.rst
index 59a785c1e..53fe9301a 100644
--- a/doc/latex.rst
+++ b/doc/latex.rst
@@ -1,7 +1,3 @@
-.. highlight:: python
-
-.. _latex:
-
 LaTeX customization
 ===================
 
@@ -26,24 +22,12 @@ LaTeX customization
          cautionBgColor={named}{LightCyan}}
    \relax
 
-The *latex* target does not benefit from prepared themes.
-
-The :ref:`latex-options`, and particularly among them the
-:ref:`latex_elements <latex_elements_confval>` variable
-provides much of the interface for customization.
-
-For some details of the LaTeX/PDF builder command line
-invocation, refer to :py:class:`~sphinx.builders.latex.LaTeXBuilder`.
-
-.. _latex-basic:
-
-Example
--------
+Unlike :ref:`the HTML builders <html-themes>`, the ``latex`` builder does not
+benefit from prepared themes. The :ref:`latex-options`, and particularly the
+:ref:`latex_elements <latex_elements_confval>` variable, provides much of the
+interface for customization. For example:
 
-Keep in mind that backslashes must be doubled in Python string literals to
-avoid interpretation as escape sequences, or use raw strings (as is done here).
-
-::
+.. code-block:: python
 
    # inside conf.py
    latex_engine = 'xelatex'
@@ -65,433 +49,487 @@ avoid interpretation as escape sequences, or use raw strings (as is done here).
    }
    latex_show_urls = 'footnote'
 
-.. highlight:: latex
+.. note::
+
+   Keep in mind that backslashes must be doubled in Python string literals to
+   avoid interpretation as escape sequences. Alternatively, you may use raw
+   strings as is done above.
 
 .. _latex_elements_confval:
 
-The latex_elements configuration setting
-----------------------------------------
+The ``latex_elements`` configuration setting
+--------------------------------------------
 
 A dictionary that contains LaTeX snippets overriding those Sphinx usually puts
 into the generated ``.tex`` files.  Its ``'sphinxsetup'`` key is described
 :ref:`separately <latexsphinxsetup>`.
 
-* Keys that you may want to override include:
-
-  ``'papersize'``
-     Paper size option of the document class (``'a4paper'`` or
-     ``'letterpaper'``), default ``'letterpaper'``.
-
-  ``'pointsize'``
-     Point size option of the document class (``'10pt'``, ``'11pt'`` or
-     ``'12pt'``), default ``'10pt'``.
-
-  ``'pxunit'``
-     the value of the ``px`` when used in image attributes ``width`` and
-     ``height``. The default value is ``'0.75bp'`` which achieves
-     ``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for
-     example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter
-     leads to TeX computing a more precise value, due to the smaller unit
-     used in the specification); for ``72px=1in``, simply use ``'1bp'``; for
-     ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``.
-
-     .. versionadded:: 1.5
-
-  ``'passoptionstopackages'``
-     A string which will be positioned early in the preamble, designed to
-     contain ``\\PassOptionsToPackage{options}{foo}`` commands. Default empty.
-
-     .. versionadded:: 1.4
-
-  ``'babel'``
-     "babel" package inclusion, default ``'\\usepackage{babel}'`` (the
-     suitable document language string is passed as class option, and
-     ``english`` is used if no language.) For Japanese documents, the
-     default is the empty string.
-
-     With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use
-     `polyglossia`_, but one should be aware that current `babel`_ has
-     improved its support for Unicode engines in recent years and for some
-     languages it may make sense to prefer ``babel`` over ``polyglossia``.
-
-     .. hint::
-
-        After modifiying a core LaTeX key like this one, clean up the LaTeX
-        build repertory before next PDF build, else left-over auxiliary
-        files are likely to break the build.
-
-     .. _`polyglossia`: https://ctan.org/pkg/polyglossia
-     .. _`babel`: https://ctan.org/pkg/babel
-
-     .. versionchanged:: 1.5
-        For :confval:`latex_engine` set to ``'xelatex'``, the default
-        is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
-     .. versionchanged:: 1.6
-        ``'lualatex'`` uses same default setting as ``'xelatex'``
-     .. versionchanged:: 1.7.6
-        For French, ``xelatex`` and ``lualatex`` default to using
-        ``babel``, not ``polyglossia``.
-
-  ``'fontpkg'``
-     Font package inclusion, the default is ``'\\usepackage{times}'`` which
-     uses Times for text, Helvetica for sans serif and Courier for monospace.
-
-     .. versionchanged:: 1.2
-        Defaults to ``''`` when the :confval:`language` uses the Cyrillic
-        script.
-     .. versionchanged:: 2.0
-        Support for individual Greek and Cyrillic letters:
-
-        - In order to support occasional Cyrillic (физика частиц)
-          or Greek letters (Σωματιδιακή φυσική) in
-          a document whose language is English or a  Latin European
-          one, the default set-up is enhanced (only for ``'pdflatex'``
-          engine) to do:
+Keys that you may want to override include:
+
+``'papersize'``
+   Paper size option of the document class (``'a4paper'`` or
+   ``'letterpaper'``)
+
+   Default: ``'letterpaper'``
+
+``'pointsize'``
+   Point size option of the document class (``'10pt'``, ``'11pt'`` or
+   ``'12pt'``)
+
+   Default: ``'10pt'``
+
+``'pxunit'``
+   The value of the ``px`` when used in image attributes ``width`` and
+   ``height``. The default value is ``'0.75bp'`` which achieves
+   ``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for
+   example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter
+   leads to TeX computing a more precise value, due to the smaller unit
+   used in the specification); for ``72px=1in``, simply use ``'1bp'``; for
+   ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``.
+
+   Default: ``'0.75bp'``
+
+   .. versionadded:: 1.5
+
+``'passoptionstopackages'``
+   A string which will be positioned early in the preamble, designed to
+   contain ``\\PassOptionsToPackage{options}{foo}`` commands.
+
+   Default: ``''``
+
+   .. versionadded:: 1.4
+
+``'babel'``
+   "babel" package inclusion, default ``'\\usepackage{babel}'`` (the
+   suitable document language string is passed as class option, and
+   ``english`` is used if no language.) For Japanese documents, the
+   default is the empty string.
+
+   With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use
+   `polyglossia`_, but one should be aware that current `babel`_ has
+   improved its support for Unicode engines in recent years and for some
+   languages it may make sense to prefer ``babel`` over ``polyglossia``.
+
+   .. _`polyglossia`: https://ctan.org/pkg/polyglossia
+   .. _`babel`: https://ctan.org/pkg/babel
+
+   .. hint::
+
+      After modifiying a core LaTeX key like this one, clean up the LaTeX
+      build repertory before next PDF build, else left-over auxiliary
+      files are likely to break the build.
+
+   Default:  ``'\\usepackage{babel}'`` (``''`` for Japanese documents)
+
+   .. versionchanged:: 1.5
+      For :confval:`latex_engine` set to ``'xelatex'``, the default
+      is ``'\\usepackage{polyglossia}\n\\setmainlanguage{<language>}'``.
+
+   .. versionchanged:: 1.6
+      ``'lualatex'`` uses same default setting as ``'xelatex'``
+
+   .. versionchanged:: 1.7.6
+      For French, ``xelatex`` and ``lualatex`` default to using
+      ``babel``, not ``polyglossia``.
+
+``'fontpkg'``
+   Font package inclusion. The default of ``'\\usepackage{times}'`` uses Times
+   for text, Helvetica for sans serif and Courier for monospace.
+
+   In order to support occasional Cyrillic (физика частиц) or Greek
+   letters (Σωματιδιακή φυσική) in a document whose language is
+   English or a Latin European one, the default set-up is enhanced (only for
+   ``'pdflatex'`` engine) to do:
+
+   .. code-block:: latex
+
+      \substitutefont{LGR}{\rmdefault}{cmr}
+      \substitutefont{LGR}{\sfdefault}{cmss}
+      \substitutefont{LGR}{\ttdefault}{cmtt}
+      \substitutefont{X2}{\rmdefault}{cmr}
+      \substitutefont{X2}{\sfdefault}{cmss}
+      \substitutefont{X2}{\ttdefault}{cmtt}
+
+   This is activated only under the condition that the ``'fontenc'`` key is
+   configured to load the ``LGR`` (Greek) and/or ``X2`` (Cyrillic)
+   pdflatex-font encodings (if the :confval:`language` is set to a Cyrillic
+   language, this ``'fontpkg'`` key must be used as "times" package has no
+   direct support for it; then keep only ``LGR`` lines from the above, if
+   support is needed for Greek in the text).
+
+   The ``\substitutefont`` command is from the eponymous LaTeX package, which
+   is loaded by Sphinx if needed (on Ubuntu Xenial it is part of
+   ``texlive-latex-extra`` which is a Sphinx requirement).
+
+   Only if the document actually does contain Unicode Greek letters (in text)
+   or Cyrillic letters, will the above default set-up cause additional
+   requirements for the PDF build. On Ubuntu Xenial, these are the
+   ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and (with the above
+   choice of fonts) the ``cm-super`` (or ``cm-super-minimal``) packages.
+
+   For ``'xelatex'`` and ``'lualatex'``, the default is to use the FreeFont
+   family: this OpenType font family supports both Cyrillic and Greek scripts
+   and is available as separate Ubuntu Xenial package ``fonts-freefont-otf``.
+   It is not necessary to install the much larger ``texlive-fonts-extra``
+   package.
+
+   ``'platex'`` (Japanese documents) engine supports individual Cyrillic and
+   Greek letters with no need of extra user set-up.
+
+   Default: ``'\\usepackage{times}'`` (or ``''`` when using a Cyrillic script)
+
+   .. versionchanged:: 1.2
+      Defaults to ``''`` when the :confval:`language` uses the Cyrillic
+      script.
+
+   .. versionchanged:: 2.0
+      Added support for individual Greek and Cyrillic letters:
+
+``'fncychap'``
+   Inclusion of the "fncychap" package (which makes fancy chapter titles),
+   default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation
+   (this option is slightly customized by Sphinx),
+   ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because
+   the "Bjarne" style uses numbers spelled out in English).  Other
+   "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and
+   "Bjornstrup".  You can also set this to ``''`` to disable fncychap.
+
+   Default: ``'\\usepackage[Bjarne]{fncychap}'`` for English documents,
+       ``'\\usepackage[Sonny]{fncychap}'`` for internationalized documents, and
+       ``''`` for Japanese documents.
+
+``'preamble'``
+   Additional preamble content.  One may move all needed macros into some file
+   :file:`mystyle.tex.txt` of the project source repertory, and get LaTeX to
+   import it at run time::
+
+     'preamble': r'\input{mystyle.tex.txt}',
+     # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
+     'preamble': r'\usepackage{mystyle}',
+
+   It is then needed to set appropriately :confval:`latex_additional_files`,
+   for example:
+
+   .. code-block:: python
+
+      latex_additional_files = ["mystyle.sty"]
+
+   Default: ``''``
+
+``'figure_align'``
+   Latex figure float alignment. Whenever an image doesn't fit into the current
+   page, it will be 'floated' into the next page but may be preceded by any
+   other text.  If you don't like this behavior, use 'H' which will disable
+   floating and position figures strictly in the order they appear in the
+   source.
+
+   Default: ``'htbp'`` (here, top, bottom, page)
+
+   .. versionadded:: 1.3
+
+``'atendofbody'``
+   Additional document content (right before the indices).
+
+   Default: ``''``
+
+   .. versionadded:: 1.5
+
+``'extrapackages'``
+   Additional LaTeX packages.  For example:
+
+   .. code-block:: python
+
+       latex_elements = {
+           'packages': r'\usepackage{isodate}'
+       }
+
+   The specified LaTeX packages will be loaded before
+   hyperref package and packages loaded from Sphinx extensions.
+
+   .. hint::
+      If you'd like to load additional LaTeX packages after hyperref, use
+      ``'preamble'`` key instead.
+
+   Default: ``''``
+
+   .. versionadded:: 2.3
+
+``'footer'``
+   Additional footer content (before the indices).
+
+   Default: ``''``
+
+   .. deprecated:: 1.5
+      Use ``'atendofbody'`` key instead.
+
+Keys that don't need to be overridden unless in special cases are:
+
+``'extraclassoptions'``
+   The default is the empty string. Example: ``'extraclassoptions':
+   'openany'`` will allow chapters (for documents of the ``'manual'``
+   type) to start on any page.
+
+   Default: ``''``
+
+   .. versionadded:: 1.2
+
+   .. versionchanged:: 1.6
+      Added this documentation.
+
+``'maxlistdepth'``
+   LaTeX allows by default at most 6 levels for nesting list and
+   quote-like environments, with at most 4 enumerated lists, and 4 bullet
+   lists. Setting this key for example to ``'10'`` (as a string) will
+   allow up to 10 nested levels (of all sorts). Leaving it to the empty
+   string means to obey the LaTeX default.
+
+   .. warning::
+
+      - Using this key may prove incompatible with some LaTeX packages
+        or special document classes which do their own list customization.
+
+      - The key setting is silently *ignored* if ``\usepackage{enumitem}``
+        is executed inside the document preamble. Use then rather the
+        dedicated commands of this LaTeX package.
+
+   Default: ``6``
+
+   .. versionadded:: 1.5
+
+``'inputenc'``
+   "inputenc" package inclusion.
+
+   Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else
+       ``''``
+
+   .. versionchanged:: 1.4.3
+      Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
+      compilers.
+
+``'cmappkg'``
+   "cmap" package inclusion.
+
+   Default: ``'\\usepackage{cmap}'``
+
+   .. versionadded:: 1.2
 
-          .. code-block:: latex
+``'fontenc'``
+   "fontenc" package inclusion.
 
-             \substitutefont{LGR}{\rmdefault}{cmr}
-             \substitutefont{LGR}{\sfdefault}{cmss}
-             \substitutefont{LGR}{\ttdefault}{cmtt}
-             \substitutefont{X2}{\rmdefault}{cmr}
-             \substitutefont{X2}{\sfdefault}{cmss}
-             \substitutefont{X2}{\ttdefault}{cmtt}
+   If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR``
+   for support of Greek letters in the document, and also ``X2`` (or
+   ``T2A``) for Cyrillic letters, like this:
 
-          but this is activated only under the condition that the
-          ``'fontenc'`` key is configured to load the ``LGR`` (Greek)
-          and/or ``X2`` (Cyrillic) pdflatex-font encodings (if the
-          :confval:`language` is set to a Cyrillic language, this
-          ``'fontpkg'`` key must be used as "times" package has no direct
-          support for it; then keep only ``LGR`` lines from the above,
-          if support is needed for Greek in the text).
+   .. code-block:: latex
 
-          The ``\substitutefont`` command is from the eponymous LaTeX
-          package, which is loaded by Sphinx if needed (on Ubuntu xenial it
-          is part of ``texlive-latex-extra`` which is a Sphinx
-          requirement).
+      r'\usepackage[LGR,X2,T1]{fontenc}'
 
-          Only if the document actually does contain Unicode Greek letters
-          (in text) or Cyrillic letters, will the above default set-up
-          cause additional requirements for the PDF build.  On Ubuntu
-          xenial, ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and
-          (with the above choice of fonts) the ``cm-super`` (or
-          ``cm-super-minimal``) package.
-
-        - For ``'xelatex'`` and ``'lualatex'``, the default is to
-          use the FreeFont family:  this OpenType font family
-          supports both Cyrillic and Greek scripts and is available as
-          separate Ubuntu xenial package ``fonts-freefont-otf``, it is not
-          needed to install the big package ``texlive-fonts-extra``.
-
-        - ``'platex'`` (Japanese documents) engine supports individual
-          Cyrillic and Greek letters with no need of extra user set-up.
+   .. attention::
 
-  ``'fncychap'``
-     Inclusion of the "fncychap" package (which makes fancy chapter titles),
-     default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation
-     (this option is slightly customized by Sphinx),
-     ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because
-     the "Bjarne" style uses numbers spelled out in English).  Other
-     "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and
-     "Bjornstrup".  You can also set this to ``''`` to disable fncychap.
+      If Greek is main language, do not use this key.  Since Sphinx 2.2.1,
+      ``xelatex`` will be used automatically as :confval:`latex_engine`.
+      Formerly, Sphinx did not support producing PDF via LaTeX with Greek as
+      main language.
 
-     The default is ``''`` for Japanese documents.
+      Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math
+      mark-up.  This is not the case anymore, and the above must be used
+      (only in case of ``'pdflatex'`` engine) if the source contains such
+      Unicode Greek.
 
-  ``'preamble'``
-     Additional preamble content, default empty.  One may move all needed
-     macros into some file :file:`mystyle.tex.txt` of the project source
-     repertory, and get LaTeX to import it at run time::
+      On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
+      (for the latter, only if the ``'fontpkg'`` setting is left to its
+      default) are needed for ``LGR`` to work.  In place of ``cm-super``
+      one can install smaller ``cm-super-minimal``, but it requires the
+      LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before
+      loading ``fontenc``.  Thus, use this key with this extra at its
+      start if needed.
 
-       'preamble': r'\input{mystyle.tex.txt}',
-       # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty
-       'preamble': r'\usepackage{mystyle}',
+   Default: ``'\\usepackage[T1]{fontenc}'``
 
-     It is then needed to set appropriately
-     :confval:`latex_additional_files`, for example::
+   .. versionchanged:: 1.5
+      Defaults to ``'\\usepackage{fontspec}'`` when
+      :confval:`latex_engine` is ``'xelatex'``.
 
-        latex_additional_files = ["mystyle.sty"]
+   .. versionchanged:: 1.6
+      ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``.
 
+   .. versionchanged:: 2.0
+      ``'lualatex'`` executes
+      ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX
+      ligatures transforming `<<` and `>>` as escaping working with
+      ``pdflatex/xelatex`` failed with ``lualatex``.
 
-  ``'figure_align'``
-     Latex figure float alignment, default 'htbp' (here, top, bottom, page).
-     Whenever an image doesn't fit into the current page, it will be
-     'floated' into the next page but may be preceded by any other text.
-     If you don't like this behavior, use 'H' which will disable floating
-     and position figures strictly in the order they appear in the source.
+   .. versionchanged:: 2.0
+      Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of
+      occasional Greek or Cyrillic (``'pdflatex'`` only, as this support
+      is provided natively by ``'platex'`` and only requires suitable
+      font with ``'xelatex'/'lualatex'``).
 
-     .. versionadded:: 1.3
+   .. versionchanged:: 2.3.0
+      ``'xelatex'`` also executes
+      ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid
+      contractions of ``--`` into en-dash or transforms of straight quotes
+      into curly ones in PDF (in non-literal text paragraphs) despite
+      :confval:`smartquotes` being set to ``False``.
 
-  ``'atendofbody'``
-     Additional document content (right before the indices), default empty.
+``'textgreek'``
+   This is needed for ``pdflatex`` to support Unicode input of Greek
+   letters such as φύσις.  Expert users may want to load the ``textalpha``
+   package with its option ``normalize-symbols``.
 
-     .. versionadded:: 1.5
+   .. hint::
 
-  ``'extrapackages'``
-     Additional LaTeX packages.  For example:
+      Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
+      can be supported by ``'pdflatex'`` from setting this key to
+      ``r'\usepackage{textalpha,alphabeta}'``.  Then ``:math:`α``` (U+03B1)
+      will render as :math:`\alpha`.  For wider Unicode support in math
+      input, see the discussion of :confval:`latex_engine`.
 
-     .. code-block:: python
+   With ``'platex'`` (Japanese),  ``'xelatex'`` or ``'lualatex'``, this
+   key is ignored.
 
-         latex_elements = {
-             'packages': r'\usepackage{isodate}'
-         }
+   Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not
+       include the ``LGR`` option.
 
-     It defaults to empty.
-
-     The specified LaTeX packages will be loaded before
-     hyperref package and packages loaded from Sphinx extensions.
-
-     .. hint:: If you'd like to load additional LaTeX packages after hyperref, use
-               ``'preamble'`` key instead.
-
-     .. versionadded:: 2.3
-
-  ``'footer'``
-     Additional footer content (before the indices), default empty.
-
-     .. deprecated:: 1.5
-        Use ``'atendofbody'`` key instead.
-
-* Keys that don't need to be overridden unless in special cases are:
-
-  ``'extraclassoptions'``
-     The default is the empty string. Example: ``'extraclassoptions':
-     'openany'`` will allow chapters (for documents of the ``'manual'``
-     type) to start on any page.
-
-     .. versionadded:: 1.2
-     .. versionchanged:: 1.6
-        Added this documentation.
-
-  ``'maxlistdepth'``
-     LaTeX allows by default at most 6 levels for nesting list and
-     quote-like environments, with at most 4 enumerated lists, and 4 bullet
-     lists. Setting this key for example to ``'10'`` (as a string) will
-     allow up to 10 nested levels (of all sorts). Leaving it to the empty
-     string means to obey the LaTeX default.
+   .. versionadded:: 2.0
 
-     .. warning::
-
-        - Using this key may prove incompatible with some LaTeX packages
-          or special document classes which do their own list customization.
+``'geometry'``
+   "geometry" package inclusion, the default definition is:
 
-        - The key setting is silently *ignored* if ``\usepackage{enumitem}``
-          is executed inside the document preamble. Use then rather the
-          dedicated commands of this LaTeX package.
+     ``'\\usepackage{geometry}'``
 
-     .. versionadded:: 1.5
+   with an additional ``[dvipdfm]`` for Japanese documents.
+   The Sphinx LaTeX style file executes:
 
-  ``'inputenc'``
-     "inputenc" package inclusion, defaults to
-     ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex.
-     Otherwise empty.
+     ``\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}``
 
-     .. versionchanged:: 1.4.3
-        Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
-        compilers.
+   which can be customized via corresponding :ref:`'sphinxsetup' options
+   <latexsphinxsetup>`.
 
-  ``'cmappkg'``
-     "cmap" package inclusion, default ``'\\usepackage{cmap}'``.
+   Default: ``'\\usepackage{geometry}'`` (or
+       ``'\\usepackage[dvipdfm]{geometry}'`` for Japanese documents)
 
-     .. versionadded:: 1.2
+   .. versionadded:: 1.5
+
+   .. versionchanged:: 1.5.2
+      ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``.
+
+   .. versionadded:: 1.5.3
+      The :ref:`'sphinxsetup' keys for the margins
+      <latexsphinxsetuphmargin>`.
+
+   .. versionchanged:: 1.5.3
+      The location in the LaTeX file has been moved to after
+      ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after
+      insertion of ``'fontpkg'`` key. This is in order to handle the paper
+      layout options in a special way for Japanese documents: the text
+      width will be set to an integer multiple of the *zenkaku* width, and
+      the text height to an integer multiple of the baseline. See the
+      :ref:`hmargin <latexsphinxsetuphmargin>` documentation for more.
+
+``'hyperref'``
+   "hyperref" package inclusion; also loads package "hypcap" and issues
+   ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is
+   loaded and before executing the contents of ``'preamble'`` key.
+
+   .. attention::
+
+      Loading of packages "hyperref" and "hypcap" is mandatory.
+
+   .. versionadded:: 1.5
+      Previously this was done from inside :file:`sphinx.sty`.
+
+``'maketitle'``
+   "maketitle" call. Override if you want to generate a differently styled
+   title page.
+
+   .. hint::
+
+      If the key value is set to
+      ``r'\newcommand\sphinxbackoftitlepage{<Extra
+      material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
+      typeset on back of title page (``'manual'`` docclass only).
+
+   Default: ``'\\sphinxmaketitle'``
+
+   .. versionchanged:: 1.8.3
+      Original ``\maketitle`` from document class is not overwritten,
+      hence is re-usable as part of some custom setting for this key.
+
+   .. versionadded:: 1.8.3
+      ``\sphinxbackoftitlepage`` optional macro.  It can also be defined
+      inside ``'preamble'`` key rather than this one.
+
+``'releasename'``
+   Value that prefixes ``'release'`` element on title page.  As for *title* and
+   *author* used in the tuples of :confval:`latex_documents`, it is inserted as
+   LaTeX markup.
+
+   Default: ``'Release'``
+
+``'tableofcontents'``
+   "tableofcontents" call. The default of ``'\\sphinxtableofcontents'`` is a
+   wrapper of unmodified ``\tableofcontents``, which may itself be customized
+   by user loaded packages. Override if you want to generate a different table
+   of contents or put content between the title page and the TOC.
+
+   Default: ``'\\sphinxtableofcontents'``
+
+   .. versionchanged:: 1.5
+      Previously the meaning of ``\tableofcontents`` itself was modified
+      by Sphinx. This created an incompatibility with dedicated packages
+      modifying it also such as "tocloft" or "etoc".
+
+``'transition'``
+   Commands used to display transitions. Override if you want to display
+   transitions differently.
 
-  ``'fontenc'``
-     "fontenc" package inclusion, defaults to
-     ``'\\usepackage[T1]{fontenc}'``.
+   Default: ``'\n\n\\bigskip\\hrule\\bigskip\n\n'``
 
-     If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR``
-     for support of Greek letters in the document, and also ``X2`` (or
-     ``T2A``) for Cyrillic letters, like this:
+   .. versionadded:: 1.2
 
-     .. code-block:: latex
+   .. versionchanged:: 1.6
+      Remove unneeded ``{}`` after ``\\hrule``.
 
-        r'\usepackage[LGR,X2,T1]{fontenc}'
+``'printindex'``
+   "printindex" call, the last thing in the file. Override if you want to
+   generate the index differently or append some content after the index. For
+   example ``'\\footnotesize\\raggedright\\printindex'`` is advisable when the
+   index is full of long entries.
 
-     .. attention::
+   Default: ``'\\printindex'``
 
-        If Greek is main language, do not use this key.  Since Sphinx 2.2.1,
-        ``xelatex`` will be used automatically as :confval:`latex_engine`.
-        Formerly, Sphinx did not support producing PDF via LaTeX with Greek as
-        main language.
+``'fvset'``
+   Customization of ``fancyvrb`` LaTeX package. The default value of
+   ``'\\fvset{fontsize=\\small}'`` is used to adjust for the large character
+   width of the monospace font, used in code-blocks.  You may need to modify
+   this if you use custom fonts.
 
-        Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math
-        mark-up.  This is not the case anymore, and the above must be used
-        (only in case of ``'pdflatex'`` engine) if the source contains such
-        Unicode Greek.
+   Default: ``'\\fvset{fontsize=\\small}'``
 
-        On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
-        (for the latter, only if the ``'fontpkg'`` setting is left to its
-        default) are needed for ``LGR`` to work.  In place of ``cm-super``
-        one can install smaller ``cm-super-minimal``, but it requires the
-        LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before
-        loading ``fontenc``.  Thus, use this key with this extra at its
-        start if needed.
+   .. versionadded:: 1.8
 
-     .. versionchanged:: 1.5
-        Defaults to ``'\\usepackage{fontspec}'`` when
-        :confval:`latex_engine` is ``'xelatex'``.
-     .. versionchanged:: 1.6
-        ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``.
-     .. versionchanged:: 2.0
-        ``'lualatex'`` executes
-        ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX
-        ligatures transforming `<<` and `>>` as escaping working with
-        ``pdflatex/xelatex`` failed with ``lualatex``.
-     .. versionchanged:: 2.0
-        Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of
-        occasional Greek or Cyrillic (``'pdflatex'`` only, as this support
-        is provided natively by ``'platex'`` and only requires suitable
-        font with ``'xelatex'/'lualatex'``).
-     .. versionchanged:: 2.3.0
-        ``'xelatex'`` also executes
-        ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid
-        contractions of ``--`` into en-dash or transforms of straight quotes
-        into curly ones in PDF (in non-literal text paragraphs) despite
-        :confval:`smartquotes` being set to ``False``.
-
-  ``'textgreek'``
-     The default (``'pdflatex'`` only) is
-     ``'\\usepackage{textalpha}'``, but only if ``'fontenc'`` was
-     modified by user to include ``LGR`` option.  If not, the key
-     value will be forced to be the empty string.
-
-     This is needed for ``pdfLaTeX`` to support Unicode input of Greek
-     letters such as φύσις.  Expert users may want to load the ``textalpha``
-     package with its option ``normalize-symbols``.
-
-     .. hint::
-
-        Unicode Greek (but no further Unicode symbols) in :rst:dir:`math`
-        can be supported by ``'pdflatex'`` from setting this key to
-        ``r'\usepackage{textalpha,alphabeta}'``.  Then ``:math:`α``` (U+03B1)
-        will render as :math:`\alpha`.  For wider Unicode support in math
-        input, see the discussion of :confval:`latex_engine`.
-
-     With ``'platex'`` (Japanese),  ``'xelatex'`` or ``'lualatex'``, this
-     key is ignored.
-
-     .. versionadded:: 2.0
-  ``'geometry'``
-     "geometry" package inclusion, the default definition is:
-
-       ``'\\usepackage{geometry}'``
-
-     with an additional ``[dvipdfm]`` for Japanese documents.
-     The Sphinx LaTeX style file executes:
-
-       ``\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}``
-
-     which can be customized via corresponding :ref:`'sphinxsetup' options
-     <latexsphinxsetup>`.
-
-     .. versionadded:: 1.5
-
-     .. versionchanged:: 1.5.2
-        ``dvipdfm`` option if :confval:`latex_engine` is ``'platex'``.
-
-     .. versionadded:: 1.5.3
-        The :ref:`'sphinxsetup' keys for the margins
-        <latexsphinxsetuphmargin>`.
-
-     .. versionchanged:: 1.5.3
-        The location in the LaTeX file has been moved to after
-        ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after
-        insertion of ``'fontpkg'`` key. This is in order to handle the paper
-        layout options in a special way for Japanese documents: the text
-        width will be set to an integer multiple of the *zenkaku* width, and
-        the text height to an integer multiple of the baseline. See the
-        :ref:`hmargin <latexsphinxsetuphmargin>` documentation for more.
-
-  ``'hyperref'``
-     "hyperref" package inclusion; also loads package "hypcap" and issues
-     ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is
-     loaded and before executing the contents of ``'preamble'`` key.
-
-     .. attention::
-
-        Loading of packages "hyperref" and "hypcap" is mandatory.
-
-     .. versionadded:: 1.5
-        Previously this was done from inside :file:`sphinx.sty`.
-
-  ``'maketitle'``
-     "maketitle" call, default ``'\\sphinxmaketitle'``. Override
-     if you want to generate a differently styled title page.
-
-     .. hint::
-
-        If the key value is set to
-        ``r'\newcommand\sphinxbackoftitlepage{<Extra
-        material>}\sphinxmaketitle'``, then ``<Extra material>`` will be
-        typeset on back of title page (``'manual'`` docclass only).
-
-     .. versionchanged:: 1.8.3
-        Original ``\maketitle`` from document class is not overwritten,
-        hence is re-usable as part of some custom setting for this key.
-     .. versionadded:: 1.8.3
-        ``\sphinxbackoftitlepage`` optional macro.  It can also be defined
-        inside ``'preamble'`` key rather than this one.
-
-  ``'releasename'``
-     value that prefixes ``'release'`` element on title page, default
-     ``'Release'``. As for *title* and *author* used in the tuples of
-     :confval:`latex_documents`, it is inserted as LaTeX markup.
-
-  ``'tableofcontents'``
-     "tableofcontents" call, default ``'\\sphinxtableofcontents'`` (it is a
-     wrapper of unmodified ``\tableofcontents``, which may itself be
-     customized by user loaded packages.)
-     Override if
-     you want to generate a different table of contents or put content
-     between the title page and the TOC.
-
-     .. versionchanged:: 1.5
-        Previously the meaning of ``\tableofcontents`` itself was modified
-        by Sphinx. This created an incompatibility with dedicated packages
-        modifying it also such as "tocloft" or "etoc".
-
-  ``'transition'``
-     Commands used to display transitions, default
-     ``'\n\n\\bigskip\\hrule\\bigskip\n\n'``.  Override if you want to
-     display transitions differently.
+   .. versionchanged:: 2.0
+      Due to new default font choice for ``'xelatex'`` and ``'lualatex'``
+      (FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these
+      engines (and not ``\\fvset{fontsize=auto}``).
 
-     .. versionadded:: 1.2
-     .. versionchanged:: 1.6
-        Remove unneeded ``{}`` after ``\\hrule``.
+Keys that are set by other options and therefore should not be overridden are:
 
-  ``'printindex'``
-     "printindex" call, the last thing in the file, default
-     ``'\\printindex'``.  Override if you want to generate the index
-     differently or append some content after the index. For example
-     ``'\\footnotesize\\raggedright\\printindex'`` is advisable when the
-     index is full of long entries.
-
-  ``'fvset'``
-     Customization of ``fancyvrb`` LaTeX package.  Sphinx does by default
-     ``'fvset': '\\fvset{fontsize=\\small}'``, to adjust for the large
-     character width of the monospace font, used in code-blocks.
-     You may need to modify this if you use custom fonts.
-
-     .. versionadded:: 1.8
-     .. versionchanged:: 2.0
-        Due to new default font choice for ``'xelatex'`` and ``'lualatex'``
-        (FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these
-        engines (and not ``\\fvset{fontsize=auto}``).
-
-* Keys that are set by other options and therefore should not be overridden
-  are:
-
-  ``'docclass'``
-  ``'classoptions'``
-  ``'title'``
-  ``'release'``
-  ``'author'``
-  ``'makeindex'``
+``'docclass'``
+``'classoptions'``
+``'title'``
+``'release'``
+``'author'``
+``'makeindex'``
 
 
 .. _latexsphinxsetup:
 
-\\'sphinxsetup\\' key
----------------------
+The ``sphinxsetup`` configuration setting
+-----------------------------------------
+
+.. versionadded:: 1.5
 
 The ``'sphinxsetup'`` key of :ref:`latex_elements <latex_elements_confval>`
 provides a LaTeX-type customization interface::
@@ -506,46 +544,40 @@ It defaults to empty.  If non-empty, it will be passed as argument to the
    \usepackage{sphinx}
    \sphinxsetup{key1=value1, key2=value2,...}
 
-.. versionadded:: 1.5
-
-.. hint::
-
-   It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro
-   directly into the body of the document, via the help of the :rst:dir:`raw`
-   directive.  Here is how this present chapter is styled in the PDF output::
+The colors used in the above are provided by the ``svgnames`` option of the
+"xcolor" package::
 
-     .. raw:: latex
-
-        \begingroup
-        \sphinxsetup{%
-              verbatimwithframe=false,
-              VerbatimColor={named}{OldLace},
-              TitleColor={named}{DarkGoldenrod},
-              hintBorderColor={named}{LightCoral},
-              attentionborder=3pt,
-              attentionBorderColor={named}{Crimson},
-              attentionBgColor={named}{FloralWhite},
-              noteborder=2pt,
-              noteBorderColor={named}{Olive},
-              cautionborder=3pt,
-              cautionBorderColor={named}{Cyan},
-              cautionBgColor={named}{LightCyan}}
-
-   at the start of the chapter and::
+   latex_elements = {
+       'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
+   }
 
-     .. raw:: latex
+It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro
+directly into the body of the document, via the help of the :rst:dir:`raw`
+directive. This chapter is styled in the PDF output using the following at the
+start of the chaper::
 
-        \endgroup
+  .. raw:: latex
 
-   at its end.
+     \begingroup
+     \sphinxsetup{%
+           verbatimwithframe=false,
+           VerbatimColor={named}{OldLace},
+           TitleColor={named}{DarkGoldenrod},
+           hintBorderColor={named}{LightCoral},
+           attentionborder=3pt,
+           attentionBorderColor={named}{Crimson},
+           attentionBgColor={named}{FloralWhite},
+           noteborder=2pt,
+           noteBorderColor={named}{Olive},
+           cautionborder=3pt,
+           cautionBorderColor={named}{Cyan},
+           cautionBgColor={named}{LightCyan}}
 
-   The colors used in the above are provided by the ``svgnames`` option of the
-   "xcolor" package::
+The below is included at the end of the chapter::
 
-      latex_elements = {
-          'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
-      }
+  .. raw:: latex
 
+     \endgroup
 
 LaTeX boolean keys require *lowercase* ``true`` or ``false`` values.
 Spaces around the commas and equal signs are ignored, spaces inside LaTeX
@@ -555,9 +587,8 @@ macros may be significant.
 
 ``hmargin, vmargin``
     The dimensions of the horizontal (resp. vertical) margins, passed as
-    ``hmargin`` (resp. ``vmargin``) option to
-    the ``geometry`` package. The default is ``1in``, which is equivalent to
-    ``{1in,1in}``. Example::
+    ``hmargin`` (resp. ``vmargin``) option to the ``geometry`` package.
+    Example::
 
       'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
 
@@ -567,6 +598,8 @@ macros may be significant.
     the text height set to an integer multiple of the baselineskip, with the
     closest fit for the margins.
 
+    Default: ``1in`` (equivalent to ``{1in,1in}``)
+
     .. hint::
 
        For Japanese ``'manual'`` docclass with pointsize ``11pt`` or ``12pt``,
@@ -579,55 +612,68 @@ macros may be significant.
     .. versionadded:: 1.5.3
 
 ``marginpar``
-    The ``\marginparwidth`` LaTeX dimension, defaults to ``0.5in``. For Japanese
-    documents, the value is modified to be the closest integer multiple of the
-    *zenkaku* width.
+    The ``\marginparwidth`` LaTeX dimension. For Japanese documents, the value
+    is modified to be the closest integer multiple of the *zenkaku* width.
+
+    Default: ``0.5in``
 
     .. versionadded:: 1.5.3
 
 ``verbatimwithframe``
-    default ``true``. Boolean to specify if :rst:dir:`code-block`\ s and literal
-    includes are framed. Setting it to ``false`` does not deactivate use of
-    package "framed", because it is still in use for the optional background
-    colour.
+    Boolean to specify if :rst:dir:`code-block`\ s and literal includes are
+    framed. Setting it to ``false`` does not deactivate use of package
+    "framed", because it is still in use for the optional background colour.
+
+    Default: ``true``.
 
 ``verbatimwrapslines``
-    default ``true``. Tells whether long lines in :rst:dir:`code-block`\ 's
-    contents should wrap.
+    Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents are
+    wrapped.
+
+    Default: ``true``
 
 ``literalblockcappos``
-    default ``t`` for "top". Decides the caption position. Alternative is
-    ``b`` ("bottom").
+    Decides the caption position: either ``b`` ("bottom") or ``t`` ("top").
+
+    Default: ``t``
 
     .. versionadded:: 1.7
 
 ``verbatimhintsturnover``
-    default ``true``. If ``true``, code-blocks display "continued on next
-    page", "continued from previous page" hints in case of pagebreaks.
+    Boolean to specify if code-blocks display "continued on next page" and
+    "continued from previous page" hints in case of pagebreaks.
+
+    Default: ``true``
 
     .. versionadded:: 1.6.3
     .. versionchanged:: 1.7
        the default changed from ``false`` to ``true``.
 
 ``verbatimcontinuedalign``, ``verbatimcontinuesalign``
-    default ``r``. Horizontal position relative to the framed contents:
-    either ``l`` (left aligned), ``r`` (right aligned) or ``c`` (centered).
+    Horizontal position relative to the framed contents: either ``l`` (left
+    aligned), ``r`` (right aligned) or ``c`` (centered).
+
+    Default: ``r``
 
     .. versionadded:: 1.7
 
 ``parsedliteralwraps``
-    default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's
-    contents should wrap.
+    Boolean to specify if long lines in :dudir:`parsed-literal`\ 's contents
+    should wrap.
+
+    Default: ``true``
 
     .. versionadded:: 1.5.2
        set this option value to ``false`` to recover former behaviour.
 
 ``inlineliteralwraps``
-    default ``true``. Allows linebreaks inside inline literals: but extra
-    potential break-points (additionally to those allowed by LaTeX at spaces
-    or for hyphenation) are currently inserted only after the characters
+    Boolean to specify if line breaks are allowed inside inline literals: but
+    extra potential break-points (additionally to those allowed by LaTeX at
+    spaces or for hyphenation) are currently inserted only after the characters
     ``. , ; ? ! /`` and ``\``. Due to TeX internals, white space in the line
-    will be stretched (or shrunk) in order to accomodate the linebreak.
+    will be stretched (or shrunk) in order to accommodate the linebreak.
+
+    Default: ``true``
 
     .. versionadded:: 1.5
        set this option value to ``false`` to recover former behaviour.
@@ -636,9 +682,10 @@ macros may be significant.
        added potential breakpoint at ``\`` characters.
 
 ``verbatimvisiblespace``
-    default ``\textcolor{red}{\textvisiblespace}``. When a long code line is
-    split, the last space character from the source code line right before the
-    linebreak location is typeset using this.
+    When a long code line is split, the last space character from the source
+    code line right before the linebreak location is typeset using this.
+
+    Default: ``\textcolor{red}{\textvisiblespace}``
 
 ``verbatimcontinued``
     A LaTeX macro inserted at start of continuation code lines. Its
@@ -652,8 +699,9 @@ macros may be significant.
        various font sizes (e.g. code-blocks can be in footnotes).
 
 ``TitleColor``
-    default ``{rgb}{0.126,0.263,0.361}``. The colour for titles (as configured
-    via use of package "titlesec".)
+    The colour for titles (as configured via use of package "titlesec".)
+
+    Default: ``{rgb}{0.126,0.263,0.361}``
 
 .. warning::
 
@@ -661,22 +709,31 @@ macros may be significant.
    argument of the ``color/xcolor`` packages ``\definecolor`` command.
 
 ``InnerLinkColor``
-    default ``{rgb}{0.208,0.374,0.486}``. A colour passed to ``hyperref`` as
-    value of ``linkcolor``  and ``citecolor``.
+    A colour passed to ``hyperref`` as value of ``linkcolor``  and
+    ``citecolor``.
+
+    Default: ``{rgb}{0.208,0.374,0.486}``.
 
 ``OuterLinkColor``
-    default ``{rgb}{0.216,0.439,0.388}``. A colour passed to ``hyperref`` as
-    value of ``filecolor``, ``menucolor``, and ``urlcolor``.
+    A colour passed to ``hyperref`` as value of ``filecolor``, ``menucolor``,
+    and ``urlcolor``.
+
+    Default: ``{rgb}{0.216,0.439,0.388}``
 
 ``VerbatimColor``
-    default ``{rgb}{1,1,1}``. The background colour for
-    :rst:dir:`code-block`\ s. The default is white.
+    The background colour for :rst:dir:`code-block`\ s.
+
+    Default: ``{rgb}{1,1,1}`` (white)
 
 ``VerbatimBorderColor``
-    default ``{rgb}{0,0,0}``. The frame color, defaults to black.
+    The frame color.
+
+    Default: ``{rgb}{0,0,0}`` (black)
 
 ``VerbatimHighlightColor``
-    default ``{rgb}{0.878,1,1}``. The color for highlighted lines.
+    The color for highlighted lines.
+
+    Default: ``{rgb}{0.878,1,1}``
 
     .. versionadded:: 1.6.6
 
@@ -686,54 +743,77 @@ macros may be significant.
    names declared to "color" or "xcolor" are prefixed with "sphinx".
 
 ``verbatimsep``
-    default ``\fboxsep``. The separation between code lines and the frame.
+    The separation between code lines and the frame.
+
+    Default: ``\fboxsep``
 
 ``verbatimborder``
-    default ``\fboxrule``. The width of the frame around
-    :rst:dir:`code-block`\ s.
+    The width of the frame around :rst:dir:`code-block`\ s.
+
+    Default: ``\fboxrule``
 
 ``shadowsep``
-    default ``5pt``. The separation between contents and frame for
-    :dudir:`contents` and :dudir:`topic` boxes.
+    The separation between contents and frame for :dudir:`contents` and
+    :dudir:`topic` boxes.
+
+    Default: ``5pt``
 
 ``shadowsize``
-    default ``4pt``. The width of the lateral "shadow" to the right.
+    The width of the lateral "shadow" to the right.
+
+    Default: ``4pt``
 
 ``shadowrule``
-    default ``\fboxrule``. The width of the frame around :dudir:`topic` boxes.
+    The width of the frame around :dudir:`topic` boxes.
+
+    Default: ``\fboxrule``
 
 |notebdcolors|
-    default ``{rgb}{0,0,0}`` (black). The colour for the two horizontal rules
-    used by Sphinx in LaTeX for styling a :dudir:`note` type admonition.
+    The colour for the two horizontal rules used by Sphinx in LaTeX for styling
+    a :dudir:`note` type admonition.
+
+    Default: ``{rgb}{0,0,0}`` (black)
 
 ``noteborder``, ``hintborder``, ``importantborder``, ``tipborder``
-    default ``0.5pt``. The width of the two horizontal rules.
+    The width of the two horizontal rules.
+
+    Default: ``0.5pt``
 
 .. only:: not latex
 
    |warningbdcolors|
-       default ``{rgb}{0,0,0}`` (black). The colour for the admonition frame.
+       The colour for the admonition frame.
+
+       Default: ``{rgb}{0,0,0}`` (black)
 
 .. only:: latex
 
    |wgbdcolorslatex|
-       default ``{rgb}{0,0,0}`` (black). The colour for the admonition frame.
+       The colour for the admonition frame.
+
+       Default: ``{rgb}{0,0,0}`` (black)
 
 |warningbgcolors|
-    default ``{rgb}{1,1,1}`` (white). The background colours for the respective
-    admonitions.
+    The background colours for the respective admonitions.
+
+    Default: ``{rgb}{1,1,1}`` (white)
 
 |warningborders|
-    default ``1pt``. The width of the frame.
+    The width of the frame.
+
+    Default: ``1pt``
 
 ``AtStartFootnote``
-    default ``\mbox{ }``. LaTeX macros inserted at the start of the footnote
-    text at bottom of page, after the footnote number.
+    LaTeX macros inserted at the start of the footnote text at bottom of page,
+    after the footnote number.
+
+    Default: ``\mbox{ }``
 
 ``BeforeFootnote``
-    default ``\leavevmode\unskip``. LaTeX macros inserted before the footnote
-    mark. The default removes possible space before it (else, TeX could insert
-    a linebreak there).
+    LaTeX macros inserted before the footnote mark. The default removes
+    possible space before it (else, TeX could insert a line break there).
+
+    Default: ``\leavevmode\unskip``
 
     .. versionadded:: 1.5
 
@@ -762,6 +842,7 @@ macros may be significant.
                               ``attentionborder``, ``dangerborder``,
                               ``errorborder``
 
+
 LaTeX macros and environments
 -----------------------------
 
@@ -774,7 +855,7 @@ thus allowing redefinitions. Check the respective files for the defaults.
 Macros
 ~~~~~~
 
-- text styling commands:
+- Text styling commands:
 
   - ``\sphinxstrong``,
   - ``\sphinxbfcode``,
@@ -786,11 +867,12 @@ Macros
   - ``\sphinxcrossref``,
   - ``\sphinxtermref``,
   - ``\sphinxoptional``.
- 
+
   .. versionadded:: 1.4.5
      Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
      with LaTeX packages.
-- more text styling:
+
+- More text styling:
 
   - ``\sphinxstyleindexentry``,
   - ``\sphinxstyleindexextra``,
@@ -808,58 +890,66 @@ Macros
   - ``\sphinxstyleliteralintitle``,
   - ``\sphinxstylecodecontinued``,
   - ``\sphinxstylecodecontinues``.
- 
+
   .. versionadded:: 1.5
-     these macros were formerly hard-coded as non customizable ``\texttt``,
+     These macros were formerly hard-coded as non customizable ``\texttt``,
      ``\emph``, etc...
+
   .. versionadded:: 1.6
      ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows
      multiple paragraphs in header cells of tables.
+
   .. versionadded:: 1.6.3
      ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``.
+
   .. versionadded:: 3.0
      ``\sphinxkeyboard``
-- ``\sphinxtableofcontents``: it is a
-  wrapper (defined differently in :file:`sphinxhowto.cls` and in
-  :file:`sphinxmanual.cls`) of standard ``\tableofcontents``.  The macro
-  ``\sphinxtableofcontentshook`` is executed during its expansion right before
-  ``\tableofcontents`` itself.
+
+- ``\sphinxtableofcontents``: A wrapper (defined differently in
+  :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard
+  ``\tableofcontents``.  The macro ``\sphinxtableofcontentshook`` is executed
+  during its expansion right before ``\tableofcontents`` itself.
 
   .. versionchanged:: 1.5
-     formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
+     Formerly, the meaning of ``\tableofcontents`` was modified by Sphinx.
+
   .. versionchanged:: 2.0
-     hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly
+     Hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly
      done during loading of ``'manual'`` docclass are now executed later via
      ``\sphinxtableofcontentshook``.  This macro is also executed by the
      ``'howto'`` docclass, but defaults to empty with it.
-- ``\sphinxmaketitle``: it is defined in the class files
-  :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls` and is used as
-  default setting of ``'maketitle'`` :confval:`latex_elements` key.
+
+- ``\sphinxmaketitle``: Used as the default setting of the ``'maketitle'``
+  :confval:`latex_elements` key.
+  Defined in the class files :file:`sphinxmanual.cls` and
+  :file:`sphinxhowto.cls`.
 
   .. versionchanged:: 1.8.3
-     formerly, ``\maketitle`` from LaTeX document class was modified by
+     Formerly, ``\maketitle`` from LaTeX document class was modified by
      Sphinx.
-- ``\sphinxbackoftitlepage``: for ``'manual'`` docclass, and if it is
+
+- ``\sphinxbackoftitlepage``: For ``'manual'`` docclass, and if it is
   defined, it gets executed at end of ``\sphinxmaketitle``, before the final
   ``\clearpage``.  Use either the ``'maketitle'`` key or the ``'preamble'`` key
   of :confval:`latex_elements` to add a custom definition of
   ``\sphinxbackoftitlepage``.
 
   .. versionadded:: 1.8.3
-- ``\sphinxcite``: it is a wrapper of standard ``\cite`` for citation
-  references.
+
+- ``\sphinxcite``: A wrapper of standard ``\cite`` for citation references.
 
 Environments
 ~~~~~~~~~~~~
 
-- a :dudir:`figure` may have an optional legend with arbitrary body
+- A :dudir:`figure` may have an optional legend with arbitrary body
   elements: they are rendered in a ``sphinxlegend`` environment. The default
   definition issues ``\small``, and ends with ``\par``.
 
   .. versionadded:: 1.5.6
-     formerly, the ``\small`` was hardcoded in LaTeX writer and the ending
+     Formerly, the ``\small`` was hardcoded in LaTeX writer and the ending
      ``\par`` was lacking.
-- environments associated with admonitions:
+
+- Environments associated with admonitions:
 
   - ``sphinxnote``,
   - ``sphinxhint``,
@@ -880,17 +970,20 @@ Environments
   specific to each type, which can be set via ``'sphinxsetup'`` string.
 
   .. versionchanged:: 1.5
-     use of public environment names, separate customizability of the
+     Use of public environment names, separate customizability of the
      parameters, such as ``noteBorderColor``, ``noteborder``,
      ``warningBgColor``, ``warningBorderColor``, ``warningborder``, ...
-- the :dudir:`contents` directive (with ``:local:`` option) and the
+
+- The :dudir:`contents` directive (with ``:local:`` option) and the
   :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.
 
   .. versionadded:: 1.4.2
-     former code refactored into an environment allowing page breaks.
+     Former code refactored into an environment allowing page breaks.
+
   .. versionchanged:: 1.5
-     options ``shadowsep``, ``shadowsize``,  ``shadowrule``.
-- the literal blocks (via ``::`` or :rst:dir:`code-block`), are
+     Options ``shadowsep``, ``shadowsize``,  ``shadowrule``.
+
+- The literal blocks (via ``::`` or :rst:dir:`code-block`), are
   implemented using ``sphinxVerbatim`` environment which is a wrapper of
   ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling
   of the top caption and the wrapping of long lines, and a frame which allows
@@ -902,34 +995,39 @@ Environments
      ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (also
      under the name ``OriginalVerbatim``); ``sphinxVerbatimintable`` is used
      inside tables.
+
   .. versionadded:: 1.5
-     options ``verbatimwithframe``, ``verbatimwrapslines``,
+     Options ``verbatimwithframe``, ``verbatimwrapslines``,
      ``verbatimsep``, ``verbatimborder``.
+
   .. versionadded:: 1.6.6
-     support for ``:emphasize-lines:`` option
+     Support for ``:emphasize-lines:`` option
+
   .. versionadded:: 1.6.6
-     easier customizability of the formatting via exposed to user LaTeX macros
+     Easier customizability of the formatting via exposed to user LaTeX macros
      such as ``\sphinxVerbatimHighlightLine``.
-- the bibliography uses ``sphinxthebibliography`` and the Python Module index
+
+- The bibliography uses ``sphinxthebibliography`` and the Python Module index
   as well as the general index both use ``sphinxtheindex``; these environments
   are wrappers of the ``thebibliography`` and respectively ``theindex``
   environments as provided by the document class (or packages).
 
   .. versionchanged:: 1.5
-     formerly, the original environments were modified by Sphinx.
+     Formerly, the original environments were modified by Sphinx.
 
 Miscellany
 ~~~~~~~~~~
 
-- the section, subsection, ...  headings are set using  *titlesec*'s
+- The section, subsection, ... headings are set using  *titlesec*'s
   ``\titleformat`` command.
-- for the ``'manual'`` docclass, the chapter headings can be customized using
+
+- For the ``'manual'`` docclass, the chapter headings can be customized using
   *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. File
   :file:`sphinx.sty` has custom re-definitions in case of *fncychap*
   option ``Bjarne``.
 
   .. versionchanged:: 1.5
-     formerly, use of *fncychap* with other styles than ``Bjarne`` was
+     Formerly, use of *fncychap* with other styles than ``Bjarne`` was
      dysfunctional.
 
 .. hint::
@@ -938,9 +1036,6 @@ Miscellany
    LaTeX source if you have a file named ``_templates/latex.tex_t`` in your
    project.
 
-   .. versionadded:: 1.5
-      currently all template variables are unstable and undocumented.
-
    Additional files ``longtable.tex_t``, ``tabulary.tex_t`` and
    ``tabular.tex_t`` can be added to ``_templates/`` to configure some aspects
    of table rendering (such as the caption position).
diff --git a/doc/templating.rst b/doc/templating.rst
index 1f4bef9c8..0e3815c29 100644
--- a/doc/templating.rst
+++ b/doc/templating.rst
@@ -2,6 +2,7 @@
 
 .. _templating:
 
+==========
 Templating
 ==========
 
@@ -69,9 +70,10 @@ following contents::
 By prefixing the name of the overridden template with an exclamation mark,
 Sphinx will load the layout template from the underlying HTML theme.
 
-**Important**: If you override a block, call ``{{ super() }}`` somewhere to
-render the block's original content in the extended template -- unless you
-don't want that content to show up.
+.. important::
+   If you override a block, call ``{{ super() }}`` somewhere to render the
+   block's original content in the extended template -- unless you don't want
+   that content to show up.
 
 
 Working with the builtin templates
@@ -85,72 +87,68 @@ Blocks
 
 The following blocks exist in the ``layout.html`` template:
 
-`doctype`
+``doctype``
     The doctype of the output format.  By default this is XHTML 1.0 Transitional
     as this is the closest to what Sphinx and Docutils generate and it's a good
     idea not to change it unless you want to switch to HTML 5 or a different but
     compatible XHTML doctype.
 
-`linktags`
+``linktags``
     This block adds a couple of ``<link>`` tags to the head section of the
     template.
 
-`extrahead`
+``extrahead``
     This block is empty by default and can be used to add extra contents into
     the ``<head>`` tag of the generated HTML file.  This is the right place to
     add references to JavaScript or extra CSS files.
 
-`relbar1` / `relbar2`
+``relbar1``, ``relbar2``
     This block contains the *relation bar*, the list of related links (the
     parent documents on the left, and the links to index, modules etc. on the
-    right).  `relbar1` appears before the document, `relbar2` after the
+    right).  ``relbar1`` appears before the document, ``relbar2`` after the
     document.  By default, both blocks are filled; to show the relbar only
     before the document, you would override `relbar2` like this::
 
        {% block relbar2 %}{% endblock %}
 
-`rootrellink` / `relbaritems`
-    Inside the relbar there are three sections: The `rootrellink`, the links
-    from the documentation and the custom `relbaritems`.  The `rootrellink` is a
-    block that by default contains a list item pointing to the master document
-    by default, the `relbaritems` is an empty block.  If you override them to
-    add extra links into the bar make sure that they are list items and end with
-    the :data:`reldelim1`.
+``rootrellink``, ``relbaritems``
+    Inside the relbar there are three sections: The ``rootrellink``, the links
+    from the documentation and the custom ``relbaritems``.  The ``rootrellink``
+    is a block that by default contains a list item pointing to the master
+    document by default, the ``relbaritems`` is an empty block.  If you
+    override them to add extra links into the bar make sure that they are list
+    items and end with the :data:`reldelim1`.
 
-`document`
-    The contents of the document itself.  It contains the block "body" where the
-    individual content is put by subtemplates like ``page.html``.
+``document``
+    The contents of the document itself.  It contains the block "body" where
+    the individual content is put by subtemplates like ``page.html``.
 
     .. note::
         In order for the built-in JavaScript search to show a page preview on
         the results page, the document or body content should be wrapped in an
-        HTML element containing the ``role="main"`` attribute. For example:
-
-        .. sourcecode:: html+jinja
+        HTML element containing the ``role="main"`` attribute. For example::
 
             <div role="main">
               {% block document %}{% endblock %}
             </div>
 
-`sidebar1` / `sidebar2`
-    A possible location for a sidebar.  `sidebar1` appears before the document
-    and is empty by default, `sidebar2` after the document and contains the
+``sidebar1``, ``sidebar2``
+    A possible location for a sidebar.  ``sidebar1`` appears before the document
+    and is empty by default, ``sidebar2`` after the document and contains the
     default sidebar.  If you want to swap the sidebar location override this and
-    call the `sidebar` helper:
-
-    .. sourcecode:: html+jinja
+    call the ``sidebar`` helper::
 
         {% block sidebar1 %}{{ sidebar() }}{% endblock %}
         {% block sidebar2 %}{% endblock %}
 
-    (The `sidebar2` location for the sidebar is needed by the ``sphinxdoc.css``
+    (The ``sidebar2`` location for the sidebar is needed by the ``sphinxdoc.css``
     stylesheet, for example.)
 
-`sidebarlogo`
+``sidebarlogo``
     The logo location within the sidebar.  Override this if you want to place
     some content at the top of the sidebar.
 
-`footer`
+``footer``
     The block for the footer div.  If you want a custom footer or markup before
     or after it, override this one.
 
@@ -159,23 +157,23 @@ list of custom sidebars in the :confval:`html_sidebars` config value.  Their use
 is deprecated in favor of separate sidebar templates, which can be included via
 :confval:`html_sidebars`.
 
-`sidebartoc`
+``sidebartoc``
     The table of contents within the sidebar.
 
     .. deprecated:: 1.0
 
-`sidebarrel`
+``sidebarrel``
     The relation links (previous, next document) within the sidebar.
 
     .. deprecated:: 1.0
 
-`sidebarsourcelink`
+``sidebarsourcelink``
     The "Show source" link within the sidebar (normally only shown if this is
     enabled by :confval:`html_show_sourcelink`).
 
     .. deprecated:: 1.0
 
-`sidebarsearch`
+``sidebarsearch``
     The search box within the sidebar.  Override this if you want to place some
     content at the bottom of the sidebar.
 
@@ -392,7 +390,6 @@ are in HTML form), these variables are also available:
       <a href="{{ next.link|e }}">{{ next.title }}</a>
       {% endif %}
 
-
 .. data:: page_source_suffix
 
    The suffix of the file that was rendered. Since we support a list of
@@ -424,14 +421,19 @@ are in HTML form), these variables are also available:
    A callable yielding the global TOC tree containing the current page, rendered
    as HTML bullet lists.  Optional keyword arguments:
 
-   * ``collapse`` (``True`` by default): if true, all TOC entries that are not
-     ancestors of the current page are collapsed
+   ``collapse``
+     If true, all TOC entries that are not ancestors of the current page are
+     collapsed.
+     ``True`` by default.
 
-   * ``maxdepth`` (defaults to the max depth selected in the toctree directive):
-     the maximum depth of the tree; set it to ``-1`` to allow unlimited depth
+   ``maxdepth``
+     The maximum depth of the tree. Set it to ``-1`` to allow unlimited depth.
+     Defaults to the max depth selected in the toctree directive.
 
-   * ``titles_only`` (``False`` by default): if true, put only toplevel document
-     titles in the tree
+   ``titles_only``
+     If true, put only top-level document titles in the tree.
+     ``False`` by default.
 
-   * ``includehidden`` (``False`` by default): if true, the TOC tree will also
-     contain hidden entries.
+   ``includehidden``
+     If true, the ToC tree will also contain hidden entries.
+     ``False`` by default.
diff --git a/doc/usage/extensions/autodoc.rst b/doc/usage/extensions/autodoc.rst
index 36be7568b..ec1d6c9b5 100644
--- a/doc/usage/extensions/autodoc.rst
+++ b/doc/usage/extensions/autodoc.rst
@@ -454,7 +454,14 @@ There are also config values that you can set:
    looks like a signature, use the line as the signature and remove it from the
    docstring content.
 
+   If the signature line ends with backslash, autodoc considers the function has
+   multiple signatures and look at the next line of the docstring.  It is useful
+   for overloaded function.
+
    .. versionadded:: 1.1
+   .. versionchanged:: 3.1
+
+      Support overloaded signatures
 
 .. confval:: autodoc_mock_imports
 
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
new file mode 100644
index 000000000..49a4dccaa
--- /dev/null
+++ b/doc/usage/index.rst
@@ -0,0 +1,23 @@
+============
+Using Sphinx
+============
+
+This guide serves to demonstrate how one can get started with Sphinx and covers
+everything from installing Sphinx and configuring your first Sphinx project to
+using some of the advanced features Sphinx provides out-of-the-box. If you are
+looking for guidance on extending Sphinx, refer to :doc:`/development/index`.
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart
+   installation
+   restructuredtext/index
+   markdown
+   configuration
+   builders/index
+   extensions/index
+   theming
+   advanced/intl
+   advanced/setuptools
+   advanced/websupport/index
diff --git a/doc/usage/installation.rst b/doc/usage/installation.rst
index ba93bf192..c9bef974d 100644
--- a/doc/usage/installation.rst
+++ b/doc/usage/installation.rst
@@ -12,9 +12,13 @@ Installing Sphinx
 Overview
 --------
 
-Sphinx is written in `Python`__ and supports Python 3.5+.
+Sphinx is written in `Python`__ and supports Python 3.5+. It builds upon the
+shoulders of many third-party libraries such as `Docutils`__ and `Jinja`__,
+which are installed when Sphinx is installed.
 
 __ https://docs.python-guide.org/
+__ https://docutils.sourceforge.io/
+__ https://jinja.palletsprojects.com/
 
 
 Linux
diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst
index b5462a388..8d2de021e 100644
--- a/doc/usage/quickstart.rst
+++ b/doc/usage/quickstart.rst
@@ -2,21 +2,38 @@
 Getting Started
 ===============
 
-Once Sphinx is :doc:`installed </usage/installation>`, you can proceed with
-setting up your first Sphinx project. To ease the process of getting started,
-Sphinx provides a tool, :program:`sphinx-quickstart`, which will generate a
-documentation source directory and populate it with some defaults. We're going
-to use the :program:`sphinx-quickstart` tool here, though its use is by no means
-necessary.
+Sphinx is a *documentation generator* or a tool that translates a set of plain
+text source files into various output formats, automatically producing
+cross-references, indices, etc.  That is, if you have a directory containing a
+bunch of :doc:`/usage/restructuredtext/index` or :doc:`/usage/markdown`
+documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX),
+man pages and much more.
+
+Sphinx focuses on documentation, in particular handwritten documentation,
+however, Sphinx can also be used to generate blogs, homepages and even books.
+Much of Sphinx's power comes from the richness of its default plain-text markup
+format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with
+it's :doc:`significant extensibility capabilities </development/index>`.
+
+The goal of this document is to give you a quick taste of what Sphinx it is and
+how you might use it. When you're done here, you can check out the
+:doc:`installation guide </usage/installation>` followed by the intro to the
+default markup format used by Sphinx, :doc:`reStucturedText
+</usage/restructuredtext/index>`.
+
+For a great "introduction" to writing docs in general -- the whys and hows, see
+also `Write the docs`__, written by Eric Holscher.
+
+.. __: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/
 
 
 Setting up the documentation sources
 ------------------------------------
 
-The root directory of a Sphinx collection of :term:`reStructuredText` document
-sources is called the :term:`source directory`.  This directory also contains
-the Sphinx configuration file :file:`conf.py`, where you can configure all
-aspects of how Sphinx reads your sources and builds your documentation.  [#]_
+The root directory of a Sphinx collection of plain-text document sources is
+called the :term:`source directory`.  This directory also contains the Sphinx
+configuration file :file:`conf.py`, where you can configure all aspects of how
+Sphinx reads your sources and builds your documentation.  [#]_
 
 Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a
 source directory and creates a default :file:`conf.py` with the most useful
@@ -26,9 +43,6 @@ configuration values from a few questions it asks you. To use this, run:
 
    $ sphinx-quickstart
 
-There is also an automatic "API documentation" generator called
-:program:`sphinx-apidoc`; see :doc:`/man/sphinx-apidoc` for details.
-
 
 Defining document structure
 ---------------------------
diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst
index 0aae78718..792a4a53d 100644
--- a/doc/usage/theming.rst
+++ b/doc/usage/theming.rst
@@ -1,5 +1,7 @@
 .. highlight:: python
 
+.. _html-themes:
+
 HTML
 ====
 
diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py
index cf0480aad..e247d3bd2 100644
--- a/sphinx/ext/autodoc/__init__.py
+++ b/sphinx/ext/autodoc/__init__.py
@@ -1036,39 +1036,71 @@ class DocstringSignatureMixin:
     Mixin for FunctionDocumenter and MethodDocumenter to provide the
     feature of reading the signature from the docstring.
     """
+    _new_docstrings = None  # type: List[List[str]]
+    _signatures = None      # type: List[str]
 
     def _find_signature(self, encoding: str = None) -> Tuple[str, str]:
         if encoding is not None:
             warnings.warn("The 'encoding' argument to autodoc.%s._find_signature() is "
                           "deprecated." % self.__class__.__name__,
                           RemovedInSphinx40Warning, stacklevel=2)
+
+        # candidates of the object name
+        valid_names = [self.objpath[-1]]  # type: ignore
+        if isinstance(self, ClassDocumenter):
+            valid_names.append('__init__')
+            if hasattr(self.object, '__mro__'):
+                valid_names.extend(cls.__name__ for cls in self.object.__mro__)
+
         docstrings = self.get_doc()
         self._new_docstrings = docstrings[:]
+        self._signatures = []
         result = None
         for i, doclines in enumerate(docstrings):
-            # no lines in docstring, no match
-            if not doclines:
-                continue
-            # match first line of docstring against signature RE
-            match = py_ext_sig_re.match(doclines[0])
-            if not match:
-                continue
-            exmod, path, base, args, retann = match.groups()
-            # the base name must match ours
-            valid_names = [self.objpath[-1]]  # type: ignore
-            if isinstance(self, ClassDocumenter):
-                valid_names.append('__init__')
-                if hasattr(self.object, '__mro__'):
-                    valid_names.extend(cls.__name__ for cls in self.object.__mro__)
-            if base not in valid_names:
-                continue
-            # re-prepare docstring to ignore more leading indentation
-            tab_width = self.directive.state.document.settings.tab_width  # type: ignore
-            self._new_docstrings[i] = prepare_docstring('\n'.join(doclines[1:]),
-                                                        tabsize=tab_width)
-            result = args, retann
-            # don't look any further
-            break
+            for j, line in enumerate(doclines):
+                if not line:
+                    # no lines in docstring, no match
+                    break
+
+                if line.endswith('\\'):
+                    multiline = True
+                    line = line.rstrip('\\').rstrip()
+                else:
+                    multiline = False
+
+                # match first line of docstring against signature RE
+                match = py_ext_sig_re.match(line)
+                if not match:
+                    continue
+                exmod, path, base, args, retann = match.groups()
+
+                # the base name must match ours
+                if base not in valid_names:
+                    continue
+
+                # re-prepare docstring to ignore more leading indentation
+                tab_width = self.directive.state.document.settings.tab_width  # type: ignore
+                self._new_docstrings[i] = prepare_docstring('\n'.join(doclines[j + 1:]),
+                                                            tabsize=tab_width)
+
+                if result is None:
+                    # first signature
+                    result = args, retann
+                else:
+                    # subsequent signatures
+                    self._signatures.append("(%s) -> %s" % (args, retann))
+
+                if multiline:
+                    # the signature have multiple signatures on docstring
+                    continue
+                else:
+                    # don't look any further
+                    break
+
+            if result:
+                # finish the loop when signature found
+                break
+
         return result
 
     def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
@@ -1076,9 +1108,8 @@ class DocstringSignatureMixin:
             warnings.warn("The 'encoding' argument to autodoc.%s.get_doc() is deprecated."
                           % self.__class__.__name__,
                           RemovedInSphinx40Warning, stacklevel=2)
-        lines = getattr(self, '_new_docstrings', None)
-        if lines is not None:
-            return lines
+        if self._new_docstrings is not None:
+            return self._new_docstrings
         return super().get_doc(None, ignore)  # type: ignore
 
     def format_signature(self, **kwargs: Any) -> str:
@@ -1088,7 +1119,11 @@ class DocstringSignatureMixin:
             result = self._find_signature()
             if result is not None:
                 self.args, self.retann = result
-        return super().format_signature(**kwargs)  # type: ignore
+        sig = super().format_signature(**kwargs)  # type: ignore
+        if self._signatures:
+            return "\n".join([sig] + self._signatures)
+        else:
+            return sig
 
 
 class DocstringStripSignatureMixin(DocstringSignatureMixin):
@@ -1170,6 +1205,7 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
 
                     documenter = FunctionDocumenter(self.directive, '')
                     documenter.object = func
+                    documenter.objpath = [None]
                     sigs.append(documenter.format_signature())
 
         return "\n".join(sigs)
diff --git a/tests/roots/test-ext-autodoc/target/docstring_signature.py b/tests/roots/test-ext-autodoc/target/docstring_signature.py
index 2e5499770..244109629 100644
--- a/tests/roots/test-ext-autodoc/target/docstring_signature.py
+++ b/tests/roots/test-ext-autodoc/target/docstring_signature.py
@@ -17,3 +17,9 @@ class C:
 class D:
     def __init__(self):
         """D(foo, bar, baz)"""
+
+
+class E:
+    def __init__(self):
+        """E(foo: int, bar: int, baz: int) -> None \\
+        E(foo: str, bar: str, baz: str) -> None"""
diff --git a/tests/test_ext_autodoc_configs.py b/tests/test_ext_autodoc_configs.py
index 22558885b..674620df0 100644
--- a/tests/test_ext_autodoc_configs.py
+++ b/tests/test_ext_autodoc_configs.py
@@ -346,6 +346,10 @@ def test_autoclass_content_and_docstring_signature_class(app):
         '',
         '.. py:class:: D()',
         '   :module: target.docstring_signature',
+        '',
+        '',
+        '.. py:class:: E()',
+        '   :module: target.docstring_signature',
         ''
     ]
 
@@ -375,6 +379,11 @@ def test_autoclass_content_and_docstring_signature_init(app):
         '',
         '.. py:class:: D(foo, bar, baz)',
         '   :module: target.docstring_signature',
+        '',
+        '',
+        '.. py:class:: E(foo: int, bar: int, baz: int) -> None',
+        '              E(foo: str, bar: str, baz: str) -> None',
+        '   :module: target.docstring_signature',
         ''
     ]
 
@@ -409,6 +418,11 @@ def test_autoclass_content_and_docstring_signature_both(app):
         '.. py:class:: D(foo, bar, baz)',
         '   :module: target.docstring_signature',
         '',
+        '',
+        '.. py:class:: E(foo: int, bar: int, baz: int) -> None',
+        '              E(foo: str, bar: str, baz: str) -> None',
+        '   :module: target.docstring_signature',
+        '',
     ]