Merge pull request #7752 from stephenfin/doc/latex-rework

[doc] Rework "latex" document

2 files changed, 623 insertions, 526 deletions

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/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
 ====