IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

LaTeX: Revamp the styling of all admonitions (#12508)

Browse Source 
In LaTeX output, all admonitions now also have a title row with icon.

The ``xcolor`` LaTeX package is now required and the ``fontawesome5`` LaTeX package is needed for the icons.
This commit is contained in:
Jean-François B 2024-07-13 18:33:22 +02:00 committed by GitHub
parent e49e2933bb
commit aa6dac81ec
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 939 additions and 685 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
CHANGES.rst
View File

@ -6,6 +6,13 @@ Dependencies
* #12555: Drop Docutils 0.18.1 and Docutils 0.19 support.
Patch by Adam Turner.
* LaTeX: the ``xcolor`` package is now required (but is for example part of
Ubuntu ``texlive-latex-recommended`` which has always been required).
* LaTeX: the ``fontawesome5`` LaTeX package is needed for the default choices
of icons now used in admonition titles in PDF output; but if unavailable the
PDF build will simply silently omit rendering such icons. Check the
documentation of the ``iconpackage`` key of :ref:`'sphinxsetup'
<latexsphinxsetup>` for more.
Incompatible changes
--------------------
@ -13,6 +20,9 @@ Incompatible changes
Deprecated
----------
* LaTeX: the ``sphinxlightbox`` environment is not used anymore, all types
of admonitions use (by default) only ``sphinxheavybox``.
Features added
--------------
@ -85,6 +95,9 @@ Features added
Patch by Ashley Whetter.
* #6792: Prohibit module import cycles in :mod:`sphinx.ext.autosummary`.
Patch by Trevor Bekolay.
* #12508: LaTeX: Revamped styling of all admonitions, with addition of a
title row with icon.
Patch by Jean-François B.
Bugs fixed
----------

3
bindep.txt
View File

@ -14,10 +14,13 @@ texlive-ctablestack [platform:rpm]
texlive-gnu-freefont [platform:rpm]
texlive-tex-gyre [platform:rpm]
texlive-pict2e [platform:rpm]
texlive-fontawesome5 [platform:rpm]
texlive-xcolor [platform:rpm]
latexmk [platform:rpm]
texlive-latex-recommended [platform:dpkg]
texlive-fonts-recommended [platform:dpkg]
texlive-fonts-extra [platform:dpkg]
tex-gyre [platform:dpkg]
texlive-latex-extra [platform:dpkg]
texlive-luatex [platform:dpkg]

390
doc/latex.rst
View File

@ -10,12 +10,12 @@ LaTeX customization
\begingroup
\sphinxsetup{%
TitleColor={named}{DarkGoldenrod},
TitleColor=DarkGoldenrod,
pre_border-width=2pt,
pre_border-right-width=8pt,
pre_padding=5pt,
pre_border-radius=5pt,
pre_background-TeXcolor={named}{OldLace},
pre_background-TeXcolor=OldLace,
pre_border-TeXcolor=Gold!90,
pre_box-shadow=6pt 6pt,
pre_box-shadow-TeXcolor=gray!20,
@ -52,6 +52,9 @@ interface for customization. For example:
# inside conf.py
latex_engine = 'xelatex'
latex_elements = {
'passoptionstopackages': r'''
\PassOptionsToPackage{svgnames}{xcolor}
''',
'fontpkg': r'''
\setmainfont{DejaVu Serif}
\setsansfont{DejaVu Sans}
@ -64,6 +67,7 @@ interface for customization. For example:
\setlength{\cftsecindent}{\cftchapnumwidth}
\setlength{\cftsecnumwidth}{1.25cm}
''',
'sphinxsetup': 'TitleColor=DarkGoldenrod',
'fncychap': r'\usepackage[Bjornstrup]{fncychap}',
'printindex': r'\footnotesize\raggedright\printindex',
}
@ -591,23 +595,22 @@ provides a LaTeX-type customization interface::
'sphinxsetup': 'key1=value1, key2=value2, ...',
}
It defaults to empty. If non-empty, it will be passed as argument to the
LaTeX syntax for boolean keys requires *lowercase* ``true`` or ``false``
e.g ``'sphinxsetup': "verbatimwrapslines=false"``. If setting a
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 ticks/quotes to enclose string or numerical values.
The ``'sphinxsetup'`` 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`.
into the body of the document, via the ``raw`` directive:
.. code-block:: latex
@ -615,83 +618,31 @@ uses keys described later in :ref:`additionalcss`.
\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.
TitleColor=DarkGoldenrod,
... more comma separated key=value using LaTeX syntax ...
}
And this is placed at the end of the chapter source to end the scope of
the configuration:
.. code-block:: latex
All elements here will be under the influence of the raw ``\sphinxsetup``
settings.
.. 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.
From here on, the raw ``\sphinxsetup`` has no effect anymore.
This is the technique which has been used to style especially the present part
of the documentation for the PDF output. The actually used options will be
found at top of :file:`doc/latex.rst` at the `development repository`_.
.. _development repository: https://github.com/sphinx-doc/sphinx
The color used in the above example is available from having passed the
``svgnames`` option to the "xcolor" package::
latex_elements = {
'passoptionstopackages': r'\PassOptionsToPackage{svgnames}{xcolor}',
}
``bookmarksdepth``
Controls the depth of the collapsible bookmarks panel in the PDF.
@ -878,11 +829,10 @@ Do not use quotes to enclose values, whether numerical or strings.
- 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
``{gray}{0.75}`` or ``{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.
@ -912,7 +862,7 @@ Do not use quotes to enclose values, whether numerical or strings.
``VerbatimColor``
The background color for :rst:dir:`code-block`\ s.
Default: ``{gray}{0.95}``
Default: ``{RGB}{242,242,242}`` (same as ``{gray}{0.95}``).
.. versionchanged:: 6.0.0
@ -1017,27 +967,48 @@ Do not use quotes to enclose values, whether numerical or strings.
Default: ``\fboxrule``
|notebdcolors|
The color for the two horizontal rules used by Sphinx in LaTeX for styling
a :dudir:`note` type admonition.
.. important::
Default: ``{rgb}{0,0,0}`` (black)
At 7.4.0 all admonitions (not only danger-type) use the possibilities
which were added at 5.1.0 and 6.2.0. All defaults have changed.
``iconpackage``
The name of the LaTeX package used for icons in the admonition titles. It
defaults to ``fontawesome5`` or to fall-back ``fontawesome``. In case
neither one is available the option value will automatically default to
``none``, which means that no attempt at loading a package is done.
Independently of this setting, arbitrary LaTeX code can be associated to
each admonition type via ``div.<type>_icon-title`` keys which are
described in the :ref:`additionalcss` section. If these keys are not
used, Sphinx will either apply its default choices of icons (if
``fontawesome{5,}`` is available) or not draw the icon at all. Notice that
if fall-back ``fontawesome`` is used the common icon for :dudir:`caution`
and :dudir:`danger` will default to "bolt" not "radiation", which is only
found in ``fontawesome5``.
.. versionadded:: 7.4.0
|notebdcolors|
The color for the admonition border.
Default: ``{RGB}{134,152,155}``.
.. versionchanged:: 7.4.0
|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`.
The color for the admonition background.
Default: ``{rgb}{1,1,1}`` (white)
Default: ``{RGB}{247,247,247}``.
.. versionadded:: 6.2.0
|notetextcolors|
The optional color for the contents.
.. versionchanged:: 7.4.0
Default: unset (uses ambient text color, a priori black)
|notetextcolors|
The color for the admonition contents.
Default: unset (contents text uses ambient text color, a priori black)
.. versionadded:: 6.2.0
@ -1058,41 +1029,45 @@ Do not use quotes to enclose values, whether numerical or strings.
``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.
The width of the border. See
:ref:`additionalcss` for keys allowing to configure separately each
border width.
Default: ``0.5pt``
.. only:: not latex
|warningbdcolors|
The color for the admonition frame.
The color for the admonition border.
Default: ``{rgb}{0,0,0}`` (black)
Default: ``{RGB}{148,0,0}`` except for ``error`` which uses ``red``.
.. versionchanged:: 7.4.0
.. only:: latex
|wgbdcolorslatex|
The color for the admonition frame.
The color for the admonition border.
Default: ``{rgb}{0,0,0}`` (black)
Default: ``{RGB}{148,0,0}`` except for ``error`` which uses ``red``.
.. versionchanged:: 7.4.0
|warningbgcolors|
The background colors for the respective admonitions.
The background color for the admonition background.
Default: ``{rgb}{1,1,1}`` (white)
Default: ``{RGB}{247,247,247}``.
.. versionchanged:: 7.4.0
|warningborders|
The width of the frame. See
The width of the admonition frame. See
:ref:`additionalcss` for keys allowing to configure separately each
border width.
Default: ``1pt``
Default: ``1pt`` except for ``error`` which uses ``1.25pt``.
.. versionchanged:: 7.4.0
``AtStartFootnote``
LaTeX macros inserted at the start of the footnote text at bottom of page,
@ -1160,6 +1135,20 @@ Additional CSS-like ``'sphinxsetup'`` keys
``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of
``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...).
.. versionadded:: 7.4.0
For *all* admonition types, the default configuration does set a background
color (hence the richer ``sphinxheavybox`` is always used).
.. important::
Further, all admonition titles are by default styled using a colored row
and an icon, which are modeled on the current rendering of Sphinx own
docs at https://www.sphinx-doc.org. CSS-named alike keys are added to
set the foreground and background colors for the title as well as the
LaTeX code for the icon.
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
@ -1169,13 +1158,12 @@ inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated.
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
previously described, i.e. either in the ``\definecolor`` syntax or via 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)
div.warning_border-TeXcolor={rgb}{1,0,0},% \definecolor syntax
div.error_background-TeXcolor=red!10,% \colorlet syntax
...<other options>
* A colon in place of the equal sign will break LaTeX.
@ -1212,9 +1200,15 @@ which is then followed by an underscore, then the property name.
: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``)
:dudir:`note`, ``div.note``, ``sphinxnote``
:dudir:`warning`, ``div.warning``, ``sphinxwarning``
further admonition types ``<type>``, ``div.<type>``, ``sphinx<type>``
:rst:dir:`seealso`, ``div.seealso``, ``sphinxseealso``
:rst:dir:`todo`, ``div.todo``, ``sphinxtodo``
.. versionadded:: 7.4.0 Customizability of the :rst:dir:`seealso` and
:rst:dir:`todo` directives.
Here are now these options as well as their common defaults.
Replace below ``<prefix>`` by the actual prefix as explained above. Don't
@ -1229,13 +1223,16 @@ forget the underscore separating the prefix from the property names.
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``.
* ``0.4pt`` for :rst:dir:`code-block`,
* ``0.5pt`` for :dudir:`topic` or contents_ directive,
* ``0.5pt`` for :dudir:`note` and other "light" admonitions,
* ``0.5pt`` for :rst:dir:`seealso` and :rst:dir:`todo` directives,
* ``1pt`` for :dudir:`warning` and other "strong" admonitions except
:dudir:`error` which uses ``1.25pt``.
.. versionchanged:: 7.4.0
Changed defaults for :dudir:`topic` and :dudir:`error`.
- ``<prefix>_box-decoration-break`` can be set to either ``clone`` or
``slice`` and configures the behavior at page breaks.
@ -1248,25 +1245,24 @@ forget the underscore separating the prefix from the property names.
| ``<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:
The defaults:
* ``\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.
* all four ``3pt`` for :rst:dir:`code-block`,
* ``10pt``, ``7pt``, ``12pt``, ``7pt`` for :dudir:`topic` or
contents_ directive,
* ``6pt``, ``7pt``, ``6pt``, ``7pt`` for all "light" admonitions as well
as the :rst:dir:`seealso` and :rst:dir:`todo` directives.
* ``6pt``, ``6.5pt``, ``6pt``, ``6.5pt`` for the strong admonition types
except :dudir:`error` which uses horizontal padding of ``6.25pt``.
.. important::
.. versionchanged:: 7.4.0
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.
All defaults were changed, except for :rst:dir:`code-block`. Admonitions
are set-up so that left (or right) padding plus left (or right)
border-width add up always to ``7.5pt``, so contents align well
vertically across admonition types on same page in PDF. This is only a
property of defaults, not a constraint on possible user choices.
* 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``,
@ -1275,11 +1271,19 @@ forget the underscore separating the prefix from the property names.
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:
The defaults:
* ``\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.
* ``3pt`` for :rst:dir:`code-block` (since 6.0.0) and all corners,
* ``12pt`` for the bottom right corner of :dudir:`topic`, other corners are
straight,
* all radii set to ``5pt`` for :dudir:`note`, :dudir:`hint` and
:dudir:`tip`,
* ``0pt``, i.e. straight corners for all other directives.
.. versionchanged:: 7.4.0
:dudir:`topic` and :dudir:`note`\ -like admonitions acquire (at least one)
rounded corners.
See a remark above about traps with spaces in LaTeX.
- ``<prefix>_box-shadow`` is special in so far as it may be:
@ -1326,6 +1330,36 @@ forget the underscore separating the prefix from the property names.
start of the contents; for admonitions, this happens after the heading which
reproduces the admonition type.
The next keys, for admonitions only, were all three added at 7.4.0. The
default colors are the ones applying to the current HTML rendering of Sphinx
own docs at https://www.sphinx-doc.org.
- ``div.<type>_title-background-TeXcolor``: the background color for the title.
.. important::
The colored title-row is produced as a result of the Sphinx default
definitions for the various ``\sphinxstyle<type>title`` commands, see
:ref:`latex-macros`. Custom redefinitions of these commands are
possible, but to re-use the colors and the icon, it is needed to check in
Sphinx LaTeX source code how the default definitions are done.
- ``div.<type>_title-foreground-TeXcolor``: the color to be used for the icon
(it applies only to the icon, not to the title of the admonition).
- ``div.<type>_title-icon``: the LaTeX code responsible for producing the
icon. For example, the default for :dudir:`note` is
``div.note_title-icon=\faIcon{info-circle}``. This uses a command from the
LaTeX ``fontawesome5`` package, which is loaded automatically if available.
If neither ``fontawesome5`` nor fall-back ``fontawesome`` (for which the
associated command is ``\faicon``, not ``\faIcon``) are found, or if the
``iconpackage`` key of :ref:`'sphinxsetup' <latexsphinxsetup>` is set to
load some other user-chosen package, or no package at all, all the
``title-icons`` default to empty LaTeX code. It is up to user to employ
this interface to inject the icon (or anything else) into the PDF output.
.. note::
- All directives support ``box-decoration-break`` to be set to ``slice``.
@ -1522,16 +1556,30 @@ Macros
``\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``
``\sphinxstylenotetitle``; ``\sphinxdotitlerowwithicon{note}{#1}``
``\sphinxstylehinttitle``; ``\sphinxdotitlerowwithicon{hint}{#1}``
``\sphinxstyleimportanttitle``; *similar*
``\sphinxstyletiptitle``; *similar*
``\sphinxstylewarningtitle``; *similar*
``\sphinxstylecautiontitle``; *similar*
``\sphinxstyleattentiontitle``; *similar*
``\sphinxstyledangertitle``; *similar*
``\sphinxstyleerrortitle``; *similar*
``\sphinxstyleseealsotitle``; *similar*
``\sphinxstyletodotitle``; *similar*
.. note::
To let this table fit on the page width in PDF output we have lied a bit
and the actual definition of ``\sphinxstylenotetitle`` is:
.. code-block:: latex
\newcommand\sphinxstylenotetitle[1]%
{\sphinxdotitlerowwithicon{note}{\sphinxremovefinalcolon{#1}}}
The same remark applies to all other similar commands associated with
admonitions.
.. versionadded:: 1.5
These macros were formerly hard-coded as non customizable ``\texttt``,
@ -1550,23 +1598,16 @@ Macros
.. 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:
if this final colon is to be removed.
.. code-block:: latex
.. versionadded:: 7.4.0 The ``\sphinxdotitlerowwithicon`` LaTeX command,
whose first argument is the admonition type, so that it can recover
the associated colours and icon for the title row, and the second
argument gets typeset after the icon.
\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
}
.. todo:: The fact that we must employ ``\sphinxremovefinalcolon`` is a
legacy artefact from old ill-designed Sphinx LaTeX writer,
which postfixes (still today) the title with a colon automatically.
- ``\sphinxtableofcontents``: A wrapper (defined differently in
:file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard
@ -1746,6 +1787,11 @@ Environments
Colon made part of the mark-up rather than being inserted by the
environment for coherence with how admonitions are handled generally.
- Environment for the :rst:dir:`todo` directive: ``sphinxtodo``.
It takes one argument which will be the localized string ``Todo``
followed with a colon.
.. versionadded:: 7.4.0
- The contents_ directive (with ``:local:`` option) and the
:dudir:`topic` directive are implemented by environment ``sphinxShadowBox``.

8
doc/usage/builders/index.rst
View File

@ -237,6 +237,8 @@ The most common builders are:
* ``texlive-latex-recommended``
* ``texlive-fonts-recommended``
* ``texlive-fonts-extra`` (needed for ``fontawesome5``, see the 7.4.0
change notice below)
* ``tex-gyre`` (if :confval:`latex_engine` left to default)
* ``texlive-latex-extra``
* ``latexmk``
@ -244,6 +246,12 @@ The most common builders are:
.. versionchanged:: 4.0.0
TeX Gyre fonts now required for ``'pdflatex'`` engine (default).
.. versionchanged:: 7.4.0
LaTeX package ``xcolor`` is now required (it is part of Ubuntu
``texlive-latex-recommended`` anyhow). The LaTeX package
``fontawesome5`` is recommended. See the :ref:`'sphinxsetup'
<latexsphinxsetup>` ``iconpackage`` key for more.
Additional packages are needed in some circumstances:
* ``texlive-lang-cyrillic`` for Cyrillic (and also then

4
sphinx/ext/todo.py
View File

@ -209,7 +209,7 @@ def depart_todo_node(self: HTML5Translator, node: todo_node) -> None:
def latex_visit_todo_node(self: LaTeXTranslator, node: todo_node) -> None:
if self.config.todo_include_todos:
self.body.append('\n\\begin{sphinxadmonition}{note}{')
self.body.append('\n\\begin{sphinxtodo}{')
self.body.append(self.hypertarget_to(node))
title_node = cast(nodes.title, node[0])
@ -221,7 +221,7 @@ def latex_visit_todo_node(self: LaTeXTranslator, node: todo_node) -> None:
def latex_depart_todo_node(self: LaTeXTranslator, node: todo_node) -> None:
self.body.append('\\end{sphinxadmonition}\n')
self.body.append('\\end{sphinxtodo}\n')
def setup(app: Sphinx) -> ExtensionMetadata:

789
sphinx/texinputs/sphinx.sty
View File

File diff suppressed because it is too large Load Diff

273
sphinx/texinputs/sphinxlatexadmonitions.sty
View File

@ -1,25 +1,51 @@
%% NOTICES AND ADMONITIONS
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexadmonitions.sty}[2023/03/19 admonitions]
\ProvidesFile{sphinxlatexadmonitions.sty}[2024/07/01 v7.4.0 admonitions]
% Provides support for this output mark-up from Sphinx latex writer:
%
% - sphinxseealso environment added at 6.1.0
% - sphinxseealso environment added at 6.1.0.
%
% At 7.4.0 it too now uses sphinxheavybox, and has the same associated
% sphinxsetup CSS keys as admonitions do.
%
% - sphinxtodo environment added at 7.4.0.
%
% - sphinxadmonition (environment)
% This is a dispatch supporting
% This is a dispatch which formerly configured
%
% - note, hint, important, tip (via sphinxlightbox)
% (also optionally via sphinxheavybox since 6.2.0)
% - warning, caution, attention, danger, error (via sphinxheavybox)
% - note, hint, important, tip to use sphinxlightbox (or optionally
% sphinxheavybox since 6.2.0),
% - warning, caution, attention, danger, error to use sphinxheavybox.
%
% Each sphinx<notice name> environment can be redefined by user.
% The defaults are customizable via various colour and dimension
% settings, cf sphinx docs (latex customization).
% At 7.4.0 all admonitions use sphinxheavybox.
%
% - All environments sphinxnote, sphinxwarning, etc... can be redefined as
% will by user. Thay have a single parameter #1 which is the title.
%
% - The default sphinxnote, sphinxwarning, etc... use associated
% one-argument macros \sphinxstylenotetitle, \sphinxstylewarningtitle, etc
% which can be redefined. Their default is to use \sphinxdotitlerowwithicon
% to typeset the title in a coloured header row at top of the
% admonition. (new with 7.4.0)
%
% The sphinxlightbox environment is kept for backward compatiblity, for user
% custom code which used it via custom definitions done in preamble or via
% raw latex directive.
% MEMO: here is for example how sphinxnote was formerly defined:
% (where #1 is the localized string Note, followed with a colon)
% \newenvironment{sphinxnote}[1]
% {\begin{sphinxlightbox}\sphinxstrong{#1} }
% {\end{sphinxlightbox}}
% Use this if you want to revert the 7.4.0 switch to usage of sphinxheavybox.
% (the 7.4.0 redefined \sphinxstylenotetitle will not work in sphinxlightbox,
% so \sphinxstrong{#1}<space> which was its former default is used above).
%
% Requires:
\RequirePackage{sphinxpackageboxes}
% 7.4.0 removes unneeded \spx@boxes@border
\RequirePackage{framed}% used by sphinxheavybox
%
% Dependencies (they do not need to be defined at time of loading):
@ -29,25 +55,17 @@
% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
%
% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
%
% - \sphinxstylenotetitle, ..., \sphinxstylewarningtitle, etc... which are used by
% default in the corresponding sphinx<notice> environments to replace at 6.2.0
% formerly hard-coded \sphinxstrong{#1}<space>
% Their definitions are in sphinxlatexstyletext.sty.
% Provides: (also in sphinxlatexliterals.sty)
% Only needed here by legacy (deprecated) sphinxlightbox environment.
\providecommand*\sphinxvspacefixafterfrenchlists{%
\ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
}
% Some are quite plain
\newenvironment{sphinxseealso}[1]{\sphinxstyleseealsotitle{#1}}{}
% This \dimen register is a legacy relic from Sphinx 1.5 which is used now
% only for sphinxlightbox. It is set in the sphinxadmonition environment.
\newdimen\spx@notice@border
% sphinxlightbox is now also a legacy relic, not used by Sphinx anymore
\newenvironment{sphinxlightbox}{%
\par
\noindent{\color{spx@notice@bordercolor}%
@ -65,55 +83,28 @@
{\linewidth}{\spx@notice@border}}\hss}\allowbreak
}% end of sphinxlightbox environment definition
% note/hint/important/tip notices
% Since 1.5 these environments are named individually sphinxnote, sphinxhint,
% etc... to allow user to redefine them entirely.
%
% Since 1.5 these environments are named individually to allow user to
% redefine them entirely.
%
% The Sphinx definitions were done like this, prior to 6.2.0:
% The Sphinx definitions for note/hint/important/tip notices were done like
% this, prior to 6.2.0:
%
% \newenvironment{sphinxhint}[1]
% {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
%
% The more complex definition below will branch to sphinxheavybox if a certain
% boolean associated to the notice type is true. This boolean is set to true
% whenever a CSS-named alike options for the notice type has been used in
% sphinxsetup. The old coding as above would still work, with the new options
% being then simply ignored. A user redefinition will probably either use
% directly sphinxlightbox or sphinxheavybox or something else, with no need to
% test the boolean.
% Then from 6.2.0 to 7.4.0 (exclusive) a more complex definition decided
% to use either sphinxlightbox or sphinxheavybox according to whether
% some CSS-like options had been used, for example for a background color.
%
% 6.2.0 also adds one layer of mark-up via \sphinxnotetitle etc..., because
% the former \sphinxstrong{#1}<space> used a too generic \sphinxstrong. But
% perhaps the #1 should be passed over to sphinx{light,heavy}box as parameter.
% Unfortunately replacing these environments with one-parameter environments
% would be potentially a breaking change. Anyway, sphinxpackageboxes.sty does not
% provide a "titled" box; the caption of code-blocks is handled by extra
% code in sphinxVerbatim.
\newenvironment{sphinxnote}[1]
{\edef\spx@env{sphinx\ifspx@opt@heavynote heavy\else light\fi box}%
\expandafter\begin\expandafter{\spx@env}\sphinxstylenotetitle{#1}}
{\expandafter\end\expandafter{\spx@env}}
\newenvironment{sphinxhint}[1]
{\edef\spx@env{sphinx\ifspx@opt@heavyhint heavy\else light\fi box}%
\expandafter\begin\expandafter{\spx@env}\sphinxstylehinttitle{#1}}
{\expandafter\end\expandafter{\spx@env}}
\newenvironment{sphinximportant}[1]
{\edef\spx@env{sphinx\ifspx@opt@heavyimportant heavy\else light\fi box}%
\expandafter\begin\expandafter{\spx@env}\sphinxstyleimportanttitle{#1}}
{\expandafter\end\expandafter{\spx@env}}
\newenvironment{sphinxtip}[1]
{\edef\spx@env{sphinx\ifspx@opt@heavytip heavy\else light\fi box}%
\expandafter\begin\expandafter{\spx@env}\sphinxstyletiptitle{#1}}
{\expandafter\end\expandafter{\spx@env}}
% warning/caution/attention/danger/error get more distinction
% 6.2.0 also added one layer of mark-up via \sphinxnotetitle etc..., because
% the former \sphinxstrong{#1}<space> used a too generic \sphinxstrong.
%
% At 7.4.0, sphinxheavybox environment is default for all types of notices
% and also for the seealso and todo directives.
%
% Code adapted from framed.sty's "snugshade" environment.
% Nesting works (inner frames do not allow page breaks).
\newenvironment{sphinxheavybox}{\par
% 6.2.0 allows to not have to distinguish here between warning type notices
% which always use sphinxheavybox or note type notices which might use it.
% (MEMO: it is not a problem here if there is no sphinx<type>ShadowColor,
% as it used only if set)
\spx@boxes@fcolorbox@setup{\spx@noticetype}%
@ -205,16 +196,80 @@
% Example:
% \renewcommand{\sphinxwarningtitle}[1]{\textbf{#1}\par\smallskip
% {\color{sphinxwarningBorderColor}\hrule height1pt}\smallskip}
%
% - Since 7.4.0, all types of notices use sphinxheavybox and the default
% for \sphinxstyle<type>title is mapped to using \sphinxdotitlerowwithicon{<type>}
%
% MEMO: except for the generic admonition directive (which uses "note" type)
% the argument #1 in these environments has a postfixed colon originating
% in Sphinx LaTeX writer legacy code. The
% \sphinxremovefinalcolon utility in sphinxlatexstyletext.sty can be used as
% \sphinxremovefinalcolon{#1} from inside the definitions of
% \sphinxstylenotetitle et al. commands.
% Important: even prior to 5.1.0 it was not really possible to use directly
% sphinxheavybox if not triggered from sphinxadmonition, because some
% parameters were defined in sphinxadmonition. This meant that the
% sphinxwarning, sphinxcaution etc... environments (defined below) could not
% be used directly in a document, they had to be triggered via
% sphinxadmonition. The sole data since 5.1.0 needed by sphinxheavybox is the
% type of the notice which sphinxadmonition stores into \spx@noticetype.
%
% In order to facilitate recycling or imitation of the sphinx<type>
% environments, 7.4.0 inserts an extra \def\spx@noticetype{<type>} in their
% definitions, so that they can be used independently of sphinxadmonition
% dispatcher.
%
% MEMO: direct usage of these environments does not execute the div.<type>_TeXextras
% and div.<type>_TexColor code, there are only done from the sphinxadmonition wrapper.
\newenvironment{sphinxnote}[1]
{\def\spx@noticetype{note}\begin{sphinxheavybox}\sphinxstylenotetitle{#1}}
{\end{sphinxheavybox}}
\newenvironment{sphinxhint}[1]
{\def\spx@noticetype{hint}\begin{sphinxheavybox}\sphinxstylehinttitle{#1}}
{\end{sphinxheavybox}}
\newenvironment{sphinxtip}[1]
{\def\spx@noticetype{tip}\begin{sphinxheavybox}\sphinxstyletiptitle{#1}}
{\end{sphinxheavybox}}
\newenvironment{sphinximportant}[1]
{\def\spx@noticetype{important}\begin{sphinxheavybox}\sphinxstyleimportanttitle{#1}}
{\end{sphinxheavybox}}
\newenvironment{sphinxwarning}[1]
{\begin{sphinxheavybox}\sphinxstylewarningtitle{#1}}{\end{sphinxheavybox}}
{\def\spx@noticetype{warning}\begin{sphinxheavybox}\sphinxstylewarningtitle{#1}}
{\end{sphinxheavybox}}
\newenvironment{sphinxcaution}[1]
{\begin{sphinxheavybox}\sphinxstylecautiontitle{#1}}{\end{sphinxheavybox}}
{\def\spx@noticetype{caution}\begin{sphinxheavybox}\sphinxstylecautiontitle{#1}}
{\end{sphinxheavybox}}
\newenvironment{sphinxattention}[1]
{\begin{sphinxheavybox}\sphinxstyleattentiontitle{#1}}{\end{sphinxheavybox}}
{\def\spx@noticetype{attention}\begin{sphinxheavybox}\sphinxstyleattentiontitle{#1}}
{\end{sphinxheavybox}}
\newenvironment{sphinxdanger}[1]
{\begin{sphinxheavybox}\sphinxstyledangertitle{#1}}{\end{sphinxheavybox}}
{\def\spx@noticetype{danger}\begin{sphinxheavybox}\sphinxstyledangertitle{#1}}
{\end{sphinxheavybox}}
\newenvironment{sphinxerror}[1]
{\begin{sphinxheavybox}\sphinxstyleerrortitle{#1}}{\end{sphinxheavybox}}
{\def\spx@noticetype{error}\begin{sphinxheavybox}\sphinxstyleerrortitle{#1}}
{\end{sphinxheavybox}}
% The "see also" was quite plain until 7.4.0 as it simply did
% \newenvironment{sphinxseealso}[1]{\sphinxstyleseealsotitle{#1}}{}
% Here we need to manually insert execution of div.seealso_TeX{color,extras} values
\newenvironment{sphinxseealso}[1]
{\def\spx@noticetype{seealso}%
\begin{sphinxheavybox}\sphinxstyleseealsotitle{#1}%
\ifspx@seealso@withtextcolor\color{sphinxseealsoTextColor}\fi
\spx@seealso@TeXextras
}
{\end{sphinxheavybox}}
% There was no sphinxtodo environment until 7.4.0 because sphinx.ext.todo
% generated \begin{sphinxadmonition}{note}{Todo:} mark-up.
\newcounter{sphinxtodo}% to provide targets from todolist directive output
\newenvironment{sphinxtodo}[1]
{\refstepcounter{sphinxtodo}\def\spx@noticetype{todo}%
\begin{sphinxheavybox}\sphinxstyletodotitle{#1}%
\ifspx@todo@withtextcolor\color{sphinxtodoTextColor}\fi
\spx@todo@TeXextras
}
{\end{sphinxheavybox}}
% the main dispatch for all types of notices
\newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
@ -227,16 +282,104 @@
% the more bulky "sphinx\spx@noticetype BgColor".
\sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
\sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
\spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax
% At 7.4.0 there are no \spx@<type>@boder macros anymore only top, left,
% bottom, right. For this legacy \spx@notice@border only needed by
% sphinxlightbox (which is not used by own Sphinx environments anymore)
% we thus use here @top
\spx@notice@border \dimexpr\csname spx@#1@border@top\endcsname\relax
% trigger the sphinx<type> environment, #2=heading is passed as argument
\begin{sphinx#1}{#2}%
% MEMO: the heading #2 will be typeset before the next lines are executed
% 6.2.0 support of div.<type>_TeX{color,extras} options
\csname ifspx@\spx@noticetype @withtextcolor\endcsname
\color{sphinx\spx@noticetype TextColor}%
\fi
% Other code to be executed at start of contents (after title)
\csname spx@\spx@noticetype @TeXextras\endcsname
}
% workaround some LaTeX "feature" of \end command (can't use "sphinx#1" here)
% workaround some LaTeX "feature" of \end command (i.e. can't use "sphinx#1" here)
{\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
\newcommand\sphinxtitlerowtoppadding{5pt}
\newcommand\sphinxtitlerowbottompadding{3pt}
\newcommand\sphinxtitlerowaftericonspacecmd{\hskip0.5em\relax}
\newcommand\sphinxdotitlerowwithicon[2]{% #1=type, #2=heading (without final colon)
\begingroup
\kern-\spx@boxes@padding@top
\parskip\z@skip % the \parskip business is a workaround to a vertical
% glue issue showing in LaTeX earlier than 2023-06-01
\noindent
\kern-\spx@boxes@padding@left % must have been configured by a prior
% \spx@boxes@fcolorbox@setup{<type>}
% inherit settings from the enclosing box and modify what is needed
\spx@boxes@border@top =\z@
\spx@boxes@border@right =\z@
\spx@boxes@border@bottom =\z@
\spx@boxes@border@left =\z@
\spx@boxes@radius@bottomright@x=\z@
\spx@boxes@radius@bottomright@y=\z@
\spx@boxes@radius@bottomleft@x=\z@
\spx@boxes@radius@bottomleft@x=\z@
\spx@boxes@padding@top =\sphinxtitlerowtoppadding\relax
\spx@boxes@padding@bottom=\sphinxtitlerowbottompadding\relax
\spx@boxes@withshadowfalse
\sphinxcolorlet{spx@boxes@backgroundcolor}{sphinx#1TtlBgColor}%
\spx@boxes@fcolorbox{%
\makebox[\linewidth][l]{%
\textcolor{sphinx#1TtlFgColor}{%
\@nameuse{sphinx#1TtlIcon}%
% This macro is located here and not after the closing brace
% for reasons of fall-back \spx@faIcon definition in sphinx.sty
% in case fontawesome5 package not found.
\sphinxtitlerowaftericonspacecmd
}%
\sphinxstrong{#2}%
\strut}%
}%
\kern-\spx@boxes@padding@right
\par
\endgroup
\vskip-\parskip
\kern\spx@boxes@padding@top
}
% #1 holds the localized name of the notice, postfixed with a colon.
% \sphinxremovefinalcolon{#1} will typeset #1 without the colon.
% Legacy definitions (done in sphinxlatexstyletext.sty) were all using
% a boring plain \sphinxstrong{#1}, now we use a coloured title row.
\newcommand\sphinxstylenotetitle [1]{\sphinxdotitlerowwithicon{note}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylehinttitle [1]{\sphinxdotitlerowwithicon{hint}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerowwithicon{important}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyletiptitle [1]{\sphinxdotitlerowwithicon{tip}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylewarningtitle [1]{\sphinxdotitlerowwithicon{warning}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstylecautiontitle [1]{\sphinxdotitlerowwithicon{caution}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerowwithicon{attention}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyledangertitle [1]{\sphinxdotitlerowwithicon{danger}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleerrortitle [1]{\sphinxdotitlerowwithicon{error}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyleseealsotitle [1]{\sphinxdotitlerowwithicon{seealso}{\sphinxremovefinalcolon{#1}}}
\newcommand\sphinxstyletodotitle [1]{\sphinxdotitlerowwithicon{todo}{\sphinxremovefinalcolon{#1}}}
%
% A utility to remove a final colon. Removing last token is not easy in
% LaTeX, and there are additional complications:
% - some languages will make the : "active" in document body,
% - the generic admonition ends up using "note", so for \sphinxnotetitle to
% use it safely, the utility has to allow an input not having any final colon.
% - a bit far-fetched but maybe there is more than one colon inside the input
% (possible from a generic admonition title).
% Hence the scary code.
\newcommand\sphinxremovefinalcolon[1]{% #1 is the "active" : TeX token
% Prior to 7.4.0 this was defined with \protected\def but we do not
% see what usefulness this could have.
\renewcommand\sphinxremovefinalcolon[1]{%
% complications due to : possibly "active"
\begingroup\ifnum\catcode`:=\active
\def\x####1#1\relax{####1}%
\else\def\x####1:\relax{####1}\fi
\expandafter\endgroup\x##1\relax
% trick to let \x work also if input ##1 has no ending colon
\@gobblefour#1\relax:\relax\relax\relax
}%
}% end of wrapper to inject active :
\begingroup\catcode`:\active\expandafter\endgroup\sphinxremovefinalcolon:
\endinput

25
sphinx/texinputs/sphinxlatexliterals.sty
View File

@ -1,7 +1,7 @@
%% LITERAL BLOCKS
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexliterals.sty}[2023/04/01 code-blocks and parsed literals]
\ProvidesFile{sphinxlatexliterals.sty}[2024/07/01 v7.4.0 code-blocks and parsed literals]
% Provides support for this output mark-up from Sphinx latex writer:
%
@ -34,6 +34,7 @@
% - needspace
% - sphinxpackageboxes
\RequirePackage{sphinxpackageboxes}
% 7.4.0 removes unneeded usage of \spx@boxes@border
% also in sphinxlatexadmonitions.sty:
% This is a workaround to a "feature" of French lists, when literal block
@ -224,7 +225,6 @@
\spx@boxes@border@right\z@
\spx@boxes@border@bottom\z@
\spx@boxes@border@left\z@
\spx@boxes@border\z@
% MEMO: rounded corners still make sense in presence of a background
% color, so we do not force the fcolorbox@rectangle here
\fi
@ -670,25 +670,18 @@
\def\sphinxVerbatim@Before
{\sphinxVerbatim@Title\nointerlineskip
\kern\dimexpr-\dp\strutbox+\sphinxbelowcaptionspace
% if no frame (code-blocks inside table cells), remove
% the top padding (better visually)
\ifspx@opt@verbatimwithframe\else
% but we must now check if there is a background color
% MEMO: "fcolorbox@setup" will have been done by time of use
\ifspx@boxes@withbackgroundcolor\else-\spx@boxes@padding@top\fi
\fi
% MEMO: prior to 7.4.0 a test was done for presence or
% not of a frame and if not top padding was removed if
% no background color. A background color is now always
% assumed, so this got removed.
% caption package adds \abovecaptionskip vspace, remove it
\spx@ifcaptionpackage{-\abovecaptionskip}{}\relax}%
\spx@ifcaptionpackage{-\abovecaptionskip}{}\relax}%
\else
\vskip\sphinxverbatimsmallskipamount
\def\sphinxVerbatim@After
{\nointerlineskip\kern\dimexpr\dp\strutbox
\ifspx@opt@verbatimwithframe\else
% but we must now check if there is a background color
% MEMO: "fcolorbox@setup" will have been done by time of use
\ifspx@boxes@withbackgroundcolor\else-\spx@boxes@padding@bottom\fi
\fi
\spx@ifcaptionpackage{-\abovecaptionskip}{}\relax
% MEMO: 7.4.0 removes here too an optional removal of bottom padding
\spx@ifcaptionpackage{-\abovecaptionskip}{}\relax
\sphinxVerbatim@Title}%
\fi
\def\@captype{literalblock}%

42
sphinx/texinputs/sphinxlatexstyletext.sty
View File

@ -1,45 +1,11 @@
%% TEXT STYLING
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexstyletext.sty}[2023/07/23 text styling]
\ProvidesFile{sphinxlatexstyletext.sty}[2024/07/01 v7.4.0 text styling]
% Basically everything here consists of macros which are part of the latex
% markup produced by the Sphinx latex writer
% But those arise rather from the default definitions of the respective
% latex environments done in sphinxlatexadmonitions.sty
\def\sphinxstylenotetitle #1{\sphinxstrong{#1} }
\let\sphinxstylehinttitle \sphinxstylenotetitle % #1 holds the localized notice name
\let\sphinxstyleimportanttitle\sphinxstylenotetitle % followed by a colon
\let\sphinxstyletiptitle \sphinxstylenotetitle
\let\sphinxstylewarningtitle \sphinxstylenotetitle
\let\sphinxstylecautiontitle \sphinxstylenotetitle
\let\sphinxstyleattentiontitle\sphinxstylenotetitle
\let\sphinxstyledangertitle \sphinxstylenotetitle
\let\sphinxstyleerrortitle \sphinxstylenotetitle
\def\sphinxstyleseealsotitle#1{\sphinxstrong{#1}\par\nopagebreak}
%
% A utility to remove a final colon. Removing last token is not easy in
% LaTeX, and there are additional complications:
% - some languages will make the : "active" in document body,
% - the generic admonition ends up using "note", so for \sphinxnotetitle to
% use it safely, the utility has to allow an input not having any final colon.
% - a bit far-fetched but maybe there is more than one colon inside the input
% (possible from a generic admonition title).
% Hence the scary code.
\def\sphinxremovefinalcolon#1{% #1 is the "active" : TeX token
\protected\def\sphinxremovefinalcolon ##1{%
% complications due to : possibly "active"
\begingroup\ifnum\catcode`:=\active
\def\x####1#1\relax{####1}%
\else\def\x####1:\relax{####1}\fi
\expandafter\endgroup\x##1\relax
% trick to let \x work also if input ##1 has no ending colon
\@gobblefour#1\relax:\relax\relax\relax
}%
}% end of wrapper to inject active :
\begingroup\catcode`:\active\expandafter\endgroup\sphinxremovefinalcolon:
% See doc/latex.rst for an example.
% 7.4.0 has moved all that is related to admonitions to sphinxlatexadmonitions.sty
% Most everything left here consists of macros which are part of the latex markup
% produced by the Sphinx LaTeX writer.
% Some custom font markup commands.
\protected\def\sphinxstrong#1{\textbf{#1}}

20
sphinx/texinputs/sphinxlatextables.sty
View File

@ -1,7 +1,7 @@
%% TABLES (WITH SUPPORT FOR MERGED CELLS OF GENERAL CONTENTS)
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatextables.sty}[2022/08/15 tables]%
\ProvidesFile{sphinxlatextables.sty}[2024/07/01 v7.4.0 tables]%
% Provides support for this output mark-up from Sphinx latex writer
% and table templates:
@ -42,6 +42,11 @@
% - \sphinxthistablewithnocolorrowsstyle
% - \sphinxthistablewithvlinesstyle
% - \sphinxthistablewithnovlinesstyle
%
% Also provides user command (see docs)
% - \sphixncolorblend
% (Sphinx 7.4.0 now requires xcolor, so \sphinxcolorblend does not check
% its availability anymore)
%
% Executes \RequirePackage for:
%
@ -513,19 +518,6 @@
\fi
}
\def\sphinxcolorblend#1{\gdef\spx@colorblendparam{{#1}}\spx@table@hackCT@colorblend}
% Either xcolor.sty exists on user system and has been loaded by sphinx.sty,
% or it does not exist, so we can use \@ifpackageloaded without delaying.
\@ifpackageloaded{xcolor}%
{}%
{\def\sphinxcolorblend#1{%
\PackageWarning{sphinx}{This table uses \string\sphinxcolorblend\space
but xcolor is not in\MessageBreak
the TeX/LaTeX installation, the command will be\MessageBreak
ignored in this and the next tables}%
\global\let\sphinxcolorblend\@gobble
\sphinxbuildwarning{colorblend}%
}%
}
%%%%%%%%%%%%%%%%%%

57
sphinx/texinputs/sphinxpackageboxes.sty
View File

@ -1,7 +1,12 @@
%% COLOURED BOXES
%
% change this info string if making any custom modification
\ProvidesPackage{sphinxpackageboxes}[2023/03/19 v6.2.0 advanced colored boxes]
\ProvidesPackage{sphinxpackageboxes}[2024/07/01 v7.4.0 advanced colored boxes]
% 7.4.0 removes usage of some booleans "...withbackgroundcolor" and
% "...withbordercolor" as well as \spx@boxes@border dimen which was
% actually really needed nowhere. This was done in sync with changes in
% sphinx.sty, sphinxlatexadmonitions.sty and sphinxlatexliterals.sty.
%
% Optionally executes \RequirePackage for:
%
% - pict2e. Ideally we would like to use the v0.4a 2020/08/16 release of this
@ -78,15 +83,13 @@
%%%%%%%%%%%%%%%%
% Internal registers, conditionals, colors to be configured by each caller
% via a preliminary "setup" call
%
\newif\ifspx@boxes@withshadow
\newif\ifspx@boxes@insetshadow
\newif\ifspx@boxes@withbackgroundcolor
%%% \newif\ifspx@boxes@withbackgroundcolor % removed at 7.4.0
\newif\ifspx@boxes@withshadowcolor
\newif\ifspx@boxes@withbordercolor
%%% \newif\ifspx@boxes@withbordercolor % removed at 7.4.0
\newif\ifspx@boxes@shadowinbbox
%
\newdimen\spx@boxes@border
\newdimen\spx@boxes@border@top
\newdimen\spx@boxes@border@right
\newdimen\spx@boxes@border@bottom
@ -150,7 +153,6 @@
\spx@boxes@border@right \dimexpr\@nameuse{spx@#1@border@right}\relax
\spx@boxes@border@bottom\dimexpr\@nameuse{spx@#1@border@bottom}\relax
\spx@boxes@border@left \dimexpr\@nameuse{spx@#1@border@left}\relax
\spx@boxes@border \dimexpr\@nameuse{spx@#1@border}\relax
%
\spx@boxes@padding@top \dimexpr\@nameuse{spx@#1@padding@top}\relax
\spx@boxes@padding@right \dimexpr\@nameuse{spx@#1@padding@right}\relax
@ -200,19 +202,9 @@
\spx@boxes@insetshadowfalse
\fi
%
\@nameuse{ifspx@#1@withbordercolor}%
\spx@boxes@withbordercolortrue
\sphinxcolorlet{spx@boxes@bordercolor}{sphinx#1BorderColor}%
\else
\spx@boxes@withbordercolorfalse
\fi
%
\@nameuse{ifspx@#1@withbackgroundcolor}%
\spx@boxes@withbackgroundcolortrue
\sphinxcolorlet{spx@boxes@backgroundcolor}{sphinx#1BgColor}%
\else
\spx@boxes@withbackgroundcolorfalse
\fi
%
\@nameuse{ifspx@#1@withshadowcolor}%
\spx@boxes@withshadowcolortrue
@ -447,14 +439,12 @@
\fi
% BACKGROUND
% draw background and move back to reference point
\ifspx@boxes@withbackgroundcolor
{\color{spx@boxes@backgroundcolor}%
\vrule\@height\ht\spx@tempboxa
\@depth\dp\spx@tempboxa
\@width\wd\spx@tempboxa
\kern-\wd\spx@tempboxa
}%
\fi
% BOX SHADOW
% draw shadow and move back to reference point
\ifspx@boxes@withshadow
@ -494,13 +484,8 @@
}% end of \vbox
\fi % end of shadow drawing, and we are back to horizontal reference point
% BOX BORDER
\vbox{\ifspx@boxes@withbordercolor
\color{spx@boxes@bordercolor}%
\else
% 6.2.0: guard against a \color command in contents whose effect
% could leak to border at a pagebreak
\normalcolor
\fi
% 7.4.0 requires a set border color
\vbox{\color{spx@boxes@bordercolor}%
\hrule\@height\spx@boxes@border@top
\kern-\spx@boxes@border@top
\setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa
@ -540,14 +525,13 @@
\def\spx@boxes@fcolorbox@insetshadow{%
% BACKGROUND
% draw background and move back to reference point
\ifspx@boxes@withbackgroundcolor
% 7.4.0 always assumes a background color
{\color{spx@boxes@backgroundcolor}%
\vrule\@height\ht\spx@tempboxa
\@depth\dp\spx@tempboxa
\@width\wd\spx@tempboxa
\kern-\wd\spx@tempboxa
}%
\fi
% BOX SHADOW
% draw shadow and move back to reference point
\ifspx@boxes@withshadow
@ -589,13 +573,8 @@
}% end of \hbox, attention its depth is only |yoffset| if yoffset<0
\fi % end of inset shadow drawing, and we are back to horizontal reference point
% BOX BORDER
\vbox{\ifspx@boxes@withbordercolor
\color{spx@boxes@bordercolor}%
\else
% 6.2.0: guard against a \color command in contents whose effect
% could leak to border at a pagebreak
\normalcolor
\fi
% 7.4.0 requires a set border color
\vbox{\color{spx@boxes@bordercolor}%
\hrule\@height\spx@boxes@border@top
\kern-\spx@boxes@border@top
\setbox\spx@tempboxb\hb@xt@\wd\spx@tempboxa
@ -807,17 +786,11 @@
\fi
\spx@boxes@border@defpath% must be redone after each \fillpath! (even if
% was in a \put)
\ifspx@boxes@withbordercolor
% 7.4.0 requires a set border color
\color{spx@boxes@bordercolor}%
\else
\normalcolor
\fi
\fillpath
\ifspx@boxes@withbackgroundcolor
% and backgroundcolor command
\color{spx@boxes@backgroundcolor}%
\else
\color{white}%
\fi
\edef\spx@width{\number\dimexpr\spx@width-\spx@boxes@border@left
-\spx@boxes@border@right sp}%
\edef\spx@height{\number\dimexpr\spx@height-\spx@boxes@border@top