Adding upstream version 7.2.6.upstream/7.2.6

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1841 insertions, 0 deletions

diff --git a/doc/latex.rst b/doc/latex.rst
new file mode 100644
index 0000000..4c9a4e0
--- /dev/null
+++ b/doc/latex.rst
@@ -0,0 +1,1841 @@
+LaTeX customization
+===================
+
+.. module:: latex
+   :synopsis: LaTeX specifics.
+
+.. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
+
+.. raw:: latex
+
+   \begingroup
+   \sphinxsetup{%
+         TitleColor={named}{DarkGoldenrod},
+         pre_border-width=2pt,
+         pre_border-right-width=8pt,
+         pre_padding=5pt,
+         pre_border-radius=5pt,
+         pre_background-TeXcolor={named}{OldLace},
+         pre_border-TeXcolor=Gold!90,
+         pre_box-shadow=6pt 6pt,
+         pre_box-shadow-TeXcolor=gray!20,
+         %
+         div.warning_border-width=3pt,
+         div.warning_padding=6pt,
+         div.warning_padding-right=18pt,
+         div.warning_padding-bottom=18pt,
+         div.warning_border-TeXcolor=DarkCyan,
+         div.warning_background-TeXcolor=LightCyan,
+         div.warning_box-shadow=-12pt -12pt inset,
+         div.warning_box-shadow-TeXcolor=Cyan,
+         %
+         attentionborder=3pt,
+         attentionBorderColor=Crimson,
+         attentionBgColor=FloralWhite,
+         %
+         noteborder=1pt,
+         noteBorderColor=Olive,
+         noteBgColor=Olive!10,
+         div.note_border-top-width=0pt,
+         div.note_border-bottom-width=0pt,
+         hintBorderColor=LightCoral,
+   }
+   \relax
+
+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:
+
+.. code-block:: latex
+
+   # inside conf.py
+   latex_engine = 'xelatex'
+   latex_elements = {
+       'fontpkg': r'''
+   \setmainfont{DejaVu Serif}
+   \setsansfont{DejaVu Sans}
+   \setmonofont{DejaVu Sans Mono}
+   ''',
+       'preamble': r'''
+   \usepackage[titles]{tocloft}
+   \cftsetpnumwidth {1.25cm}\cftsetrmarg{1.5cm}
+   \setlength{\cftchapnumwidth}{0.75cm}
+   \setlength{\cftsecindent}{\cftchapnumwidth}
+   \setlength{\cftsecnumwidth}{1.25cm}
+   ''',
+       'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
+       'printindex': r'\footnotesize\raggedright\printindex',
+   }
+   latex_show_urls = 'footnote'
+
+.. 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
+--------------------------------------------
+
+A dictionary that contains LaTeX snippets overriding those Sphinx usually puts
+into the generated ``.tex`` files.  Its ``'sphinxsetup'`` key is described
+:ref:`separately <latexsphinxsetup>`.  It allows also local configurations
+inserted in generated files, via :dudir:`raw` directives.  For example, in
+the PDF documentation this chapter is styled especially, as will be described
+later.
+
+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.
+
+   .. hint::
+
+      It may be also used for loading LaTeX packages very early in the
+      preamble.  For example package ``fancybox`` is incompatible with
+      being loaded via the ``'preamble'`` key, it must be loaded earlier.
+
+   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 modifying 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 is::
+
+      r"""\usepackage{tgtermes}
+      \usepackage{tgheros}
+      \renewcommand\ttdefault{txtt}
+      """
+
+   For ``'xelatex'`` and ``'lualatex'`` however the default is to use
+   the GNU FreeFont.
+
+   .. versionchanged:: 1.2
+      Defaults to ``''`` when the :confval:`language` uses the Cyrillic
+      script.
+
+   .. versionchanged:: 2.0
+      Incorporates some font substitution commands to help support occasional
+      Greek or Cyrillic in a document using ``'pdflatex'`` engine.
+
+   .. versionchanged:: 4.0.0
+
+      - The font substitution commands added at ``2.0`` have been moved
+        to the ``'fontsubstitution'`` key, as their presence here made
+        it complicated for user to customize the value of ``'fontpkg'``.
+      - The default font setting has changed: it still uses Times and
+        Helvetica clones for serif and sans serif, but via better, more
+        complete TeX fonts and associated LaTeX packages.  The
+        monospace font has been changed to better match the Times clone.
+
+``'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"]
+
+   Do not use ``.tex`` as suffix, else the file is submitted itself to the PDF
+   build process, use ``.tex.txt`` or ``.sty`` as in the examples above.
+
+   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:: latex
+
+       latex_elements = {
+           'extrapackages': 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
+   ``''``.
+
+   .. note::
+
+      If using ``utf8x`` in place of ``utf8`` it is mandatory to extend the
+      LaTeX preamble with suitable ``\PreloadUnicodePage{<number>}`` commands,
+      as per the ``utf8x`` documentation (``texdoc ucs`` on a TeXLive based
+      TeX installation).  Else, unexpected and possibly hard-to-spot problems
+      (i.e. not causing a build crash) may arise in the PDF, in particular
+      regarding hyperlinks.
+
+      Even if these precautions are taken, PDF build via ``pdflatex`` engine
+      may crash due to upstream LaTeX not being fully compatible with
+      ``utf8x``.  For example, in certain circumstances related to
+      code-blocks, or attempting to include images whose filenames contain
+      Unicode characters.  Indeed, starting in 2015, upstream LaTeX with
+      ``pdflatex`` engine has somewhat enhanced native support for Unicode and
+      is becoming more and more incompatible with ``utf8x``.  In particular,
+      since the October 2019 LaTeX release, filenames can use Unicode
+      characters, and even spaces.  At Sphinx level this means e.g. that the
+      :dudir:`image` and :dudir:`figure` directives are now compatible with
+      such filenames for PDF via LaTeX output.  But this is broken if
+      ``utf8x`` is in use.
+
+   .. versionchanged:: 1.4.3
+      Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all
+      compilers.
+
+``'cmappkg'``
+   "cmap" package inclusion.
+
+   Default: ``'\\usepackage{cmap}'``
+
+   .. versionadded:: 1.2
+
+``'fontenc'``
+   Customize this from its default ``'\\usepackage[T1]{fontenc}'`` to:
+
+   - ``'\\usepackage[X2,T1]{fontenc}'`` if you need occasional
+     Cyrillic letters (физика частиц),
+
+   - ``'\\usepackage[LGR,T1]{fontenc}'`` if you need occasional
+     Greek letters (Σωματιδιακή φυσική).
+
+   Use ``[LGR,X2,T1]`` rather if both are needed.
+
+   .. attention::
+
+      - Do not use this key for a :confval:`latex_engine` other than
+        ``'pdflatex'``.
+
+      - If Greek is main language, do not use this key.  Since Sphinx 2.2.1,
+        ``xelatex`` will be used automatically as :confval:`latex_engine`.
+
+      - The TeX installation may need some extra packages. For example,
+        on Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super``
+        are needed for ``LGR`` to work. And ``texlive-lang-cyrillic`` and
+        ``cm-super`` are needed for support of Cyrillic.
+
+   .. 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 letters (``'pdflatex'``).
+
+   .. versionchanged:: 2.3.0
+      ``'xelatex'`` 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``.
+
+``'fontsubstitution'``
+   Ignored if ``'fontenc'`` was not configured to use ``LGR`` or ``X2`` (or
+   ``T2A``).  In case ``'fontpkg'`` key is configured for usage with some
+   TeX fonts known to be available in the ``LGR`` or ``X2`` encodings, set
+   this one to be the empty string.  Else leave to its default.
+
+   Ignored with :confval:`latex_engine` other than ``'pdflatex'``.
+
+   .. versionadded:: 4.0.0
+
+``'textgreek'``
+   For the support of occasional Greek letters.
+
+   It is ignored with ``'platex'``, ``'xelatex'`` or ``'lualatex'`` as
+   :confval:`latex_engine` and defaults to either the empty string or
+   to ``'\\usepackage{textalpha}'`` for ``'pdflatex'`` depending on
+   whether the ``'fontenc'`` key was used with ``LGR`` or not.  Only
+   expert LaTeX users may want to customize this key.
+
+   It can also be used as ``r'\usepackage{textalpha,alphabeta}'`` to let
+   ``'pdflatex'`` support Greek Unicode input in :rst:dir:`math` context.
+   For example ``:math:`α``` (U+03B1) will render as :math:`\alpha`.
+
+   Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not
+   include the ``LGR`` option.
+
+   .. versionadded:: 2.0
+
+``'geometry'``
+   "geometry" package inclusion, the default definition is:
+
+   .. code:: latex
+
+      '\\usepackage{geometry}'
+
+   with an additional ``[dvipdfm]`` for Japanese documents.
+   The Sphinx LaTeX style file executes:
+
+   .. code:: latex
+
+      \PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}
+
+   which can be customized via corresponding :ref:`'sphinxsetup' options
+   <latexsphinxsetup>`.
+
+   Default: ``'\\usepackage{geometry}'`` (or
+   ``'\\usepackage[dvipdfm]{geometry}'`` for Japanese documents)
+
+   .. 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.
+
+   Default: ``'\n\n\\bigskip\\hrule\\bigskip\n\n'``
+
+   .. versionadded:: 1.2
+
+   .. versionchanged:: 1.6
+      Remove unneeded ``{}`` after ``\\hrule``.
+
+``'makeindex'``
+   "makeindex" call, the last thing before ``\begin{document}``. With
+   ``'\\usepackage[columns=1]{idxlayout}\\makeindex'`` the index will use
+   only one column. You may have to install ``idxlayout`` LaTeX package.
+
+   Default: ``'\\makeindex'``
+
+``'printindex'``
+   "printindex" call, the last thing in the file. Override if you want to
+   generate the index differently, append some content after the index, or
+   change the font. As LaTeX uses two-column mode for the index it is
+   often advisable to set this key to
+   ``'\\footnotesize\\raggedright\\printindex'``. Or, to obtain a one-column
+   index, use ``'\\def\\twocolumn[#1]{#1}\\printindex'`` (this trick may fail
+   if using a custom document class; then try the ``idxlayout`` approach
+   described in the documentation of the ``'makeindex'`` key).
+
+   Default: ``'\\printindex'``
+
+``'fvset'``
+   Customization of ``fancyvrb`` LaTeX package.
+
+   The default value is ``'\\fvset{fontsize=auto}'`` which means that the
+   font size will adjust correctly if a code-block ends up in a footnote.
+   You may need to modify this if you use custom fonts:
+   ``'\\fvset{fontsize=\\small}'`` if the monospace font is Courier-like.
+
+   Default: ``'\\fvset{fontsize=auto}'``
+
+   .. versionadded:: 1.8
+
+   .. versionchanged:: 2.0
+      For ``'xelatex'`` and ``'lualatex'`` defaults to
+      ``'\\fvset{fontsize=\\small}'`` as this
+      is adapted to the relative widths of the FreeFont family.
+
+   .. versionchanged:: 4.0.0
+      Changed default for ``'pdflatex'``. Previously it was using
+      ``'\\fvset{fontsize=\\small}'``.
+
+   .. versionchanged:: 4.1.0
+      Changed default for Chinese documents to
+      ``'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'``
+
+Keys that are set by other options and therefore should not be overridden are:
+
+``'docclass'``
+``'classoptions'``
+``'title'``
+``'release'``
+``'author'``
+
+
+.. _latexsphinxsetup:
+
+The ``sphinxsetup`` configuration setting
+-----------------------------------------
+
+.. versionadded:: 1.5
+
+The ``'sphinxsetup'`` key of :ref:`latex_elements <latex_elements_confval>`
+provides a LaTeX-type customization interface::
+
+   latex_elements = {
+       'sphinxsetup': 'key1=value1, key2=value2, ...',
+   }
+
+It defaults to empty.  If non-empty, it will be passed as argument to the
+``\sphinxsetup`` macro inside the document preamble, like this::
+
+   \usepackage{sphinx}
+   \sphinxsetup{key1=value1, key2=value2,...}
+
+The colors used in the above are provided by the ``svgnames`` option of the
+"xcolor" package::
+
+   latex_elements = {
+       'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
+   }
+
+It is possible to insert uses of the ``\sphinxsetup`` LaTeX macro directly
+into the body of the document, via the ``raw`` directive.  This chapter is
+styled in the PDF output using the following insertion at its start.  This
+uses keys described later in :ref:`additionalcss`.
+
+.. code-block:: latex
+
+   .. raw:: latex
+
+      \begingroup
+      \sphinxsetup{%
+         TitleColor={named}{DarkGoldenrod},
+         % pre_border-width is 5.1.0 alias for verbatimborder
+         pre_border-width=2pt,
+         pre_border-right-width=8pt,
+         % pre_padding is a 5.1.0 alias for verbatimsep
+         pre_padding=5pt,
+         % Rounded boxes are new at 5.1.0
+         pre_border-radius=5pt,
+         % TeXcolor reminds that syntax must be as for LaTeX \definecolor
+         pre_background-TeXcolor={named}{OldLace},
+         % ... and since 5.3.0 also xcolor \colorlet syntax is accepted and we
+         %     can thus drop the {named}{...} thing if xcolor is available!
+         pre_border-TeXcolor=Gold,
+         % ... and even take more advantage of xcolor syntax:
+         pre_border-TeXcolor=Gold!90,
+         % add a shadow to code-blocks
+         pre_box-shadow=6pt 6pt,
+         pre_box-shadow-TeXcolor=gray!20,
+         %
+         % This 5.1.0 CSS-named option is alias for warningborder
+         div.warning_border-width=3pt,
+         % Prior to 5.1.0, padding for admonitions was not customizable
+         div.warning_padding=6pt,
+         div.warning_padding-right=18pt,
+         div.warning_padding-bottom=18pt,
+         % Assume xcolor has been loaded with its svgnames option
+         div.warning_border-TeXcolor=DarkCyan,
+         div.warning_background-TeXcolor=LightCyan,
+         % This one is the only option with space separated input:
+         div.warning_box-shadow=-12pt -12pt inset,
+         div.warning_box-shadow-TeXcolor=Cyan,
+         %
+         % The 5.1.0 new name would be div.attention_border-width
+         attentionborder=3pt,
+         % The 5.1.0 name here would be div.attention_border-TeXcolor
+         attentionBorderColor=Crimson,
+         % The 5.1.0 name would be div.attention_background-TeXcolor
+         attentionBgColor=FloralWhite,
+         %
+         % For note/hint/important/tip, the CSS syntax was added at 6.2.0
+         % Legacy syntax still works
+         noteborder=1pt,
+         noteBorderColor=Olive,
+         % But setting a background color via the new noteBgColor means that
+         % it will be rendered using the same interface as warning type
+         noteBgColor=Olive!10,
+         % We can customize separately the four border-widths, and mimic
+         % the legacy "light" rendering, but now with a background color:
+         % div.note_border-left-width=0pt,
+         % div.note_border-right-width=0pt,
+         % Let's rather for variety use lateral borders:
+         div.note_border-top-width=0pt,
+         div.note_border-bottom-width=0pt,
+         %
+         % As long as only border width and border color are set, *and* using
+         % for this the old interface, the rendering will be the "light" one
+         hintBorderColor=LightCoral,
+         % but if we had used div.hint_border-TeXcolor or *any* CSS-named
+         % option we would have triggered the more complex "heavybox" code.
+      }
+
+
+And this is placed at the end of the chapter source to end the scope of
+the configuration:
+
+.. code-block:: latex
+
+   .. raw:: latex
+
+      \endgroup
+
+LaTeX syntax for boolean keys requires *lowercase* ``true`` or ``false``
+e.g ``'sphinxsetup': "verbatimwrapslines=false"``.  If setting the
+boolean key to ``true``, ``=true`` is optional.
+Spaces around the commas and equal signs are ignored, spaces inside LaTeX
+macros may be significant.
+Do not use quotes to enclose values, whether numerical or strings.
+
+``bookmarksdepth``
+    Controls the depth of the collapsible bookmarks panel in the PDF.
+    May be either a number (e.g. ``3``) or a LaTeX sectioning name (e.g.
+    ``subsubsection``, i.e. without backslash).
+    For details, refer to the ``hyperref`` LaTeX docs.
+
+    Default: ``5``
+
+    .. versionadded:: 4.0.0
+
+.. _latexsphinxsetuphmargin:
+
+``hmargin, vmargin``
+    The dimensions of the horizontal (resp. vertical) margins, passed as
+    ``hmargin`` (resp. ``vmargin``) option to the ``geometry`` package.
+    Example::
+
+      'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
+
+    Japanese documents currently accept only the one-dimension format for
+    these parameters. The ``geometry`` package is then passed suitable options
+    to get the text width set to an exact multiple of the *zenkaku* width, and
+    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``,
+       use the ``nomag`` extra document class option (cf.
+       ``'extraclassoptions'`` key of :confval:`latex_elements`) or so-called
+       TeX "true" units::
+
+         'sphinxsetup': 'hmargin=1.5truein, vmargin=1.5truein, marginpar=5zw',
+
+    .. versionadded:: 1.5.3
+
+``marginpar``
+    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``
+    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 color.
+
+    Default: ``true``.
+
+``verbatimwrapslines``
+    Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents are
+    wrapped.
+
+    If ``true``, line breaks may happen at spaces (the last space before the
+    line break will be rendered using a special symbol), and at ascii
+    punctuation characters (i.e. not at letters or digits). Whenever a long
+    string has no break points, it is moved to next line. If its length is
+    longer than the line width it will overflow.
+
+    Default: ``true``
+
+.. _latexsphinxsetupforcewraps:
+
+``verbatimforcewraps``
+    Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents
+    should be forcefully wrapped to never overflow due to long strings.
+
+    .. note::
+
+       It is assumed that the Pygments_ LaTeXFormatter has not been used with
+       its ``texcomments`` or similar options which allow additional
+       (arbitrary) LaTeX mark-up.
+
+       Also, in case of :confval:`latex_engine` set to ``'pdflatex'``, only
+       the default LaTeX handling of Unicode code points, i.e. ``utf8`` not
+       ``utf8x`` is allowed.
+
+    .. _Pygments: https://pygments.org/
+
+    Default: ``false``
+
+    .. versionadded:: 3.5.0
+
+``verbatimmaxoverfull``
+    A number. If an unbreakable long string has length larger than the total
+    linewidth plus this number of characters, and if ``verbatimforcewraps``
+    mode is on, the input line will be reset using the forceful algorithm
+    which applies breakpoints at each character.
+
+    Default: ``3``
+
+    .. versionadded:: 3.5.0
+
+``verbatimmaxunderfull``
+    A number. If ``verbatimforcewraps`` mode applies, and if after applying
+    the line wrapping at spaces and punctuation, the first part of the split
+    line is lacking at least that number of characters to fill the available
+    width, then the input line will be reset using the forceful algorithm.
+
+    As the default is set to a high value, the forceful algorithm is triggered
+    only in overfull case, i.e. in presence of a string longer than full
+    linewidth. Set this to ``0`` to force all input lines to be hard wrapped
+    at the current available linewidth::
+
+      latex_elements = {
+          'sphinxsetup': "verbatimforcewraps, verbatimmaxunderfull=0",
+      }
+
+    This can be done locally for a given code-block via the use of raw latex
+    directives to insert suitable ``\sphinxsetup`` (before and after) into the
+    latex file.
+
+    Default: ``100``
+
+    .. versionadded:: 3.5.0
+
+``verbatimhintsturnover``
+    Boolean to specify if code-blocks display "continued on next page" and
+    "continued from previous page" hints in case of page breaks.
+
+    Default: ``true``
+
+    .. versionadded:: 1.6.3
+    .. versionchanged:: 1.7
+       the default changed from ``false`` to ``true``.
+
+``verbatimcontinuedalign``, ``verbatimcontinuesalign``
+    Horizontal position relative to the framed contents: either ``l`` (left
+    aligned), ``r`` (right aligned) or ``c`` (centered).
+
+    Default: ``r``
+
+    .. versionadded:: 1.7
+
+``parsedliteralwraps``
+    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 behavior.
+
+``inlineliteralwraps``
+    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 accommodate the linebreak.
+
+    Default: ``true``
+
+    .. versionadded:: 1.5
+       set this option value to ``false`` to recover former behavior.
+
+    .. versionchanged:: 2.3.0
+       added potential breakpoint at ``\`` characters.
+
+``verbatimvisiblespace``
+    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
+    (complicated...) default typesets a small red hook pointing to the right::
+
+      \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}}
+
+    .. versionchanged:: 1.5
+       The breaking of long code lines was added at 1.4.2. The default
+       definition of the continuation symbol was changed at 1.5 to accommodate
+       various font sizes (e.g. code-blocks can be in footnotes).
+
+.. note::
+
+   Values for color keys must either:
+
+   - obey the syntax of the ``\definecolor`` LaTeX command, e.g. something
+     such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or
+     ``{gray}{0.75}`` or (only with package ``xcolor``) ``{HTML}{808080}`` or
+     ...
+
+   - or obey the syntax of the ``\colorlet`` command from package ``xcolor``
+     (which then must exist in the LaTeX installation),
+     e.g. ``VerbatimColor=red!10`` or ``red!50!green`` or ``-red!75`` or
+     ``MyPreviouslyDefinedColor`` or... Refer to xcolor_ documentation for
+     this syntax.
+
+   .. _xcolor: https://ctan.org/pkg/xcolor
+
+   .. versionchanged:: 5.3.0
+      Formerly only the ``\definecolor`` syntax was accepted.
+
+``TitleColor``
+    The color for titles (as configured via use of package "titlesec".)
+
+    Default: ``{rgb}{0.126,0.263,0.361}``
+
+``InnerLinkColor``
+    A color passed to ``hyperref`` as value of ``linkcolor``  and
+    ``citecolor``.
+
+    Default: ``{rgb}{0.208,0.374,0.486}``.
+
+``OuterLinkColor``
+    A color passed to ``hyperref`` as value of ``filecolor``, ``menucolor``,
+    and ``urlcolor``.
+
+    Default: ``{rgb}{0.216,0.439,0.388}``
+
+``VerbatimColor``
+    The background color for :rst:dir:`code-block`\ s.
+
+    Default: ``{gray}{0.95}``
+
+    .. versionchanged:: 6.0.0
+
+       Formerly, it was ``{rgb}{1,1,1}`` (white).
+
+``VerbatimBorderColor``
+    The frame color.
+
+    Default: ``{RGB}{32,32,32}``
+
+    .. versionchanged:: 6.0.0
+
+       Formerly it was ``{rgb}{0,0,0}`` (black).
+
+``VerbatimHighlightColor``
+    The color for highlighted lines.
+
+    Default: ``{rgb}{0.878,1,1}``
+
+    .. versionadded:: 1.6.6
+
+.. _tablecolors:
+
+``TableRowColorHeader``
+    Sets the background color for (all) the header rows of tables.
+
+    It will have an effect only if either the :confval:`latex_table_style`
+    contains ``'colorrows'`` or if the table is assigned the ``colorrows``
+    class.  It is ignored for tables with ``nocolorrows`` class.
+
+    As for the other ``'sphinxsetup'`` keys, it can also be set or modified
+    from a ``\sphinxsetup{...}`` LaTeX command inserted via the :dudir:`raw`
+    directive, or also from a LaTeX environment associated to a `container
+    class <latexcontainer_>`_ and using such ``\sphinxsetup{...}``.
+
+    Default: ``{gray}{0.86}``
+
+    There is also ``TableMergeColorHeader``.  If used, sets a specific color
+    for merged single-row cells in the header.
+
+    .. versionadded:: 5.3.0
+
+``TableRowColorOdd``
+    Sets the background color for odd rows in tables (the row count starts at
+    ``1`` at the first non-header row).  Has an effect only if the
+    :confval:`latex_table_style` contains ``'colorrows'`` or for specific
+    tables assigned the ``colorrows`` class.
+
+    Default: ``{gray}{0.92}``
+
+    There is also ``TableMergeColorOdd``.
+
+    .. versionadded:: 5.3.0
+
+``TableRowColorEven``
+    Sets the background color for even rows in tables.
+
+    Default ``{gray}{0.98}``
+
+    There is also ``TableMergeColorEven``.
+
+    .. versionadded:: 5.3.0
+
+``verbatimsep``
+    The separation between code lines and the frame.
+
+    See :ref:`additionalcss` for its alias  ``pre_padding`` and
+    additional keys.
+
+    Default: ``\fboxsep``
+
+``verbatimborder``
+    The width of the frame around :rst:dir:`code-block`\ s.  See also
+    :ref:`additionalcss` for ``pre_border-width``.
+
+    Default: ``\fboxrule``
+
+``shadowsep``
+    The separation between contents and frame for contents_ and
+    :dudir:`topic` boxes.
+
+    See :ref:`additionalcss` for the alias ``div.topic_padding``.
+
+    Default: ``5pt``
+
+``shadowsize``
+    The width of the lateral "shadow" to the right and bottom.
+
+    See :ref:`additionalcss` for ``div.topic_box-shadow`` which allows to
+    configure separately the widths of the vertical and horizontal shadows.
+
+    Default: ``4pt``
+
+    .. versionchanged:: 6.1.2
+       Fixed a regression introduced at ``5.1.0`` which modified unintentionally
+       the width of topic boxes and worse had made usage of this key break PDF
+       builds.
+
+``shadowrule``
+    The width of the frame around :dudir:`topic` boxes.  See also
+    :ref:`additionalcss` for ``div.topic_border-width``.
+
+    Default: ``\fboxrule``
+
+|notebdcolors|
+    The color for the two horizontal rules used by Sphinx in LaTeX for styling
+    a :dudir:`note` type admonition.
+
+    Default: ``{rgb}{0,0,0}`` (black)
+
+|notebgcolors|
+    The optional color for the background.  It is a priori set to white, but
+    is not used, unless it has been set explicitly, and doing this triggers
+    Sphinx into switching to the more complex LaTeX code which is employed
+    also for ``warning`` type admonitions.  There are then additional options
+    which are described in :ref:`additionalcss`.
+
+    Default: ``{rgb}{1,1,1}`` (white)
+
+    .. versionadded:: 6.2.0
+
+|notetextcolors|
+    The optional color for the contents.
+
+    Default: unset (uses ambient text color, a priori black)
+
+    .. versionadded:: 6.2.0
+
+       To be considered experimental until 7.0.0.  These options have aliases
+       ``div.note_TeXcolor`` (etc) described in :ref:`additionalcss`.  Using
+       the latter will let Sphinx switch to a more complex LaTeX code,
+       which supports the customizability described in :ref:`additionalcss`.
+
+|notetexextras|
+    Some extra LaTeX code (such as ``\bfseries``  or ``\footnotesize``)
+    to be executed at start of the contents.
+
+    Default: empty
+
+    .. versionadded:: 6.2.0
+
+       To be considered experimental until 7.0.0.  These options have aliases
+       ``div.note_TeXextras`` (etc) described in :ref:`additionalcss`.
+
+``noteborder``, ``hintborder``, ``importantborder``, ``tipborder``
+    The width of the two horizontal rules.
+
+    If the background color is set, or the alternative :ref:`additionalcss`
+    syntax is used (e.g. ``div.note_border-width=1pt`` in place of
+    ``noteborder=1pt``), or *any* option with a CSS-alike name is used, then
+    the border is a full frame and this parameter sets its width also for left
+    and right.
+
+    Default: ``0.5pt``
+
+.. only:: not latex
+
+   |warningbdcolors|
+       The color for the admonition frame.
+
+   Default: ``{rgb}{0,0,0}`` (black)
+
+.. only:: latex
+
+   |wgbdcolorslatex|
+       The color for the admonition frame.
+
+   Default: ``{rgb}{0,0,0}`` (black)
+
+|warningbgcolors|
+    The background colors for the respective admonitions.
+
+    Default: ``{rgb}{1,1,1}`` (white)
+
+|warningborders|
+    The width of the frame.  See
+    :ref:`additionalcss` for keys allowing to configure separately each
+    border width.
+
+    Default: ``1pt``
+
+``AtStartFootnote``
+    LaTeX macros inserted at the start of the footnote text at bottom of page,
+    after the footnote number.
+
+    Default: ``\mbox{ }``
+
+``BeforeFootnote``
+    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
+
+``HeaderFamily``
+    default ``\sffamily\bfseries``. Sets the font used by headings.
+
+
+.. |notebdcolors| replace:: ``noteBorderColor``, ``hintBorderColor``,
+                            ``importantBorderColor``, ``tipBorderColor``
+
+.. |notebgcolors| replace:: ``noteBgColor``, ``hintBgColor``,
+                            ``importantBgColor``, ``tipBgColor``
+
+.. |notetextcolors| replace:: ``noteTextColor``, ``hintTextColor``,
+                              ``importantTextColor``, ``tipTextColor``
+
+.. |notetexextras| replace:: ``noteTeXextras``, ``hintTeXextras``,
+                             ``importantTeXextras``, ``tipTeXextras``
+
+.. |warningbdcolors| replace:: ``warningBorderColor``, ``cautionBorderColor``,
+                               ``attentionBorderColor``, ``dangerBorderColor``,
+                               ``errorBorderColor``
+
+.. |wgbdcolorslatex| replace:: ``warningBorderColor``, and
+                               ``(caution|attention|danger|error)BorderColor``
+
+.. else latex goes into right margin, as it does not hyphenate the names
+
+.. |warningbgcolors| replace:: ``warningBgColor``, ``cautionBgColor``,
+                               ``attentionBgColor``, ``dangerBgColor``,
+                               ``errorBgColor``
+
+.. |warningborders| replace:: ``warningborder``, ``cautionborder``,
+                              ``attentionborder``, ``dangerborder``,
+                              ``errorborder``
+
+.. _additionalcss:
+
+Additional  CSS-like ``'sphinxsetup'`` keys
+-------------------------------------------
+
+.. versionadded:: 5.1.0
+
+   For :rst:dir:`code-block`, :dudir:`topic` and contents_ directive,
+   and strong-type admonitions (:dudir:`warning`, :dudir:`error`, ...).
+
+.. versionadded:: 6.2.0
+
+   Also the :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip`
+   admonitions can be styled this way.  Using for them *any* of the listed
+   options will trigger usage of a more complex LaTeX code than the one used
+   per default (``sphinxheavybox`` vs ``sphinxlightbox``).  Setting the new
+   ``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of
+   ``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...).
+
+Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally
+imported from some genuine CSS external file, but currently they have to be used
+via the ``'sphinxsetup'`` interface (or the ``\sphinxsetup`` LaTeX command
+inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated.
+
+.. important:: Low-level LaTeX errors causing a build failure can happen if
+   the input syntax is not respected.
+
+   * In particular colors must be input as for the other color related options
+     previously described, i.e. either in the ``\definecolor`` syntax or, if
+     package ``xcolor`` is available (it is then automatically used) also the
+     ``\colorlet`` syntax::
+
+       ...<other options>
+       div.warning_border-TeXcolor={rgb}{1,0,0},% (always works)
+       div.error_background-TeXcolor=red!10,% (works only if xcolor is available)
+       ...<other options>
+
+   * A colon in place of the equal sign will break LaTeX.
+
+   * ``...border-width`` or ``...padding`` expect a *single* dimension: they can not
+     be used so far with space separated dimensions.
+
+   * ``...top-right-radius`` et al. values may be either a single or *two* space
+     separated dimensions.
+
+   * Dimension specifications must use TeX units such as ``pt`` or ``cm`` or
+     ``in``.  The ``px`` unit is recognized by ``pdflatex`` and ``lualatex``
+     but not by ``xelatex`` or ``platex``.
+
+   * It is allowed for such specifications to be so-called "dimensional
+     expressions", e.g. ``\fboxsep+2pt`` or ``0.5\baselineskip`` are valid
+     inputs.  The expressions will be evaluated only at the typesetting time.
+     Be careful though if using as in these examples TeX control sequences to
+     double the backslash or to employ a raw Python string for the value of
+     the :ref:`'sphinxsetup' <latexsphinxsetup>` key.
+
+   * As a rule, avoid inserting unneeded spaces in the key values: especially
+     for the radii an input such  ``2 pt 3pt`` will break LaTeX.  Beware also
+     that ``\fboxsep \fboxsep`` will not be seen as space separated in LaTeX.
+     You must use something such as ``{\fboxsep} \fboxsep``.  Or use
+     directly ``3pt 3pt`` which is a priori equivalent and simpler.
+
+The options are all named in a similar pattern which depends on a ``prefix``,
+which is then followed by an underscore, then the property name.
+
+.. csv-table::
+   :header: Directive, Option prefix, LaTeX environment
+
+   :rst:dir:`code-block`, ``pre``, ``sphinxVerbatim``
+   :dudir:`topic`, ``div.topic``, ``sphinxShadowBox``
+   contents_, ``div.topic``, ``sphinxShadowBox``
+   :dudir:`note`, ``div.note``, ``sphinxnote`` using ``sphinxheavybox``
+   :dudir:`warning`, ``div.warning``, ``sphinxwarning`` (uses ``sphinxheavybox``)
+   admonition type, ``div.<type>``,  ``sphinx<type>`` (using ``sphinxheavybox``)
+
+Here are now these options as well as their common defaults.
+Replace below ``<prefix>`` by the actual prefix as explained above.  Don't
+forget the underscore separating the prefix from the property names.
+
+- | ``<prefix>_border-top-width``,
+  | ``<prefix>_border-right-width``,
+  | ``<prefix>_border-bottom-width``,
+  | ``<prefix>_border-left-width``,
+  | ``<prefix>_border-width``.  The latter can (currently) be only a *single*
+    dimension which then sets all four others.
+
+  The default is that all those dimensions are equal.  They are set to:
+
+  * ``\fboxrule`` (i.e. a priori ``0.4pt``) for :rst:dir:`code-block`,
+  * ``\fboxrule`` for :dudir:`topic` or contents_ directive,
+  * ``1pt`` for  :dudir:`warning` and other "strong" admonitions,
+  * ``0.5pt`` for :dudir:`note` and other "light" admonitions.  The framing
+    style of the "lighbox" used for them in absence of usage of CSS-named
+    options will be emulated by the richer "heavybox" if setting
+    ``border-left-width`` and ``border-right-width`` both to ``0pt``.
+
+- ``<prefix>_box-decoration-break`` can be set to either ``clone`` or
+  ``slice`` and configures the behavior at page breaks.
+  It defaults to ``slice`` for :rst:dir:`code-block` (i.e. for ``<prefix>=pre``)
+  since 6.0.0.  For other directives the default is ``clone``.
+- | ``<prefix>_padding-top``,
+  | ``<prefix>_padding-right``,
+  | ``<prefix>_padding-bottom``,
+  | ``<prefix>_padding-left``,
+  | ``<prefix>_padding``.  The latter can (currently) be only a *single*
+    dimension which then sets all four others.
+
+  The default is that all those dimensions are equal.  They are set to:
+
+  * ``\fboxsep`` (i.e. a priori ``3pt``) for :rst:dir:`code-block`,
+  * ``5pt`` for :dudir:`topic` or contents_ directive,
+  * a special value for  :dudir:`warning` and other "strong" admonitions,
+    which ensures a backward compatible behavior.
+
+    .. important::
+
+       Prior to 5.1.0 there was no separate customizability of
+       padding for warning-type boxes in PDF via LaTeX output.  The sum of
+       padding and border-width (as set for example for :dudir:`warning` by
+       ``warningborder``, now also named ``div.warning_border-width``) was
+       kept to a certain constant value.  This limited the border-width
+       to small values else the border could overlap the text contents.
+       This behavior is kept as default.
+
+  * the same padding behavior is obeyed per default for :dudir:`note` or
+    other "light" admonitions when using ``sphinxheavybox``.
+- | ``<prefix>_border-top-left-radius``,
+  | ``<prefix>_border-top-right-radius``,
+  | ``<prefix>_border-bottom-right-radius``,
+  | ``<prefix>_border-bottom-left-radius``,
+  | ``<prefix>_border-radius``.  This last key sets the first four to
+    its assigned value.  Each key value can be either a single, or *two*,
+    dimensions which are then space separated.
+
+  The default is that all four corners are either circular or straight,
+  with common radii:
+
+  * ``\fboxsep`` (i.e. a priori ``3pt``) for :rst:dir:`code-block` (since 6.0.0).
+  * ``0pt`` for all other directives; this means to use straight corners.
+
+  See a remark above about traps with spaces in LaTeX.
+- ``<prefix>_box-shadow`` is special in so far as it may be:
+
+  * the ``none`` keyword,
+  * or a single dimension (giving both x-offset and y-offset),
+  * or two dimensions (separated by a space),
+  * or two dimensions followed by the keyword ``inset``.
+
+  The x-offset and y-offset may be negative.  The default is ``none``,
+  *except* for the :dudir:`topic` or contents_ directives, for which it is
+  ``4pt 4pt``, i.e. the shadow has a width of ``4pt`` and extends to the right
+  and below the frame.  The lateral shadow then extends into the page right
+  margin.
+- | ``<prefix>_border-TeXcolor``,
+  | ``<prefix>_background-TeXcolor``,
+  | ``<prefix>_box-shadow-TeXcolor``,
+  | ``<prefix>_TeXcolor``.
+    These are colors.
+
+  The shadow color defaults in all cases to ``{rgb}{0,0,0}`` i.e. to black.
+
+  Since 6.0.0 the border color and background color of :rst:dir:`code-block`,
+  i.e. ``pre`` prefix, default respectively to ``{RGB}{32,32,32}`` and
+  ``{gray}{0.95}``.  They previously defaulted to black, respectively white.
+
+  For all other types, the border color defaults to black and the background
+  color to white.
+
+  The ``<prefix>_TeXcolor`` stands for the CSS property "color", i.e. it
+  influences the text color of the contents.  As for the three other options,
+  the naming ``TeXcolor`` is to stress that the input syntax is the TeX one
+  for colors not an HTML/CSS one.  If package ``xcolor`` is available in the
+  LaTeX installation, one can use directly named colors as key values.
+  Consider passing options such as ``dvipsnames``, ``svgnames`` or ``x11names``
+  to ``xcolor`` via ``'passoptionstopackages'`` key of :confval:`latex_elements`.
+
+  If ``<prefix>_TeXcolor`` is set, a ``\color`` command is inserted at
+  start of the directive contents; for admonitions, this happens after the
+  heading which reproduces the admonition type.
+
+- ``<prefix>_TeXextras``: if set, its value must be some LaTeX command or
+  commands, for example ``\itshape``.  These commands will be inserted at the
+  start of the contents; for admonitions, this happens after the heading which
+  reproduces the admonition type.
+
+.. note::
+
+   - All directives support ``box-decoration-break`` to be set to ``slice``.
+
+     .. versionchanged:: 6.2.0
+
+        Formerly, only :rst:dir:`code-block` did.  The default remains
+        ``clone`` for all other directives, but this will probably change at
+        7.0.0.
+
+   - The corners of rounded boxes may be elliptical.
+
+     .. versionchanged:: 6.2.0
+
+        Formerly, only circular rounded corners were supported and a rounded
+        corner forced the whole frame to use the same constant width from
+        ``<prefix>_border-width``.
+
+   - Inset shadows are incompatible with rounded corners.  In case
+     both are specified the inset shadow will simply be ignored.
+
+     .. versionchanged:: 6.2.0
+
+        Formerly it was to the contrary the rounded corners which were ignored
+        in case an inset shadow was specified.
+
+   - ``<prefix>_TeXcolor`` and ``<prefix>_TeXextras`` are new with 6.2.0.
+
+     Usefulness is doubtful in the case of :rst:dir:`code-block`:
+
+     - ``pre_TeXcolor`` will influence only the few non-Pygments highlighted
+       tokens; it does color the line numbers, but if one wants to color
+       *only* them one has to go through the ``fancyvrb`` interface.
+
+     - ``pre_TeXextras=\footnotesize`` for example may be replaced by usage of
+       the :confval:`latex_elements` key ``'fvset'``.  For ``'lualatex'`` or
+       ``'xelatex'`` Sphinx includes in the preamble already
+       ``\fvset{fontsize=\small}`` and this induces ``fancyvrb`` into
+       overriding a ``\footnotesize`` coming from ``pre_TeXextras``.  One has
+       to use ``pre_TeXextras=\fvset{fontsize=\footnotesize}`` syntax.
+       Simpler to set directly the :confval:`latex_elements` key
+       ``'fvset'``...
+
+     Consider these options experimental and that some implementation details
+     may change.  For example if the ``pre_TeXextras`` LaTeX commands were put
+     by Sphinx in another location it could override the ``'fvset'`` effect,
+     perhaps this is what will be done in a future release.
+
+   - Rounded boxes are done using the pict2e_ interface to some basic PDF
+     graphics operations.  If this LaTeX package can not be found the build
+     will proceed and render all boxes with straight corners.
+
+   - Elliptic corners use the ellipse_ LaTeX package which extends pict2e_.
+     If this LaTeX package can not be found rounded corners will be circular
+     arcs (or straight if pict2e_ is not available).
+
+.. _pict2e: https://ctan.org/pkg/pict2e
+.. _ellipse: https://ctan.org/pkg/ellipse
+
+
+The following legacy behavior is currently not customizable:
+
+- For :rst:dir:`code-block`, padding and border-width and shadow (if one adds
+  one) will go into the margin; the code lines remain at the same place
+  independently of the values of the padding and border-width, except for
+  being shifted vertically of course to not overwrite other text due to the
+  width of the border or external shadow.
+
+- For :dudir:`topic` (and contents_) the shadow (if on right) goes into the
+  page margin, but the border and the extra padding are kept within the text
+  area.  Same for admonitions.
+
+- The contents_ and :dudir:`topic` directives are governed by the same options
+  with ``div.topic`` prefix: the Sphinx LaTeX mark-up uses for both directives
+  the same ``sphinxShadowBox`` environment which has currently no additional
+  branching, contrarily to the ``sphinxadmonition`` environment which branches
+  according to the admonition directive name, e.g. either to ``sphinxnote``
+  or ``sphinxwarning`` etc...
+
+
+LaTeX macros and environments
+-----------------------------
+
+The "LaTeX package" file :file:`sphinx.sty` loads various components
+providing support macros (aka commands), and environments, which are used in
+the mark-up produced on output from the ``latex`` builder, before conversion
+to ``pdf`` via the LaTeX toolchain.  Also the "LaTeX class" files
+:file:`sphinxhowto.cls` and :file:`sphinxmanual.cls` define or customize some
+environments.  All of these files can be found in the latex build repertory.
+
+Some of these provide facilities not available from pre-existing LaTeX
+packages and work around LaTeX limitations with lists, table cells, verbatim
+rendering, footnotes, etc...
+
+Others simply define macros with public names to make overwriting their
+defaults easy via user-added contents to the preamble.  We will survey most of
+those public names here, but defaults have to be looked at in their respective
+definition files.
+
+.. hint::
+
+   Sphinx LaTeX support code is split across multiple smaller-sized files.
+   Rather than adding code to the preamble via
+   `latex_elements <latex_elements_confval_>`_\ [``'preamble'``] it is
+   also possible to replace entirely one of the component files of Sphinx
+   LaTeX code with a custom version, simply by including a modified copy in
+   the project source and adding the filename to the
+   :confval:`latex_additional_files` list.  Check the LaTeX build repertory
+   for the filenames and contents.
+
+.. versionchanged:: 4.0.0
+   split of :file:`sphinx.sty` into multiple smaller units, to facilitate
+   customization of many aspects simultaneously.
+
+.. _latex-macros:
+
+Macros
+~~~~~~
+
+- Text styling commands:
+
+  .. csv-table::
+     :header: Name, ``maps argument #1 to:``
+     :align: left
+     :class: longtable
+     :delim: ;
+
+     ``\sphinxstrong``;         ``\textbf{#1}``
+     ``\sphinxcode``;           ``\texttt{#1}``
+     ``\sphinxbfcode``;         ``\textbf{\sphinxcode{#1}}``
+     ``\sphinxemail``;          ``\textsf{#1}``
+     ``\sphinxtablecontinued``; ``\textsf{#1}``
+     ``\sphinxtitleref``;       ``\emph{#1}``
+     ``\sphinxmenuselection``;  ``\emph{#1}``
+     ``\sphinxguilabel``;       ``\emph{#1}``
+     ``\sphinxkeyboard``;       ``\sphinxcode{#1}``
+     ``\sphinxaccelerator``;    ``\underline{#1}``
+     ``\sphinxcrossref``;       ``\emph{#1}``
+     ``\sphinxtermref``;        ``\emph{#1}``
+     ``\sphinxsamedocref``;     ``\emph{#1}``
+     ``\sphinxparam``;          ``\emph{#1}``
+     ``\sphinxtypeparam``;      ``\emph{#1}``
+     ``\sphinxoptional``; ``[#1]`` with larger brackets, see source
+
+  .. versionadded:: 1.4.5
+     Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict
+     with LaTeX packages.
+
+  .. versionadded:: 1.8
+     ``\sphinxguilabel``
+
+  .. versionadded:: 3.0
+     ``\sphinxkeyboard``
+
+  .. versionadded:: 6.2.0
+     ``\sphinxparam``, ``\sphinxsamedocref``
+
+  .. versionadded:: 7.1.0
+     ``\sphinxparamcomma`` which defaults to a comma followed by a space and
+     ``\sphinxparamcommaoneperline`` which is used for one-parameter-per-line
+     signatures (see :confval:`maximum_signature_line_length`).  It defaults
+     to ``\texttt{,}`` to make these end-of-line separators more distinctive.
+
+     Signatures of Python functions are rendered as ``name<space>(parameters)``
+     or ``name<space>[type parameters]<space>(parameters)`` (see :pep:`695`)
+     where the length of ``<space>`` is set to ``0pt`` by default.
+     This can be changed via ``\setlength{\sphinxsignaturelistskip}{1ex}``
+     for instance.
+
+- More text styling:
+
+  .. csv-table::
+     :header: Name, ``maps argument #1 to:``
+     :align: left
+     :class: longtable
+     :delim: ;
+
+     ``\sphinxstyleindexentry``;       ``\texttt{#1}``
+     ``\sphinxstyleindexextra``;       ``(\emph{#1})`` (with a space upfront)
+     ``\sphinxstyleindexpageref``;     ``, \pageref{#1}``
+     ``\sphinxstyleindexpagemain``;    ``\textbf{#1}``
+     ``\sphinxstyleindexlettergroup``; ``{\Large\sffamily#1}\nopagebreak\vspace{1mm}``
+     ``\sphinxstyleindexlettergroupDefault``; check source, too long for here
+     ``\sphinxstyletopictitle``;       ``\textbf{#1}\par\medskip``
+     ``\sphinxstylesidebartitle``;     ``\textbf{#1}\par\medskip``
+     ``\sphinxstyleothertitle``;       ``\textbf{#1}``
+     ``\sphinxstylesidebarsubtitle``;  ``~\\\textbf{#1} \smallskip``
+     ``\sphinxstyletheadfamily``;      ``\sffamily`` (*this one has no argument*)
+     ``\sphinxstyleemphasis``;         ``\emph{#1}``
+     ``\sphinxstyleliteralemphasis``;  ``\emph{\sphinxcode{#1}}``
+     ``\sphinxstylestrong``;           ``\textbf{#1}``
+     ``\sphinxstyleliteralstrong``;    ``\sphinxbfcode{#1}``
+     ``\sphinxstyleabbreviation``;     ``\textsc{#1}``
+     ``\sphinxstyleliteralintitle``;   ``\sphinxcode{#1}``
+     ``\sphinxstylecodecontinued``;    ``{\footnotesize(#1)}}``
+     ``\sphinxstylecodecontinues``;    ``{\footnotesize(#1)}}``
+     ``\sphinxstylenotetitle``;        ``\sphinxstrong{#1}<space>``
+     ``\sphinxstylehinttitle``;        *idem*
+     ``\sphinxstyleimportanttitle``;   *idem*
+     ``\sphinxstyletiptitle``;         *idem*
+     ``\sphinxstylewarningtitle``;     *idem*
+     ``\sphinxstylecautiontitle``;     *idem*
+     ``\sphinxstyleattentiontitle``;   *idem*
+     ``\sphinxstyledangertitle``;      *idem*
+     ``\sphinxstyleerrortitle``;       *idem*
+     ``\sphinxstyleseealsotitle``;     ``\sphinxstrong{#1}\par\nopagebreak``
+
+  .. versionadded:: 1.5
+     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:: 1.8
+     ``\sphinxstyleindexlettergroup``, ``\sphinxstyleindexlettergroupDefault``.
+
+  .. versionadded:: 6.2.0
+     ``\sphinxstylenotetitle`` et al.  The ``#1`` is the localized name of the
+     directive, with a final colon.  Wrap it as ``\sphinxremovefinalcolon{#1}``
+     if this final colon is to be removed.  Examples:
+
+     .. code-block:: latex
+
+        \renewcommand\sphinxstylewarningtitle[1]{%
+          \underline{\textbf{\sphinxremovefinalcolon{#1}}}\par
+        }
+        \renewcommand{\sphinxstylenotetitle}[1]{%
+          \textit{\textbf{\sphinxremovefinalcolon{#1}}}\par\nobreak
+          % LaTeX syntax is complex and we would be better off using \hrule.
+          {\parskip0pt\noindent}%
+          \raisebox{1ex}%
+           {\makebox[\linewidth]{\textcolor{sphinxnoteBorderColor}{\dotfill}}}
+          % It is complex to obtain nice vertical spacing for both a paragraph
+          % or a list following up; this set-up is better for a paragraph next.
+          \par\vskip-\parskip
+        }
+
+- ``\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.
+
+  .. versionchanged:: 2.0
+     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.
+
+  .. hint::
+
+     If adding to preamble the loading of ``tocloft`` package, also add to
+     preamble ``\renewcommand\sphinxtableofcontentshook{}`` else it will reset
+     ``\l@section`` and ``\l@subsection`` cancelling ``tocloft`` customization.
+
+- ``\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
+     Sphinx.
+
+- ``\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``: A wrapper of standard ``\cite`` for citation references.
+
+
+.. _sphinxbox:
+
+The ``\sphinxbox`` command
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 6.2.0
+
+The ``\sphinxbox[key=value,...]{inline text}`` command can be used to "box"
+inline text elements with all the customizability which has been described in
+:ref:`additionalcss`.  It is a LaTeX command with one optional argument, which
+is a comma-separated list of key=value pairs, as for :ref:`latexsphinxsetup`.
+Here is the complete list of keys.  They don't use any prefix.
+
+- ``border-width``,
+- ``border-top-width``, ``border-right-width``, ``border-bottom-width``,
+  ``border-left-width``,
+- ``padding``,
+- ``padding-top``, ``padding-right``, ``padding-bottom``, ``padding-left``,
+- ``border-radius``,
+- ``border-top-left-radius``, ``border-top-right-radius``,
+  ``border-bottom-right-radius``, ``border-bottom-left-radius``,
+- ``box-shadow``,
+- ``border-TeXcolor``, ``background-TeXcolor``, ``box-shadow-TeXcolor``,
+  ``TeXcolor``,
+- ``TeXextras``,
+- and ``addstrut`` which is a boolean key, i.e. to be used as ``addstrut=true``,
+  or ``addstrut`` alone where ``=true`` is omitted, or ``addstrut=false``.
+
+This last key is specific to ``\sphinxbox`` and it means to add a ``\strut``
+so that heights and depths are equalized across various instances on the same
+line with varying contents.  The default is ``addstrut=false``.
+
+.. important::
+
+   Perhaps the default will turn into ``addstrut=true`` at 7.0.0 depending on
+   feedback until then.
+
+The combination ``addstrut, padding-bottom=0pt, padding-top=1pt`` is often
+satisfactory.
+
+Refer to :ref:`additionalcss` for important syntax information regarding the
+other keys.  The default
+configuration uses no shadow, a border-width of ``\fboxrule``, a padding of
+``\fboxsep``, circular corners with radii ``\fboxsep`` and background and
+border colors as for the default rendering of code-blocks.
+
+When a ``\sphinxbox`` usage is nested within another one, it will ignore the
+options of the outer one: it first resets all options to their default state
+as they were prior to applying the outer box options, then it applies its own
+specific ones.
+
+One can modify these defaults via the command ``\sphinxboxsetup{key=value,...}``.
+The effect is cumulative, if one uses this command multiple times.  Here the
+options are a mandatory argument so are within curly braces, not square
+brackets.
+
+Here is some example of use:
+
+.. code-block:: latex
+
+   latex_elements = {
+       'preamble': r'''
+   % modify globally the defaults
+   \sphinxboxsetup{border-width=2pt,%
+                   border-radius=4pt,%
+                   background-TeXcolor=yellow!20}
+   % configure some styling element with some extra specific options:
+   \protected\def\sphinxkeyboard#1{\sphinxbox[border-TeXcolor=green]{\sphinxcode{#1}}}
+   ''',
+   }
+
+A utility ``\newsphinxbox`` is provided to create a new boxing macro, say
+``\foo`` which will act exactly like ``\sphinxbox`` but with a given extra
+configuration:
+
+.. code-block:: latex
+
+   % the specific options to \foo are within brackets
+   \newsphinxbox[border-radius=0pt, box-shadow=2pt 2pt]{\foo}
+   % then use this \foo, possibly with some extra options still:
+   \protected\def\sphinxguilabel#1{\foo{#1}}
+   \protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}}
+
+Boxes rendered with ``\foo`` obey as the ones using directly ``\sphinxbox``
+the current configuration as set possibly mid-way in document via
+``\sphinxboxsetup`` (from a :dudir:`raw` LaTeX mark-up), the only difference
+is that they have an initial additional set of default extras.
+
+In the above examples, you can probably use ``\renewcommand`` syntax if you
+prefer it to ``\protected\def`` (with ``[1]`` in place of ``#1`` then).
+
+
+Environments
+~~~~~~~~~~~~
+
+- 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
+     ``\par`` was lacking.
+
+- Environments associated with admonitions:
+
+  - ``sphinxnote``,
+  - ``sphinxhint``,
+  - ``sphinximportant``,
+  - ``sphinxtip``,
+  - ``sphinxwarning``,
+  - ``sphinxcaution``,
+  - ``sphinxattention``,
+  - ``sphinxdanger``,
+  - ``sphinxerror``.
+
+  They may be ``\renewenvironment``
+  'd individually, and must then be defined with one argument (it is the heading
+  of the notice, for example ``Warning:`` for :dudir:`warning` directive, if
+  English is the document language). Their default definitions use either the
+  *sphinxheavybox* (for the last 5 ones) or the *sphinxlightbox*
+  environments, configured to use the parameters (colors, border thickness)
+  specific to each type, which can be set via ``'sphinxsetup'`` string.
+
+  .. versionchanged:: 1.5
+     Use of public environment names, separate customizability of the
+     parameters, such as ``noteBorderColor``, ``noteborder``,
+     ``warningBgColor``, ``warningBorderColor``, ``warningborder``, ...
+
+- Environment for the :rst:dir:`seealso` directive: ``sphinxseealso``.
+  It takes one argument which will be the localized string ``See also``
+  followed with a colon.
+
+  .. versionadded:: 6.1.0
+  .. versionchanged:: 6.2.0
+
+     Colon made part of the mark-up rather than being inserted by the
+     environment for coherence with how admonitions are handled generally.
+
+- The 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.
+
+  .. versionchanged:: 1.5
+     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
+  page breaks. Inside tables the used
+  environment is ``sphinxVerbatimintable`` (it does not draw a frame, but
+  allows a caption).
+
+  .. versionchanged:: 1.5
+     ``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``,
+     ``verbatimsep``, ``verbatimborder``.
+
+  .. versionadded:: 1.6.6
+     Support for ``:emphasize-lines:`` option
+
+  .. versionadded:: 1.6.6
+     Easier customizability of the formatting via exposed to user LaTeX macros
+     such as ``\sphinxVerbatimHighlightLine``.
+
+- 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.
+
+Miscellany
+~~~~~~~~~~
+
+- Every text paragraph in document body starts with ``\sphinxAtStartPar``.
+  Currently, this is used to insert a zero width horizontal skip which
+  is a trick to allow TeX hyphenation of the first word of a paragraph
+  in a narrow context (like a table cell). For ``'lualatex'`` which
+  does not need the trick, the ``\sphinxAtStartPar`` does nothing.
+
+  .. versionadded:: 3.5.0
+
+- The section, subsection, ... headings are set using  *titlesec*'s
+  ``\titleformat`` command.
+
+- 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
+     dysfunctional.
+
+.. _latexcontainer:
+
+- Docutils :dudir:`container` directives are supported in LaTeX output: to
+  let a container class with name ``foo`` influence the final PDF via LaTeX,
+  it is only needed to define in the preamble an environment
+  ``sphinxclassfoo``.  A simple example would be:
+
+  .. code-block:: latex
+
+     \newenvironment{sphinxclassred}{\color{red}}{}
+
+  Currently the class names must contain only ascii characters and avoid
+  characters special to LaTeX such as ``\``.
+
+  .. versionadded:: 4.1.0
+
+.. hint::
+
+   As an experimental feature, Sphinx can use user-defined template file for
+   LaTeX source if you have a file named ``_templates/latex.tex_t`` in your
+   project.
+
+   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).
+
+   .. versionadded:: 1.6
+      currently all template variables are unstable and undocumented.
+
+.. raw:: latex
+
+   \endgroup