diff --git a/doc/latex.rst b/doc/latex.rst index 59a785c1e..53fe9301a 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1,7 +1,3 @@ -.. highlight:: python - -.. _latex: - LaTeX customization =================== @@ -26,24 +22,12 @@ LaTeX customization cautionBgColor={named}{LightCyan}} \relax -The *latex* target does not benefit from prepared themes. +Unlike :ref:`the HTML builders `, the ``latex`` builder does not +benefit from prepared themes. The :ref:`latex-options`, and particularly the +:ref:`latex_elements ` variable, provides much of the +interface for customization. For example: -The :ref:`latex-options`, and particularly among them the -:ref:`latex_elements ` variable -provides much of the interface for customization. - -For some details of the LaTeX/PDF builder command line -invocation, refer to :py:class:`~sphinx.builders.latex.LaTeXBuilder`. - -.. _latex-basic: - -Example -------- - -Keep in mind that backslashes must be doubled in Python string literals to -avoid interpretation as escape sequences, or use raw strings (as is done here). - -:: +.. code-block:: python # inside conf.py latex_engine = 'xelatex' @@ -65,433 +49,487 @@ avoid interpretation as escape sequences, or use raw strings (as is done here). } latex_show_urls = 'footnote' -.. highlight:: latex +.. note:: + + Keep in mind that backslashes must be doubled in Python string literals to + avoid interpretation as escape sequences. Alternatively, you may use raw + strings as is done above. .. _latex_elements_confval: -The latex_elements configuration setting ----------------------------------------- +The ``latex_elements`` configuration setting +-------------------------------------------- A dictionary that contains LaTeX snippets overriding those Sphinx usually puts into the generated ``.tex`` files. Its ``'sphinxsetup'`` key is described :ref:`separately `. -* Keys that you may want to override include: - - ``'papersize'`` - Paper size option of the document class (``'a4paper'`` or - ``'letterpaper'``), default ``'letterpaper'``. - - ``'pointsize'`` - Point size option of the document class (``'10pt'``, ``'11pt'`` or - ``'12pt'``), default ``'10pt'``. - - ``'pxunit'`` - the value of the ``px`` when used in image attributes ``width`` and - ``height``. The default value is ``'0.75bp'`` which achieves - ``96px=1in`` (in TeX ``1in = 72bp = 72.27pt``.) To obtain for - example ``100px=1in`` use ``'0.01in'`` or ``'0.7227pt'`` (the latter - leads to TeX computing a more precise value, due to the smaller unit - used in the specification); for ``72px=1in``, simply use ``'1bp'``; for - ``90px=1in``, use ``'0.8bp'`` or ``'0.803pt'``. - - .. versionadded:: 1.5 - - ``'passoptionstopackages'`` - A string which will be positioned early in the preamble, designed to - contain ``\\PassOptionsToPackage{options}{foo}`` commands. Default empty. - - .. versionadded:: 1.4 - - ``'babel'`` - "babel" package inclusion, default ``'\\usepackage{babel}'`` (the - suitable document language string is passed as class option, and - ``english`` is used if no language.) For Japanese documents, the - default is the empty string. - - With XeLaTeX and LuaLaTeX, Sphinx configures the LaTeX document to use - `polyglossia`_, but one should be aware that current `babel`_ has - improved its support for Unicode engines in recent years and for some - languages it may make sense to prefer ``babel`` over ``polyglossia``. - - .. hint:: - - After modifiying a core LaTeX key like this one, clean up the LaTeX - build repertory before next PDF build, else left-over auxiliary - files are likely to break the build. - - .. _`polyglossia`: https://ctan.org/pkg/polyglossia - .. _`babel`: https://ctan.org/pkg/babel - - .. versionchanged:: 1.5 - For :confval:`latex_engine` set to ``'xelatex'``, the default - is ``'\\usepackage{polyglossia}\n\\setmainlanguage{}'``. - .. versionchanged:: 1.6 - ``'lualatex'`` uses same default setting as ``'xelatex'`` - .. versionchanged:: 1.7.6 - For French, ``xelatex`` and ``lualatex`` default to using - ``babel``, not ``polyglossia``. - - ``'fontpkg'`` - Font package inclusion, the default is ``'\\usepackage{times}'`` which - uses Times for text, Helvetica for sans serif and Courier for monospace. - - .. versionchanged:: 1.2 - Defaults to ``''`` when the :confval:`language` uses the Cyrillic - script. - .. versionchanged:: 2.0 - Support for individual Greek and Cyrillic letters: - - - In order to support occasional Cyrillic (физика частиц) - or Greek letters (Σωματιδιακή φυσική) in - a document whose language is English or a Latin European - one, the default set-up is enhanced (only for ``'pdflatex'`` - engine) to do: - - .. code-block:: latex - - \substitutefont{LGR}{\rmdefault}{cmr} - \substitutefont{LGR}{\sfdefault}{cmss} - \substitutefont{LGR}{\ttdefault}{cmtt} - \substitutefont{X2}{\rmdefault}{cmr} - \substitutefont{X2}{\sfdefault}{cmss} - \substitutefont{X2}{\ttdefault}{cmtt} - - but this is activated only under the condition that the - ``'fontenc'`` key is configured to load the ``LGR`` (Greek) - and/or ``X2`` (Cyrillic) pdflatex-font encodings (if the - :confval:`language` is set to a Cyrillic language, this - ``'fontpkg'`` key must be used as "times" package has no direct - support for it; then keep only ``LGR`` lines from the above, - if support is needed for Greek in the text). - - The ``\substitutefont`` command is from the eponymous LaTeX - package, which is loaded by Sphinx if needed (on Ubuntu xenial it - is part of ``texlive-latex-extra`` which is a Sphinx - requirement). - - Only if the document actually does contain Unicode Greek letters - (in text) or Cyrillic letters, will the above default set-up - cause additional requirements for the PDF build. On Ubuntu - xenial, ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and - (with the above choice of fonts) the ``cm-super`` (or - ``cm-super-minimal``) package. - - - For ``'xelatex'`` and ``'lualatex'``, the default is to - use the FreeFont family: this OpenType font family - supports both Cyrillic and Greek scripts and is available as - separate Ubuntu xenial package ``fonts-freefont-otf``, it is not - needed to install the big package ``texlive-fonts-extra``. - - - ``'platex'`` (Japanese documents) engine supports individual - Cyrillic and Greek letters with no need of extra user set-up. +Keys that you may want to override include: - ``'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. +``'papersize'`` + Paper size option of the document class (``'a4paper'`` or + ``'letterpaper'``) - The default is ``''`` for Japanese documents. + Default: ``'letterpaper'`` - ``'preamble'`` - Additional preamble content, default empty. One may move all needed - macros into some file :file:`mystyle.tex.txt` of the project source - repertory, and get LaTeX to import it at run time:: +``'pointsize'`` + Point size option of the document class (``'10pt'``, ``'11pt'`` or + ``'12pt'``) - 'preamble': r'\input{mystyle.tex.txt}', - # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty - 'preamble': r'\usepackage{mystyle}', + Default: ``'10pt'`` - It is then needed to set appropriately - :confval:`latex_additional_files`, for example:: +``'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'``. - latex_additional_files = ["mystyle.sty"] + Default: ``'0.75bp'`` + .. versionadded:: 1.5 - ``'figure_align'`` - Latex figure float alignment, default 'htbp' (here, top, bottom, page). - Whenever an image doesn't fit into the current page, it will be - 'floated' into the next page but may be preceded by any other text. - If you don't like this behavior, use 'H' which will disable floating - and position figures strictly in the order they appear in the source. +``'passoptionstopackages'`` + A string which will be positioned early in the preamble, designed to + contain ``\\PassOptionsToPackage{options}{foo}`` commands. - .. versionadded:: 1.3 + Default: ``''`` - ``'atendofbody'`` - Additional document content (right before the indices), default empty. + .. versionadded:: 1.4 - .. versionadded:: 1.5 +``'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. - ``'extrapackages'`` - Additional LaTeX packages. For example: + 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``. - .. code-block:: python + .. _`polyglossia`: https://ctan.org/pkg/polyglossia + .. _`babel`: https://ctan.org/pkg/babel - latex_elements = { - 'packages': r'\usepackage{isodate}' - } + .. hint:: - It defaults to empty. - - The specified LaTeX packages will be loaded before - hyperref package and packages loaded from Sphinx extensions. - - .. hint:: If you'd like to load additional LaTeX packages after hyperref, use - ``'preamble'`` key instead. - - .. versionadded:: 2.3 - - ``'footer'`` - Additional footer content (before the indices), default empty. - - .. deprecated:: 1.5 - Use ``'atendofbody'`` key instead. - -* Keys that don't need to be overridden unless in special cases are: - - ``'extraclassoptions'`` - The default is the empty string. Example: ``'extraclassoptions': - 'openany'`` will allow chapters (for documents of the ``'manual'`` - type) to start on any page. - - .. versionadded:: 1.2 - .. versionchanged:: 1.6 - Added this documentation. - - ``'maxlistdepth'`` - LaTeX allows by default at most 6 levels for nesting list and - quote-like environments, with at most 4 enumerated lists, and 4 bullet - lists. Setting this key for example to ``'10'`` (as a string) will - allow up to 10 nested levels (of all sorts). Leaving it to the empty - string means to obey the LaTeX default. + After modifiying a core LaTeX key like this one, clean up the LaTeX + build repertory before next PDF build, else left-over auxiliary + files are likely to break the build. - .. warning:: - - - Using this key may prove incompatible with some LaTeX packages - or special document classes which do their own list customization. + Default: ``'\\usepackage{babel}'`` (``''`` for Japanese documents) - - 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. + .. versionchanged:: 1.5 + For :confval:`latex_engine` set to ``'xelatex'``, the default + is ``'\\usepackage{polyglossia}\n\\setmainlanguage{}'``. - .. versionadded:: 1.5 + .. versionchanged:: 1.6 + ``'lualatex'`` uses same default setting as ``'xelatex'`` - ``'inputenc'`` - "inputenc" package inclusion, defaults to - ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex. - Otherwise empty. + .. versionchanged:: 1.7.6 + For French, ``xelatex`` and ``lualatex`` default to using + ``babel``, not ``polyglossia``. - .. versionchanged:: 1.4.3 - Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all - compilers. +``'fontpkg'`` + Font package inclusion. The default of ``'\\usepackage{times}'`` uses Times + for text, Helvetica for sans serif and Courier for monospace. - ``'cmappkg'`` - "cmap" package inclusion, default ``'\\usepackage{cmap}'``. + In order to support occasional Cyrillic (физика частиц) or Greek + letters (Σωματιδιακή φυσική) in a document whose language is + English or a Latin European one, the default set-up is enhanced (only for + ``'pdflatex'`` engine) to do: - .. versionadded:: 1.2 + .. code-block:: latex - ``'fontenc'`` - "fontenc" package inclusion, defaults to - ``'\\usepackage[T1]{fontenc}'``. + \substitutefont{LGR}{\rmdefault}{cmr} + \substitutefont{LGR}{\sfdefault}{cmss} + \substitutefont{LGR}{\ttdefault}{cmtt} + \substitutefont{X2}{\rmdefault}{cmr} + \substitutefont{X2}{\sfdefault}{cmss} + \substitutefont{X2}{\ttdefault}{cmtt} - If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR`` - for support of Greek letters in the document, and also ``X2`` (or - ``T2A``) for Cyrillic letters, like this: + This is activated only under the condition that the ``'fontenc'`` key is + configured to load the ``LGR`` (Greek) and/or ``X2`` (Cyrillic) + pdflatex-font encodings (if the :confval:`language` is set to a Cyrillic + language, this ``'fontpkg'`` key must be used as "times" package has no + direct support for it; then keep only ``LGR`` lines from the above, if + support is needed for Greek in the text). - .. code-block:: latex + The ``\substitutefont`` command is from the eponymous LaTeX package, which + is loaded by Sphinx if needed (on Ubuntu Xenial it is part of + ``texlive-latex-extra`` which is a Sphinx requirement). - r'\usepackage[LGR,X2,T1]{fontenc}' + Only if the document actually does contain Unicode Greek letters (in text) + or Cyrillic letters, will the above default set-up cause additional + requirements for the PDF build. On Ubuntu Xenial, these are the + ``texlive-lang-greek``, ``texlive-lang-cyrillic``, and (with the above + choice of fonts) the ``cm-super`` (or ``cm-super-minimal``) packages. - .. attention:: + For ``'xelatex'`` and ``'lualatex'``, the default is to use the FreeFont + family: this OpenType font family supports both Cyrillic and Greek scripts + and is available as separate Ubuntu Xenial package ``fonts-freefont-otf``. + It is not necessary to install the much larger ``texlive-fonts-extra`` + package. - If Greek is main language, do not use this key. Since Sphinx 2.2.1, - ``xelatex`` will be used automatically as :confval:`latex_engine`. - Formerly, Sphinx did not support producing PDF via LaTeX with Greek as - main language. + ``'platex'`` (Japanese documents) engine supports individual Cyrillic and + Greek letters with no need of extra user set-up. - Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math - mark-up. This is not the case anymore, and the above must be used - (only in case of ``'pdflatex'`` engine) if the source contains such - Unicode Greek. + Default: ``'\\usepackage{times}'`` (or ``''`` when using a Cyrillic script) - On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super`` - (for the latter, only if the ``'fontpkg'`` setting is left to its - default) are needed for ``LGR`` to work. In place of ``cm-super`` - one can install smaller ``cm-super-minimal``, but it requires the - LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before - loading ``fontenc``. Thus, use this key with this extra at its - start if needed. + .. versionchanged:: 1.2 + Defaults to ``''`` when the :confval:`language` uses the Cyrillic + script. - .. versionchanged:: 1.5 - Defaults to ``'\\usepackage{fontspec}'`` when - :confval:`latex_engine` is ``'xelatex'``. - .. versionchanged:: 1.6 - ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``. - .. versionchanged:: 2.0 - ``'lualatex'`` executes - ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX - ligatures transforming `<<` and `>>` as escaping working with - ``pdflatex/xelatex`` failed with ``lualatex``. - .. versionchanged:: 2.0 - Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of - occasional Greek or Cyrillic (``'pdflatex'`` only, as this support - is provided natively by ``'platex'`` and only requires suitable - font with ``'xelatex'/'lualatex'``). - .. versionchanged:: 2.3.0 - ``'xelatex'`` also executes - ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid - contractions of ``--`` into en-dash or transforms of straight quotes - into curly ones in PDF (in non-literal text paragraphs) despite - :confval:`smartquotes` being set to ``False``. - - ``'textgreek'`` - The default (``'pdflatex'`` only) is - ``'\\usepackage{textalpha}'``, but only if ``'fontenc'`` was - modified by user to include ``LGR`` option. If not, the key - value will be forced to be the empty string. - - This is needed for ``pdfLaTeX`` to support Unicode input of Greek - letters such as φύσις. Expert users may want to load the ``textalpha`` - package with its option ``normalize-symbols``. - - .. hint:: - - Unicode Greek (but no further Unicode symbols) in :rst:dir:`math` - can be supported by ``'pdflatex'`` from setting this key to - ``r'\usepackage{textalpha,alphabeta}'``. Then ``:math:`α``` (U+03B1) - will render as :math:`\alpha`. For wider Unicode support in math - input, see the discussion of :confval:`latex_engine`. - - With ``'platex'`` (Japanese), ``'xelatex'`` or ``'lualatex'``, this - key is ignored. - - .. versionadded:: 2.0 - ``'geometry'`` - "geometry" package inclusion, the default definition is: - - ``'\\usepackage{geometry}'`` - - with an additional ``[dvipdfm]`` for Japanese documents. - The Sphinx LaTeX style file executes: - - ``\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}`` - - which can be customized via corresponding :ref:`'sphinxsetup' options - `. - - .. 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 - `. - - .. 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 ` documentation for more. - - ``'hyperref'`` - "hyperref" package inclusion; also loads package "hypcap" and issues - ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is - loaded and before executing the contents of ``'preamble'`` key. - - .. attention:: - - Loading of packages "hyperref" and "hypcap" is mandatory. - - .. versionadded:: 1.5 - Previously this was done from inside :file:`sphinx.sty`. - - ``'maketitle'`` - "maketitle" call, default ``'\\sphinxmaketitle'``. Override - if you want to generate a differently styled title page. - - .. hint:: - - If the key value is set to - ``r'\newcommand\sphinxbackoftitlepage{}\sphinxmaketitle'``, then ```` will be - typeset on back of title page (``'manual'`` docclass only). - - .. versionchanged:: 1.8.3 - Original ``\maketitle`` from document class is not overwritten, - hence is re-usable as part of some custom setting for this key. - .. versionadded:: 1.8.3 - ``\sphinxbackoftitlepage`` optional macro. It can also be defined - inside ``'preamble'`` key rather than this one. - - ``'releasename'`` - value that prefixes ``'release'`` element on title page, default - ``'Release'``. As for *title* and *author* used in the tuples of - :confval:`latex_documents`, it is inserted as LaTeX markup. - - ``'tableofcontents'`` - "tableofcontents" call, default ``'\\sphinxtableofcontents'`` (it is a - wrapper of unmodified ``\tableofcontents``, which may itself be - customized by user loaded packages.) - Override if - you want to generate a different table of contents or put content - between the title page and the TOC. - - .. versionchanged:: 1.5 - Previously the meaning of ``\tableofcontents`` itself was modified - by Sphinx. This created an incompatibility with dedicated packages - modifying it also such as "tocloft" or "etoc". - - ``'transition'`` - Commands used to display transitions, default - ``'\n\n\\bigskip\\hrule\\bigskip\n\n'``. Override if you want to - display transitions differently. - - .. versionadded:: 1.2 - .. versionchanged:: 1.6 - Remove unneeded ``{}`` after ``\\hrule``. - - ``'printindex'`` - "printindex" call, the last thing in the file, default - ``'\\printindex'``. Override if you want to generate the index - differently or append some content after the index. For example - ``'\\footnotesize\\raggedright\\printindex'`` is advisable when the - index is full of long entries. - - ``'fvset'`` - Customization of ``fancyvrb`` LaTeX package. Sphinx does by default - ``'fvset': '\\fvset{fontsize=\\small}'``, to adjust for the large - character width of the monospace font, used in code-blocks. - You may need to modify this if you use custom fonts. - - .. versionadded:: 1.8 - .. versionchanged:: 2.0 - Due to new default font choice for ``'xelatex'`` and ``'lualatex'`` - (FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these - engines (and not ``\\fvset{fontsize=auto}``). - -* Keys that are set by other options and therefore should not be overridden - are: - - ``'docclass'`` - ``'classoptions'`` - ``'title'`` - ``'release'`` - ``'author'`` - ``'makeindex'`` + .. versionchanged:: 2.0 + Added support for individual Greek and Cyrillic letters: + +``'fncychap'`` + Inclusion of the "fncychap" package (which makes fancy chapter titles), + default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation + (this option is slightly customized by Sphinx), + ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because + the "Bjarne" style uses numbers spelled out in English). Other + "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and + "Bjornstrup". You can also set this to ``''`` to disable fncychap. + + Default: ``'\\usepackage[Bjarne]{fncychap}'`` for English documents, + ``'\\usepackage[Sonny]{fncychap}'`` for internationalized documents, and + ``''`` for Japanese documents. + +``'preamble'`` + Additional preamble content. One may move all needed macros into some file + :file:`mystyle.tex.txt` of the project source repertory, and get LaTeX to + import it at run time:: + + 'preamble': r'\input{mystyle.tex.txt}', + # or, if the \ProvidesPackage LaTeX macro is used in a file mystyle.sty + 'preamble': r'\usepackage{mystyle}', + + It is then needed to set appropriately :confval:`latex_additional_files`, + for example: + + .. code-block:: python + + latex_additional_files = ["mystyle.sty"] + + Default: ``''`` + +``'figure_align'`` + Latex figure float alignment. Whenever an image doesn't fit into the current + page, it will be 'floated' into the next page but may be preceded by any + other text. If you don't like this behavior, use 'H' which will disable + floating and position figures strictly in the order they appear in the + source. + + Default: ``'htbp'`` (here, top, bottom, page) + + .. versionadded:: 1.3 + +``'atendofbody'`` + Additional document content (right before the indices). + + Default: ``''`` + + .. versionadded:: 1.5 + +``'extrapackages'`` + Additional LaTeX packages. For example: + + .. code-block:: python + + latex_elements = { + 'packages': r'\usepackage{isodate}' + } + + The specified LaTeX packages will be loaded before + hyperref package and packages loaded from Sphinx extensions. + + .. hint:: + If you'd like to load additional LaTeX packages after hyperref, use + ``'preamble'`` key instead. + + Default: ``''`` + + .. versionadded:: 2.3 + +``'footer'`` + Additional footer content (before the indices). + + Default: ``''`` + + .. deprecated:: 1.5 + Use ``'atendofbody'`` key instead. + +Keys that don't need to be overridden unless in special cases are: + +``'extraclassoptions'`` + The default is the empty string. Example: ``'extraclassoptions': + 'openany'`` will allow chapters (for documents of the ``'manual'`` + type) to start on any page. + + Default: ``''`` + + .. versionadded:: 1.2 + + .. versionchanged:: 1.6 + Added this documentation. + +``'maxlistdepth'`` + LaTeX allows by default at most 6 levels for nesting list and + quote-like environments, with at most 4 enumerated lists, and 4 bullet + lists. Setting this key for example to ``'10'`` (as a string) will + allow up to 10 nested levels (of all sorts). Leaving it to the empty + string means to obey the LaTeX default. + + .. warning:: + + - Using this key may prove incompatible with some LaTeX packages + or special document classes which do their own list customization. + + - The key setting is silently *ignored* if ``\usepackage{enumitem}`` + is executed inside the document preamble. Use then rather the + dedicated commands of this LaTeX package. + + Default: ``6`` + + .. versionadded:: 1.5 + +``'inputenc'`` + "inputenc" package inclusion. + + Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else + ``''`` + + .. versionchanged:: 1.4.3 + Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all + compilers. + +``'cmappkg'`` + "cmap" package inclusion. + + Default: ``'\\usepackage{cmap}'`` + + .. versionadded:: 1.2 + +``'fontenc'`` + "fontenc" package inclusion. + + If ``'pdflatex'`` is the :confval:`latex_engine`, one can add ``LGR`` + for support of Greek letters in the document, and also ``X2`` (or + ``T2A``) for Cyrillic letters, like this: + + .. code-block:: latex + + r'\usepackage[LGR,X2,T1]{fontenc}' + + .. attention:: + + If Greek is main language, do not use this key. Since Sphinx 2.2.1, + ``xelatex`` will be used automatically as :confval:`latex_engine`. + Formerly, Sphinx did not support producing PDF via LaTeX with Greek as + main language. + + Prior to 2.0, Unicode Greek letters were escaped to use LaTeX math + mark-up. This is not the case anymore, and the above must be used + (only in case of ``'pdflatex'`` engine) if the source contains such + Unicode Greek. + + On Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super`` + (for the latter, only if the ``'fontpkg'`` setting is left to its + default) are needed for ``LGR`` to work. In place of ``cm-super`` + one can install smaller ``cm-super-minimal``, but it requires the + LaTeX document to execute ``\usepackage[10pt]{type1ec}`` before + loading ``fontenc``. Thus, use this key with this extra at its + start if needed. + + Default: ``'\\usepackage[T1]{fontenc}'`` + + .. versionchanged:: 1.5 + Defaults to ``'\\usepackage{fontspec}'`` when + :confval:`latex_engine` is ``'xelatex'``. + + .. versionchanged:: 1.6 + ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``. + + .. versionchanged:: 2.0 + ``'lualatex'`` executes + ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX + ligatures transforming `<<` and `>>` as escaping working with + ``pdflatex/xelatex`` failed with ``lualatex``. + + .. versionchanged:: 2.0 + Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of + occasional Greek or Cyrillic (``'pdflatex'`` only, as this support + is provided natively by ``'platex'`` and only requires suitable + font with ``'xelatex'/'lualatex'``). + + .. versionchanged:: 2.3.0 + ``'xelatex'`` also executes + ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid + contractions of ``--`` into en-dash or transforms of straight quotes + into curly ones in PDF (in non-literal text paragraphs) despite + :confval:`smartquotes` being set to ``False``. + +``'textgreek'`` + This is needed for ``pdflatex`` to support Unicode input of Greek + letters such as φύσις. Expert users may want to load the ``textalpha`` + package with its option ``normalize-symbols``. + + .. hint:: + + Unicode Greek (but no further Unicode symbols) in :rst:dir:`math` + can be supported by ``'pdflatex'`` from setting this key to + ``r'\usepackage{textalpha,alphabeta}'``. Then ``:math:`α``` (U+03B1) + will render as :math:`\alpha`. For wider Unicode support in math + input, see the discussion of :confval:`latex_engine`. + + With ``'platex'`` (Japanese), ``'xelatex'`` or ``'lualatex'``, this + key is ignored. + + Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not + include the ``LGR`` option. + + .. versionadded:: 2.0 + +``'geometry'`` + "geometry" package inclusion, the default definition is: + + ``'\\usepackage{geometry}'`` + + with an additional ``[dvipdfm]`` for Japanese documents. + The Sphinx LaTeX style file executes: + + ``\PassOptionsToPackage{hmargin=1in,vmargin=1in,marginpar=0.5in}{geometry}`` + + which can be customized via corresponding :ref:`'sphinxsetup' options + `. + + 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 + `. + + .. 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 ` 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{}\sphinxmaketitle'``, then ```` 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``. + +``'printindex'`` + "printindex" call, the last thing in the file. Override if you want to + generate the index differently or append some content after the index. For + example ``'\\footnotesize\\raggedright\\printindex'`` is advisable when the + index is full of long entries. + + Default: ``'\\printindex'`` + +``'fvset'`` + Customization of ``fancyvrb`` LaTeX package. The default value of + ``'\\fvset{fontsize=\\small}'`` is used to adjust for the large character + width of the monospace font, used in code-blocks. You may need to modify + this if you use custom fonts. + + Default: ``'\\fvset{fontsize=\\small}'`` + + .. versionadded:: 1.8 + + .. versionchanged:: 2.0 + Due to new default font choice for ``'xelatex'`` and ``'lualatex'`` + (FreeFont), Sphinx does ``\\fvset{fontsize=\\small}`` also with these + engines (and not ``\\fvset{fontsize=auto}``). + +Keys that are set by other options and therefore should not be overridden are: + +``'docclass'`` +``'classoptions'`` +``'title'`` +``'release'`` +``'author'`` +``'makeindex'`` .. _latexsphinxsetup: -\\'sphinxsetup\\' key ---------------------- +The ``sphinxsetup`` configuration setting +----------------------------------------- + +.. versionadded:: 1.5 The ``'sphinxsetup'`` key of :ref:`latex_elements ` provides a LaTeX-type customization interface:: @@ -506,46 +544,40 @@ It defaults to empty. If non-empty, it will be passed as argument to the \usepackage{sphinx} \sphinxsetup{key1=value1, key2=value2,...} -.. versionadded:: 1.5 +The colors used in the above are provided by the ``svgnames`` option of the +"xcolor" package:: -.. hint:: + latex_elements = { + 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', + } - It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro - directly into the body of the document, via the help of the :rst:dir:`raw` - directive. Here is how this present chapter is styled in the PDF output:: +It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro +directly into the body of the document, via the help of the :rst:dir:`raw` +directive. This chapter is styled in the PDF output using the following at the +start of the chaper:: - .. raw:: latex + .. raw:: latex - \begingroup - \sphinxsetup{% - verbatimwithframe=false, - VerbatimColor={named}{OldLace}, - TitleColor={named}{DarkGoldenrod}, - hintBorderColor={named}{LightCoral}, - attentionborder=3pt, - attentionBorderColor={named}{Crimson}, - attentionBgColor={named}{FloralWhite}, - noteborder=2pt, - noteBorderColor={named}{Olive}, - cautionborder=3pt, - cautionBorderColor={named}{Cyan}, - cautionBgColor={named}{LightCyan}} + \begingroup + \sphinxsetup{% + verbatimwithframe=false, + VerbatimColor={named}{OldLace}, + TitleColor={named}{DarkGoldenrod}, + hintBorderColor={named}{LightCoral}, + attentionborder=3pt, + attentionBorderColor={named}{Crimson}, + attentionBgColor={named}{FloralWhite}, + noteborder=2pt, + noteBorderColor={named}{Olive}, + cautionborder=3pt, + cautionBorderColor={named}{Cyan}, + cautionBgColor={named}{LightCyan}} - at the start of the chapter and:: +The below is included at the end of the chapter:: - .. raw:: latex - - \endgroup - - at its end. - - The colors used in the above are provided by the ``svgnames`` option of the - "xcolor" package:: - - latex_elements = { - 'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}', - } + .. raw:: latex + \endgroup LaTeX boolean keys require *lowercase* ``true`` or ``false`` values. Spaces around the commas and equal signs are ignored, spaces inside LaTeX @@ -555,9 +587,8 @@ macros may be significant. ``hmargin, vmargin`` The dimensions of the horizontal (resp. vertical) margins, passed as - ``hmargin`` (resp. ``vmargin``) option to - the ``geometry`` package. The default is ``1in``, which is equivalent to - ``{1in,1in}``. Example:: + ``hmargin`` (resp. ``vmargin``) option to the ``geometry`` package. + Example:: 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in', @@ -567,6 +598,8 @@ macros may be significant. the text height set to an integer multiple of the baselineskip, with the closest fit for the margins. + Default: ``1in`` (equivalent to ``{1in,1in}``) + .. hint:: For Japanese ``'manual'`` docclass with pointsize ``11pt`` or ``12pt``, @@ -579,55 +612,68 @@ macros may be significant. .. versionadded:: 1.5.3 ``marginpar`` - The ``\marginparwidth`` LaTeX dimension, defaults to ``0.5in``. For Japanese - documents, the value is modified to be the closest integer multiple of the - *zenkaku* width. + The ``\marginparwidth`` LaTeX dimension. For Japanese documents, the value + is modified to be the closest integer multiple of the *zenkaku* width. + + Default: ``0.5in`` .. versionadded:: 1.5.3 ``verbatimwithframe`` - default ``true``. Boolean to specify if :rst:dir:`code-block`\ s and literal - includes are framed. Setting it to ``false`` does not deactivate use of - package "framed", because it is still in use for the optional background - colour. + Boolean to specify if :rst:dir:`code-block`\ s and literal includes are + framed. Setting it to ``false`` does not deactivate use of package + "framed", because it is still in use for the optional background colour. + + Default: ``true``. ``verbatimwrapslines`` - default ``true``. Tells whether long lines in :rst:dir:`code-block`\ 's - contents should wrap. + Boolean to specify if long lines in :rst:dir:`code-block`\ 's contents are + wrapped. + + Default: ``true`` ``literalblockcappos`` - default ``t`` for "top". Decides the caption position. Alternative is - ``b`` ("bottom"). + Decides the caption position: either ``b`` ("bottom") or ``t`` ("top"). + + Default: ``t`` .. versionadded:: 1.7 ``verbatimhintsturnover`` - default ``true``. If ``true``, code-blocks display "continued on next - page", "continued from previous page" hints in case of pagebreaks. + Boolean to specify if code-blocks display "continued on next page" and + "continued from previous page" hints in case of pagebreaks. + + Default: ``true`` .. versionadded:: 1.6.3 .. versionchanged:: 1.7 the default changed from ``false`` to ``true``. ``verbatimcontinuedalign``, ``verbatimcontinuesalign`` - default ``r``. Horizontal position relative to the framed contents: - either ``l`` (left aligned), ``r`` (right aligned) or ``c`` (centered). + Horizontal position relative to the framed contents: either ``l`` (left + aligned), ``r`` (right aligned) or ``c`` (centered). + + Default: ``r`` .. versionadded:: 1.7 ``parsedliteralwraps`` - default ``true``. Tells whether long lines in :dudir:`parsed-literal`\ 's - contents should wrap. + Boolean to specify if long lines in :dudir:`parsed-literal`\ 's contents + should wrap. + + Default: ``true`` .. versionadded:: 1.5.2 set this option value to ``false`` to recover former behaviour. ``inlineliteralwraps`` - default ``true``. Allows linebreaks inside inline literals: but extra - potential break-points (additionally to those allowed by LaTeX at spaces - or for hyphenation) are currently inserted only after the characters + Boolean to specify if line breaks are allowed inside inline literals: but + extra potential break-points (additionally to those allowed by LaTeX at + spaces or for hyphenation) are currently inserted only after the characters ``. , ; ? ! /`` and ``\``. Due to TeX internals, white space in the line - will be stretched (or shrunk) in order to accomodate the linebreak. + will be stretched (or shrunk) in order to accommodate the linebreak. + + Default: ``true`` .. versionadded:: 1.5 set this option value to ``false`` to recover former behaviour. @@ -636,9 +682,10 @@ macros may be significant. added potential breakpoint at ``\`` characters. ``verbatimvisiblespace`` - default ``\textcolor{red}{\textvisiblespace}``. When a long code line is - split, the last space character from the source code line right before the - linebreak location is typeset using this. + When a long code line is split, the last space character from the source + code line right before the linebreak location is typeset using this. + + Default: ``\textcolor{red}{\textvisiblespace}`` ``verbatimcontinued`` A LaTeX macro inserted at start of continuation code lines. Its @@ -652,8 +699,9 @@ macros may be significant. various font sizes (e.g. code-blocks can be in footnotes). ``TitleColor`` - default ``{rgb}{0.126,0.263,0.361}``. The colour for titles (as configured - via use of package "titlesec".) + The colour for titles (as configured via use of package "titlesec".) + + Default: ``{rgb}{0.126,0.263,0.361}`` .. warning:: @@ -661,22 +709,31 @@ macros may be significant. argument of the ``color/xcolor`` packages ``\definecolor`` command. ``InnerLinkColor`` - default ``{rgb}{0.208,0.374,0.486}``. A colour passed to ``hyperref`` as - value of ``linkcolor`` and ``citecolor``. + A colour passed to ``hyperref`` as value of ``linkcolor`` and + ``citecolor``. + + Default: ``{rgb}{0.208,0.374,0.486}``. ``OuterLinkColor`` - default ``{rgb}{0.216,0.439,0.388}``. A colour passed to ``hyperref`` as - value of ``filecolor``, ``menucolor``, and ``urlcolor``. + A colour passed to ``hyperref`` as value of ``filecolor``, ``menucolor``, + and ``urlcolor``. + + Default: ``{rgb}{0.216,0.439,0.388}`` ``VerbatimColor`` - default ``{rgb}{1,1,1}``. The background colour for - :rst:dir:`code-block`\ s. The default is white. + The background colour for :rst:dir:`code-block`\ s. + + Default: ``{rgb}{1,1,1}`` (white) ``VerbatimBorderColor`` - default ``{rgb}{0,0,0}``. The frame color, defaults to black. + The frame color. + + Default: ``{rgb}{0,0,0}`` (black) ``VerbatimHighlightColor`` - default ``{rgb}{0.878,1,1}``. The color for highlighted lines. + The color for highlighted lines. + + Default: ``{rgb}{0.878,1,1}`` .. versionadded:: 1.6.6 @@ -686,54 +743,77 @@ macros may be significant. names declared to "color" or "xcolor" are prefixed with "sphinx". ``verbatimsep`` - default ``\fboxsep``. The separation between code lines and the frame. + The separation between code lines and the frame. + + Default: ``\fboxsep`` ``verbatimborder`` - default ``\fboxrule``. The width of the frame around - :rst:dir:`code-block`\ s. + The width of the frame around :rst:dir:`code-block`\ s. + + Default: ``\fboxrule`` ``shadowsep`` - default ``5pt``. The separation between contents and frame for - :dudir:`contents` and :dudir:`topic` boxes. + The separation between contents and frame for :dudir:`contents` and + :dudir:`topic` boxes. + + Default: ``5pt`` ``shadowsize`` - default ``4pt``. The width of the lateral "shadow" to the right. + The width of the lateral "shadow" to the right. + + Default: ``4pt`` ``shadowrule`` - default ``\fboxrule``. The width of the frame around :dudir:`topic` boxes. + The width of the frame around :dudir:`topic` boxes. + + Default: ``\fboxrule`` |notebdcolors| - default ``{rgb}{0,0,0}`` (black). The colour for the two horizontal rules - used by Sphinx in LaTeX for styling a :dudir:`note` type admonition. + The colour for the two horizontal rules used by Sphinx in LaTeX for styling + a :dudir:`note` type admonition. + + Default: ``{rgb}{0,0,0}`` (black) ``noteborder``, ``hintborder``, ``importantborder``, ``tipborder`` - default ``0.5pt``. The width of the two horizontal rules. + The width of the two horizontal rules. + + Default: ``0.5pt`` .. only:: not latex |warningbdcolors| - default ``{rgb}{0,0,0}`` (black). The colour for the admonition frame. + The colour for the admonition frame. + + Default: ``{rgb}{0,0,0}`` (black) .. only:: latex |wgbdcolorslatex| - default ``{rgb}{0,0,0}`` (black). The colour for the admonition frame. + The colour for the admonition frame. + + Default: ``{rgb}{0,0,0}`` (black) |warningbgcolors| - default ``{rgb}{1,1,1}`` (white). The background colours for the respective - admonitions. + The background colours for the respective admonitions. + + Default: ``{rgb}{1,1,1}`` (white) |warningborders| - default ``1pt``. The width of the frame. + The width of the frame. + + Default: ``1pt`` ``AtStartFootnote`` - default ``\mbox{ }``. LaTeX macros inserted at the start of the footnote - text at bottom of page, after the footnote number. + LaTeX macros inserted at the start of the footnote text at bottom of page, + after the footnote number. + + Default: ``\mbox{ }`` ``BeforeFootnote`` - default ``\leavevmode\unskip``. LaTeX macros inserted before the footnote - mark. The default removes possible space before it (else, TeX could insert - a linebreak there). + LaTeX macros inserted before the footnote mark. The default removes + possible space before it (else, TeX could insert a line break there). + + Default: ``\leavevmode\unskip`` .. versionadded:: 1.5 @@ -762,6 +842,7 @@ macros may be significant. ``attentionborder``, ``dangerborder``, ``errorborder`` + LaTeX macros and environments ----------------------------- @@ -774,7 +855,7 @@ thus allowing redefinitions. Check the respective files for the defaults. Macros ~~~~~~ -- text styling commands: +- Text styling commands: - ``\sphinxstrong``, - ``\sphinxbfcode``, @@ -786,11 +867,12 @@ Macros - ``\sphinxcrossref``, - ``\sphinxtermref``, - ``\sphinxoptional``. - + .. versionadded:: 1.4.5 Use of ``\sphinx`` prefixed macro names to limit possibilities of conflict with LaTeX packages. -- more text styling: + +- More text styling: - ``\sphinxstyleindexentry``, - ``\sphinxstyleindexextra``, @@ -808,58 +890,66 @@ Macros - ``\sphinxstyleliteralintitle``, - ``\sphinxstylecodecontinued``, - ``\sphinxstylecodecontinues``. - + .. versionadded:: 1.5 - these macros were formerly hard-coded as non customizable ``\texttt``, + These macros were formerly hard-coded as non customizable ``\texttt``, ``\emph``, etc... + .. versionadded:: 1.6 ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows multiple paragraphs in header cells of tables. + .. versionadded:: 1.6.3 ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``. + .. versionadded:: 3.0 ``\sphinxkeyboard`` -- ``\sphinxtableofcontents``: it is a - wrapper (defined differently in :file:`sphinxhowto.cls` and in - :file:`sphinxmanual.cls`) of standard ``\tableofcontents``. The macro - ``\sphinxtableofcontentshook`` is executed during its expansion right before - ``\tableofcontents`` itself. + +- ``\sphinxtableofcontents``: A wrapper (defined differently in + :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard + ``\tableofcontents``. The macro ``\sphinxtableofcontentshook`` is executed + during its expansion right before ``\tableofcontents`` itself. .. versionchanged:: 1.5 - formerly, the meaning of ``\tableofcontents`` was modified by Sphinx. + Formerly, the meaning of ``\tableofcontents`` was modified by Sphinx. + .. versionchanged:: 2.0 - hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly + Hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly done during loading of ``'manual'`` docclass are now executed later via ``\sphinxtableofcontentshook``. This macro is also executed by the ``'howto'`` docclass, but defaults to empty with it. -- ``\sphinxmaketitle``: it is defined in the class files - :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls` and is used as - default setting of ``'maketitle'`` :confval:`latex_elements` key. + +- ``\sphinxmaketitle``: Used as the default setting of the ``'maketitle'`` + :confval:`latex_elements` key. + Defined in the class files :file:`sphinxmanual.cls` and + :file:`sphinxhowto.cls`. .. versionchanged:: 1.8.3 - formerly, ``\maketitle`` from LaTeX document class was modified by + Formerly, ``\maketitle`` from LaTeX document class was modified by Sphinx. -- ``\sphinxbackoftitlepage``: for ``'manual'`` docclass, and if it is + +- ``\sphinxbackoftitlepage``: For ``'manual'`` docclass, and if it is defined, it gets executed at end of ``\sphinxmaketitle``, before the final ``\clearpage``. Use either the ``'maketitle'`` key or the ``'preamble'`` key of :confval:`latex_elements` to add a custom definition of ``\sphinxbackoftitlepage``. .. versionadded:: 1.8.3 -- ``\sphinxcite``: it is a wrapper of standard ``\cite`` for citation - references. + +- ``\sphinxcite``: A wrapper of standard ``\cite`` for citation references. Environments ~~~~~~~~~~~~ -- a :dudir:`figure` may have an optional legend with arbitrary body +- A :dudir:`figure` may have an optional legend with arbitrary body elements: they are rendered in a ``sphinxlegend`` environment. The default definition issues ``\small``, and ends with ``\par``. .. versionadded:: 1.5.6 - formerly, the ``\small`` was hardcoded in LaTeX writer and the ending + Formerly, the ``\small`` was hardcoded in LaTeX writer and the ending ``\par`` was lacking. -- environments associated with admonitions: + +- Environments associated with admonitions: - ``sphinxnote``, - ``sphinxhint``, @@ -880,17 +970,20 @@ Environments specific to each type, which can be set via ``'sphinxsetup'`` string. .. versionchanged:: 1.5 - use of public environment names, separate customizability of the + Use of public environment names, separate customizability of the parameters, such as ``noteBorderColor``, ``noteborder``, ``warningBgColor``, ``warningBorderColor``, ``warningborder``, ... -- the :dudir:`contents` directive (with ``:local:`` option) and the + +- The :dudir:`contents` directive (with ``:local:`` option) and the :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``. .. versionadded:: 1.4.2 - former code refactored into an environment allowing page breaks. + Former code refactored into an environment allowing page breaks. + .. versionchanged:: 1.5 - options ``shadowsep``, ``shadowsize``, ``shadowrule``. -- the literal blocks (via ``::`` or :rst:dir:`code-block`), are + Options ``shadowsep``, ``shadowsize``, ``shadowrule``. + +- The literal blocks (via ``::`` or :rst:dir:`code-block`), are implemented using ``sphinxVerbatim`` environment which is a wrapper of ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling of the top caption and the wrapping of long lines, and a frame which allows @@ -902,34 +995,39 @@ Environments ``Verbatim`` keeps exact same meaning as in ``fancyvrb.sty`` (also under the name ``OriginalVerbatim``); ``sphinxVerbatimintable`` is used inside tables. + .. versionadded:: 1.5 - options ``verbatimwithframe``, ``verbatimwrapslines``, + Options ``verbatimwithframe``, ``verbatimwrapslines``, ``verbatimsep``, ``verbatimborder``. + .. versionadded:: 1.6.6 - support for ``:emphasize-lines:`` option + Support for ``:emphasize-lines:`` option + .. versionadded:: 1.6.6 - easier customizability of the formatting via exposed to user LaTeX macros + Easier customizability of the formatting via exposed to user LaTeX macros such as ``\sphinxVerbatimHighlightLine``. -- the bibliography uses ``sphinxthebibliography`` and the Python Module index + +- The bibliography uses ``sphinxthebibliography`` and the Python Module index as well as the general index both use ``sphinxtheindex``; these environments are wrappers of the ``thebibliography`` and respectively ``theindex`` environments as provided by the document class (or packages). .. versionchanged:: 1.5 - formerly, the original environments were modified by Sphinx. + Formerly, the original environments were modified by Sphinx. Miscellany ~~~~~~~~~~ -- the section, subsection, ... headings are set using *titlesec*'s +- The section, subsection, ... headings are set using *titlesec*'s ``\titleformat`` command. -- for the ``'manual'`` docclass, the chapter headings can be customized using + +- For the ``'manual'`` docclass, the chapter headings can be customized using *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. File :file:`sphinx.sty` has custom re-definitions in case of *fncychap* option ``Bjarne``. .. versionchanged:: 1.5 - formerly, use of *fncychap* with other styles than ``Bjarne`` was + Formerly, use of *fncychap* with other styles than ``Bjarne`` was dysfunctional. .. hint:: @@ -938,9 +1036,6 @@ Miscellany LaTeX source if you have a file named ``_templates/latex.tex_t`` in your project. - .. versionadded:: 1.5 - currently all template variables are unstable and undocumented. - Additional files ``longtable.tex_t``, ``tabulary.tex_t`` and ``tabular.tex_t`` can be added to ``_templates/`` to configure some aspects of table rendering (such as the caption position). diff --git a/doc/usage/theming.rst b/doc/usage/theming.rst index 0aae78718..792a4a53d 100644 --- a/doc/usage/theming.rst +++ b/doc/usage/theming.rst @@ -1,5 +1,7 @@ .. highlight:: python +.. _html-themes: + HTML ====