diff options
Diffstat (limited to 'doc/latex.rst')
| -rw-r--r-- | doc/latex.rst | 1841 |
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 |