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: add support for styling `note (hint, ...) similarly as warning ( danger`, ...) (#11234)

Browse Source
This commit is contained in:
Jean-François B 2023-03-12 11:28:36 +01:00 committed by GitHub
parent 7c062b828e
commit 212ed5b940
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 496 additions and 344 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
CHANGES
View File

@ -20,7 +20,11 @@ Features added
* LaTeX: a command ``\sphinxbox`` for styling text elements with a (possibly
rounded) box, optional background color and shadow, has been added.
See :ref:`sphinxbox`. (refs #11224)
See :ref:`sphinxbox`. (refs: #11224)
* LaTeX: :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip` can
now each be styled as the other admonitions, i.e. possibly with a background
color, individual border widths and paddings, possibly rounded corners, and
optional shadow. See :ref:`additionalcss`. (refs: #11234)
Bugs fixed
----------

515
doc/latex.rst
View File

@ -8,26 +8,34 @@ LaTeX customization
\begingroup
\sphinxsetup{%
TitleColor={named}{DarkGoldenrod},
pre_border-width=2pt,
pre_padding=5pt,
pre_border-radius=5pt,
pre_background-TeXcolor={named}{OldLace},
pre_border-TeXcolor={named}{Gold},
div.warning_border-width=3pt,
div.warning_padding=6pt,
div.warning_padding-right=18pt,
div.warning_padding-bottom=18pt,
div.warning_border-TeXcolor={named}{DarkCyan},
div.warning_background-TeXcolor={named}{LightCyan},
div.warning_box-shadow=-12pt -12pt inset,
div.warning_box-shadow-TeXcolor={named}{Cyan},
attentionborder=3pt,
attentionBorderColor={named}{Crimson},
attentionBgColor={named}{FloralWhite},
noteborder=2pt,
noteBorderColor={named}{Olive},
hintBorderColor={named}{LightCoral}}
TitleColor={named}{DarkGoldenrod},
pre_border-width=2pt,
pre_padding=5pt,
pre_border-radius=5pt,
pre_background-TeXcolor={named}{OldLace},
pre_border-TeXcolor=Gold,
pre_border-TeXcolor=Gold!90,
%
div.warning_border-width=3pt,
div.warning_padding=6pt,
div.warning_padding-right=18pt,
div.warning_padding-bottom=18pt,
div.warning_border-TeXcolor=DarkCyan,
div.warning_background-TeXcolor=LightCyan,
div.warning_box-shadow=-12pt -12pt inset,
div.warning_box-shadow-TeXcolor=Cyan,
%
attentionborder=3pt,
attentionBorderColor=Crimson,
attentionBgColor=FloralWhite,
%
noteborder=1pt,
noteBorderColor=Olive,
noteBgColor=Olive!10,
div.note_border-left-width=0pt,
div.note_border-right-width=0pt,
hintBorderColor=LightCoral,
}
\relax
Unlike :ref:`the HTML builders <html-themes>`, the ``latex`` builder does not
@ -592,53 +600,80 @@ The colors used in the above are provided by the ``svgnames`` option of the
It is possible to insert further uses of the ``\sphinxsetup`` LaTeX macro
directly into the body of the document, via the help of the ``raw``
directive. This chapter is styled in the PDF output using the following at the
start of the chapter (which uses keys described later in :ref:`additionalcss`)::
start of the chapter (which uses keys described later in
:ref:`additionalcss`):
.. raw:: latex
.. code-block:: latex
\begingroup
\sphinxsetup{%
.. raw:: latex
\begingroup
\sphinxsetup{%
TitleColor={named}{DarkGoldenrod},
% pre_border-width is 5.1.0 alias for verbatimborder
pre_border-width=2pt,
% pre_padding is 5.1.0 alias for verbatimsep
% pre_padding is a 5.1.0 alias for verbatimsep
pre_padding=5pt,
% rounded boxes are new at 5.1.0
% Rounded boxes are new at 5.1.0
pre_border-radius=5pt,
% TeXcolor means syntax must be as for LaTeX \definecolor
% TeXcolor reminds that syntax must be as for LaTeX \definecolor
pre_background-TeXcolor={named}{OldLace},
pre_border-TeXcolor={named}{Gold},
% ... 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,
%
% 5.1.0 alias for warningborder
% 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,
div.warning_border-TeXcolor={named}{DarkCyan},
div.warning_background-TeXcolor={named}{LightCyan},
% 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={named}{Cyan},
div.warning_box-shadow-TeXcolor=Cyan,
%
% 5.1.0 new name would be div.attention_border-width
% The 5.1.0 new name would be div.attention_border-width
attentionborder=3pt,
% same as div.attention_border-TeXcolor
attentionBorderColor={named}{Crimson},
% same as div.attention_background-TeXcolor
attentionBgColor={named}{FloralWhite},
% 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,
%
% no CSS-like names yet at 5.1.0 for note-type admonitions
noteborder=2pt,
noteBorderColor={named}{Olive},
hintBorderColor={named}{LightCoral}%
}
% 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,
% (but using rounded corners would cause the widths of all sides to
% be reset equal to the noteborder setting)
%
% As long as only border width and border color are set, *and* using
% for this the old interface, the rendering will be the "light" one
hintBorderColor=LightCoral,
% but if we had used div.hint_border-TeXcolor or *any* CSS-named
% option we would have triggered the more complex "heavybox" code.
}
And this is placed at the end of the chapter source to end the scope of
the configuration::
the configuration:
.. raw:: latex
.. code-block:: latex
\endgroup
.. raw:: latex
\endgroup
LaTeX syntax for boolean keys requires *lowercase* ``true`` or ``false``
e.g ``'sphinxsetup': "verbatimwrapslines=false"``. If setting the
@ -696,7 +731,7 @@ Do not use quotes to enclose values, whether numerical or strings.
``verbatimwithframe``
Boolean to specify if :rst:dir:`code-block`\ s and literal includes are
framed. Setting it to ``false`` does not deactivate use of package
"framed", because it is still in use for the optional background colour.
"framed", because it is still in use for the optional background color.
Default: ``true``.
@ -792,7 +827,7 @@ Do not use quotes to enclose values, whether numerical or strings.
Default: ``true``
.. versionadded:: 1.5.2
set this option value to ``false`` to recover former behaviour.
set this option value to ``false`` to recover former behavior.
``inlineliteralwraps``
Boolean to specify if line breaks are allowed inside inline literals: but
@ -804,7 +839,7 @@ Do not use quotes to enclose values, whether numerical or strings.
Default: ``true``
.. versionadded:: 1.5
set this option value to ``false`` to recover former behaviour.
set this option value to ``false`` to recover former behavior.
.. versionchanged:: 2.3.0
added potential breakpoint at ``\`` characters.
@ -828,7 +863,7 @@ Do not use quotes to enclose values, whether numerical or strings.
.. note::
Values for colour keys must either:
Values for color keys must either:
- obey the syntax of the ``\definecolor`` LaTeX command, e.g. something
such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or
@ -838,7 +873,7 @@ Do not use quotes to enclose values, whether numerical or strings.
- 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
``MyPreviouslyDefinedColour`` or... Refer to xcolor_ documentation for
``MyPreviouslyDefinedColor`` or... Refer to xcolor_ documentation for
this syntax.
.. _xcolor: https://ctan.org/pkg/xcolor
@ -847,24 +882,24 @@ Do not use quotes to enclose values, whether numerical or strings.
Formerly only the ``\definecolor`` syntax was accepted.
``TitleColor``
The colour for titles (as configured via use of package "titlesec".)
The color for titles (as configured via use of package "titlesec".)
Default: ``{rgb}{0.126,0.263,0.361}``
``InnerLinkColor``
A colour passed to ``hyperref`` as value of ``linkcolor`` and
A color passed to ``hyperref`` as value of ``linkcolor`` and
``citecolor``.
Default: ``{rgb}{0.208,0.374,0.486}``.
``OuterLinkColor``
A colour passed to ``hyperref`` as value of ``filecolor``, ``menucolor``,
A color passed to ``hyperref`` as value of ``filecolor``, ``menucolor``,
and ``urlcolor``.
Default: ``{rgb}{0.216,0.439,0.388}``
``VerbatimColor``
The background colour for :rst:dir:`code-block`\ s.
The background color for :rst:dir:`code-block`\ s.
Default: ``{gray}{0.95}``
@ -891,7 +926,7 @@ Do not use quotes to enclose values, whether numerical or strings.
.. _tablecolors:
``TableRowColorHeader``
Sets the background colour for (all) the header rows of tables.
Sets the background color for (all) the header rows of tables.
It will have an effect only if either the :confval:`latex_table_style`
contains ``'colorrows'`` or if the table is assigned the ``colorrows``
@ -904,13 +939,13 @@ Do not use quotes to enclose values, whether numerical or strings.
Default: ``{gray}{0.86}``
There is also ``TableMergeColorHeader``. If used, sets a specific colour
There is also ``TableMergeColorHeader``. If used, sets a specific color
for merged single-row cells in the header.
.. versionadded:: 5.3.0
``TableRowColorOdd``
Sets the background colour for odd rows in tables (the row count starts at
Sets the background color for odd rows in tables (the row count starts at
``1`` at the first non-header row). Has an effect only if the
:confval:`latex_table_style` contains ``'colorrows'`` or for specific
tables assigned the ``colorrows`` class.
@ -922,7 +957,7 @@ Do not use quotes to enclose values, whether numerical or strings.
.. versionadded:: 5.3.0
``TableRowColorEven``
Sets the background colour for even rows in tables.
Sets the background color for even rows in tables.
Default ``{gray}{0.98}``
@ -974,32 +1009,49 @@ Do not use quotes to enclose values, whether numerical or strings.
Default: ``\fboxrule``
|notebdcolors|
The colour for the two horizontal rules used by Sphinx in LaTeX for styling
The color for the two horizontal rules used by Sphinx in LaTeX for styling
a :dudir:`note` type admonition.
Default: ``{rgb}{0,0,0}`` (black)
|notebgcolors|
The optional color for the background. It is a priori set to white, but
is not used, unless it has been set explicitly, and doing this triggers
Sphinx into switching to the more complex LaTeX code which is employed
also for ``warning`` type admonitions. There are then additional options
which are described in :ref:`additionalcss`.
Default: ``{rgb}{1,1,1}`` (white)
.. versionadded:: 6.2.0
``noteborder``, ``hintborder``, ``importantborder``, ``tipborder``
The width of the two horizontal rules.
If the background color is set, or the alternative :ref:`additionalcss`
syntax is used (e.g. ``div.note_border-width=1pt`` in place of
``noteborder=1pt``), or *any* option with a CSS-alike name is used, then
the border is a full frame and this parameter sets its width also for left
and right.
Default: ``0.5pt``
.. only:: not latex
|warningbdcolors|
The colour for the admonition frame.
The color for the admonition frame.
Default: ``{rgb}{0,0,0}`` (black)
.. only:: latex
|wgbdcolorslatex|
The colour for the admonition frame.
The color for the admonition frame.
Default: ``{rgb}{0,0,0}`` (black)
|warningbgcolors|
The background colours for the respective admonitions.
The background colors for the respective admonitions.
Default: ``{rgb}{1,1,1}`` (white)
@ -1031,6 +1083,9 @@ Do not use quotes to enclose values, whether numerical or strings.
.. |notebdcolors| replace:: ``noteBorderColor``, ``hintBorderColor``,
``importantBorderColor``, ``tipBorderColor``
.. |notebgcolors| replace:: ``noteBgColor``, ``hintBgColor``,
``importantBgColor``, ``tipBgColor``
.. |warningbdcolors| replace:: ``warningBorderColor``, ``cautionBorderColor``,
``attentionBorderColor``, ``dangerBorderColor``,
``errorBorderColor``
@ -1055,90 +1110,148 @@ Additional CSS-like ``'sphinxsetup'`` keys
.. versionadded:: 5.1.0
For :rst:dir:`code-block`, :dudir:`topic` and :dudir:`contents` directive,
and strong-type admonitions (:dudir:`warning`, :dudir:`error`, ...).
At ``5.1.0`` the LaTeX styling possibilities have been significantly enhanced.
Code-blocks, topic directives, and the five warning-type directives each now
possess:
.. versionadded:: 6.2.0
- four border-widths parameters,
- four padding parameters,
- four radius parameters (only circular arcs) for the corners,
- optional shadow, with x-offset and y-offset being possibly negative,
and the shadow possibly inset,
- colors for background, border and shadow.
Also the :dudir:`note`, :dudir:`hint`, :dudir:`important` and :dudir:`tip`
admonitions can be styled this way. Using for them *any* of the listed
options will trigger usage of a more complex LaTeX code than the one used
per default (``sphinxheavybox`` vs ``sphinxlightbox``). Setting the new
``noteBgColor`` (or ``hintBgColor``, ...) also triggers usage of
``sphinxheavybox`` for :dudir:`note` (or :dudir:`hint`, ...).
All those options have been named in a CSS-like way. Indeed, in future it is
envisioned to allow these settings to be specified either in an external file,
or in a string variable which would be parsed to extract from CSS the
selectors and properties which are understood.
Currently though this is added via a bunch of new ``'sphinxsetup'`` keys
whose names will be given now.
Perhaps in future these 5.1.0 (and 6.2.0) novel settings could be specified in
an external file, using genuine CSS syntax, but currently they have to be used
via the ``'sphinxsetup'`` interface and CSS-named alike options.
.. important:: Low-level LaTeX errors causing a build failure can happen if
the input syntax is not respected. In particular properties for colours,
whose names end with ``TeXcolor``, must be input as for the other colour
related options previously described, i.e. for example::
the input syntax is not respected.
...<other options>
div.warning_border-TeXcolor={rgb}{1,0,0},%
...<other options>
* In particular properties for colors,
whose names end with ``-TeXcolor``, must be input as for the other color
related options previously described, i.e. for example::
A colon will not be accepted in place of the equal sign which is
expected by the LaTeX syntax.
Do not insert spaces in the input. With the exception of the
``box-shadow`` all dimensional parameters expect a unique dimension
not a space separated list of dimensions.
...<other options>
div.warning_border-TeXcolor={rgb}{1,0,0},%
div.error_background-TeXcolor=red!10,% (if xcolor available)
...<other options>
Options for code-blocks:
* A colon will not be accepted in place of the equal sign which is expected
by the LaTeX syntax. Do not insert spaces in the input.
- | ``pre_border-top-width``,
| ``pre_border-right-width``,
| ``pre_border-bottom-width``,
| ``pre_border-left-width``,
| ``pre_border-width``, beware that this is a *single* dimension. Its
default, and the ones of the separate widths is the setting of
``\fboxrule`` in the preamble, i.e. normally ``0.4pt``.
- ``pre_box-decoration-break`` can be set to ``clone`` or ``slice``, default
is ``slice`` since 6.0.0. (former default was ``clone``).
- | ``pre_padding-top``,
| ``pre_padding-right``,
| ``pre_padding-bottom``,
| ``pre_padding-left``,
| ``pre_padding``, again this is a single dimension. Its default is the
setting of ``\fboxsep`` i.e. normally ``3pt``.
- | ``pre_border-top-left-radius``,
| ``pre_border-top-right-radius``,
| ``pre_border-bottom-right-radius``,
| ``pre_border-bottom-left-radius``,
| ``pre_border-radius``, are all single dimensions (rounded corners are
circular arcs only), which default (since 6.0.0) to ``3pt``.
- ``pre_box-shadow`` is special in so far as it may be the ``none`` keyword,
or a single dimension
which will be assigned to both x-offset and y-offset, or two dimensions, or
two dimensions followed by the word ``inset``. The x-offset and y-offset
may be negative. The defaults is ``none``.
- | ``pre_border-TeXcolor``,
| ``pre_background-TeXcolor``,
| ``pre_box-shadow-TeXcolor``.
* All dimensional parameters expect a *unique* dimension, even
``border-width`` or ``padding``: they can not be used with a value being
a space separated list of dimensions. The sole exception currently is
``box-shadow``.
They
default to ``{RGB}{32,32,32}``, ``{gray}{0.95}`` and ``{rgb}{0,0,0}``
respectively (since 6.0.0).
* Dimensions should use TeX units such as ``pt`` or ``cm`` or ``in``. The
``px`` unit is recognized by ``pdflatex`` and ``lualatex`` but not by
``xelatex`` or ``platex``.
.. versionchanged:: 6.0.0
Formerly ``pre_border-radius`` (aka ``VerbatimBorder``) was ``0pt``
(i.e. straight corners) and the colours ``pre_border-TeXcolor``
and ``pre_background-TeXcolor`` (aka ``VerbatimBorderColor`` and
``VerbatimColor``) where ``{rgb}{0,0,0}`` (black border) and
``{rgb}{1,1,1}`` (white background) respectively.
Also ``pre_box-decoration-break`` was changed from ``clone`` into
``slice`` for "open" framing at pagebreaks.
The options are all named in a similar pattern which depends on a ``prefix``,
which is then followed by an underscore, then the option name.
If one of the radius parameters is positive, the separate border widths will
be ignored and only the value set by ``pre_border-width`` will be used. Also,
if a shadow is present and is inset, the box will be rendered with straight
corners.
.. csv-table::
:header: Directive, Option prefix, LaTeX environment
:rst:dir:`code-block`, ``pre``, ``sphinxVerbatim``
:dudir:`topic`, ``div.topic``, ``sphinxShadowBox``
contents_, ``div.topic``, ``sphinxShadowBox``
:dudir:`note`, ``div.note``, ``sphinxnote`` using ``sphinxheavybox``
:dudir:`warning`, ``div.warning``, ``sphinxwarning`` (uses ``sphinxheavybox``)
admonition type, ``div.<type>``, ``sphinx<type>`` (using ``sphinxheavybox``)
.. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents
Here are now these options as well as their common defaults.
Replace below ``<prefix>`` by the actual prefix as explained above. Don't
forget the underscore separating the prefix from the attribute name.
- | ``<prefix>_border-top-width``,
| ``<prefix>_border-right-width``,
| ``<prefix>_border-bottom-width``,
| ``<prefix>_border-left-width``,
| ``<prefix>_border-width``. The latter can (currently) be only a *single*
dimension which then sets all four others.
The default is that all those dimensions are equal. They are set to:
* ``\fboxrule`` (i.e. normally ``0.4pt``) for :rst:dir:`code-block`,
* ``\fboxrule`` for :dudir:`topic` or contents_ directive,
* ``1pt`` for :dudir:`warning` and other "strong" admonitions,
* ``0.5pt`` for :dudir:`note` and other "light" admonitions. The framing
style of the "lighbox" used for them in absence of usage of CSS-named
options will be emulated by the richer "heavybox" if setting
``border-left-width`` and ``border-right-width`` both to ``0pt``.
- ``<prefix>_box-decoration-break`` can be set to either ``clone`` or
``slice``. It is currently *ignored* by all except :rst:dir:`code-block`
(i.e. ``pre`` prefix) and then defaults to ``slice`` since 6.0.0 (former
default was ``clone``).
- | ``<prefix>_padding-top``,
| ``<prefix>_padding-right``,
| ``<prefix>_padding-bottom``,
| ``<prefix>_padding-left``,
| ``<prefix>_padding``. The latter can (currently) be only a *single*
dimension which then sets all four others.
The default is that all those dimensions are equal. They are set to:
* ``\fboxsep`` (i.e. normally ``3pt``) for :rst:dir:`code-block`,
* ``5pt`` for :dudir:`topic` or contents_ directive,
* a special value for :dudir:`warning` and other "strong" admonitions,
which ensures a backward compatible behavior.
.. important:: Prior to 5.1.0 there was no separate customizability of
padding for warning-type boxes in PDF via LaTeX output. The sum of
padding and border-width (as set for example for :dudir:`warning` by
``warningborder``, now also named ``div.warning_border-width``) was
kept to a certain constant value. This limited the border-width
to small values else the border could overlap the text contents.
This behavior is kept as default.
* the same padding behavior is obeyed per default for :dudir:`note` or
other "light" admonitions when using ``sphinxheavybox``.
- | ``<prefix>_border-top-left-radius``,
| ``<prefix>_border-top-right-radius``,
| ``<prefix>_border-bottom-right-radius``,
| ``<prefix>_border-bottom-left-radius``,
| ``<prefix>_border-radius``. The latter can (currently) be only a *single*
dimension which then sets all four others (rounded corners are
circular arcs only, no ellipses).
The default is that all those dimensions are equal. They are set to:
* ``3pt`` for :rst:dir:`code-block` (since 6.0.0).
* ``0pt``, i.e. straight corners for all other directives.
- ``<prefix>_box-shadow`` is special in so far as it may be the ``none``
keyword, or a single dimension which will be assigned to both x-offset and
y-offset, or two dimensions separated by a space, or two dimensions
separated by a space and followed by a space and the word ``inset``. The
x-offset and y-offset may be negative. The default is ``none``, *except*
for the :dudir:`topic` or contents_ directives, for which it is ``4pt 4pt``,
i.e. the shadow has a width of ``4pt`` and is on the right and below.
- | ``<prefix>_border-TeXcolor``,
| ``<prefix>_background-TeXcolor``,
| ``<prefix>_box-shadow-TeXcolor``.
These are colors.
The shadow color defaults in all cases to ``{rgb}{0,0,0}`` i.e. to black.
Since 6.0.0 the border color and background color of :rst:dir:`code-block`,
i.e. ``pre`` prefix, default respectively to ``{RGB}{32,32,32}`` and
``{gray}{0.95}``. They previously defaulted to black, respectively white.
For all other types, the border color defaults to black and the background
color to white (technically, the LaTeX code does not even bother injecting
color commands then).
.. note::
If one of the radii parameters is set to a positive value, the separate
border widths will be ignored and only the value set by
``<prefix>_border-width`` will be used. Also, if a shadow is present and is
inset, the box will automatically be rendered with straight corners.
.. note::
@ -1149,116 +1262,38 @@ corners.
.. _pict2e: https://ctan.org/pkg/pict2e
Options for topic boxes:
The following legacy behavior is currently not customizable:
- | ``div.topic_border-top-width``,
| ``div.topic_border-right-width``,
| ``div.topic_border-bottom-width``,
| ``div.topic_border-left-width``,
| ``div.topic_border-width``, beware that this is a *single* dimension. Its
default, and the ones of the separate widths is the setting of
``\fboxrule`` in the preamble, i.e. normally ``0.4pt``.
- ``div.topic_box-decoration-break`` is currently ignored.
- | ``div.topic_padding-top``,
| ``div.topic_padding-right``,
| ``div.topic_padding-bottom``,
| ``div.topic_padding-left``,
| ``div.topic_padding``,
again this is a single dimension. Its default is ``5pt``.
- For :rst:dir:`code-block`, padding and border-width and shadow (if one adds
one) will go into the margin; the code lines remain at the same place
independently of the values of the padding and border-width, except for
being shifted vertically of course to not overwrite other text.
.. versionchanged:: 6.1.2
These keys had been implemented at 5.1.0 without ``div.`` in
their names.
- | ``div.topic_border-top-left-radius``,
| ``div.topic_border-top-right-radius``,
| ``div.topic_border-bottom-right-radius``,
| ``div.topic_border-bottom-left-radius``,
| ``div.topic_border-radius``.
- For :dudir:`topic` the shadow (if on right) goes into the page
margin, but the border (and the extra padding) are kept within the text
area. Same for admonitions if configured to display a shadow.
They all are single dimensions which default to ``0pt``.
- ``div.topic_box-shadow`` defaults to ``4pt 4pt``.
- | ``div.topic_border-TeXcolor``,
| ``div.topic_background-TeXcolor``,
| ``div.topic_box-shadow-TeXcolor``.
- The contents_ and :dudir:`topic` directives are governed by the same options
with ``div.topic`` prefix: the Sphinx LaTeX mark-up uses for both directives
the same ``sphinxShadowBox`` environment which has currently no additional
branching, contrarily to the ``sphinxadmonition`` environment which branches
according to the admonition directive name, e.g. eitther to ``sphinxnote``
or ``sphinxwarning`` etc...
They default to ``{rgb}{0,0,0}``, ``{rgb}{1,1,1}``
and ``{rgb}{0,0,0}`` respectively.
Options for ``warning`` (and similarly for ``caution``, ``attention``,
``danger``, ``error``) directive:
- | ``div.warning_border-top-width``,
| ``div.warning_border-right-width``,
| ``div.warning_border-bottom-width``,
| ``div.warning_border-left-width``,
| ``div.warning_border-width``,
beware that this is a *single* dimension. Its
default, and the ones of the separate widths is ``1pt``.
- ``div.warning_box-decoration-break`` is currently ignored.
- | ``div.warning_padding-top``,
| ``div.warning_padding-right``,
| ``div.warning_padding-bottom``,
| ``div.warning_padding-left``,
| ``div.warning_padding``, again this is a single dimension.
.. important:: Prior to ``5.1.0`` there was no separate customizability of
padding for warning-type boxes in PDF via LaTeX output. The sum of
padding and border-width (as set by ``warningborder``, now also named
``div.warning_border-width``) was kept to a certain constant value (and
this limited the border-width to small values else the border could
overlap the text contents). This behaviour is kept as default. Using
the ``div.warning_padding`` key will cancel for all four paddings the
legacy behaviour, but using only one of the four padding keys leaves the
three other paddings behave as formerly.
- | ``div.warning_border-top-left-radius``,
| ``div.warning_border-top-right-radius``,
| ``div.warning_border-bottom-right-radius``,
| ``div.warning_border-bottom-left-radius``,
| ``div.warning_border-radius``.
They are all single dimensions which default to ``0pt``.
- ``div.warning_box-shadow`` defaults to ``none``.
- | ``div.warning_border-TeXcolor``,
| ``div.warning_background-TeXcolor``,
| ``div.warning_box-shadow-TeXcolor``.
They default to ``{rgb}{0,0,0}``, ``{rgb}{1,1,1}``
and ``{rgb}{0,0,0}`` respectively.
In the above replace ``warning`` by one of ``caution``, ``attention``,
``danger``, ``error`` to style the respective directives.
The following legacy behaviour of the PDF layout is currently not
customizable:
- for code-blocks, padding and border-width and shadow (if one adds one) will
go into the margin; the code lines remain at the same place independently of
the values of the padding and border-width, except for being shifted
vertically of course to not overwrite other text.
- for topic boxes and warning-type notices only the shadows will go into page
margin, the borders are kept within the text area.
- ``contents`` and ``topic`` directive are styled the same way.
.. note::
The ``note``-style admonition directives admit no such customization
interface at this stage.
Here is a random example (not especially recommended!):
Here is a further (random) example configuration (which is not especially
recommended!), but see perhaps rather the configuration displayed at start of
:ref:`latexsphinxsetup`.
.. code-block:: latex
latex_elements = {
'sphinxsetup': """%
% For colors, we use throughout this example the \definecolor syntax
% The leaner \colorlet syntax is available if xcolor is on your system
pre_background-TeXcolor={RGB}{242,242,242},% alias of VerbatimColor
pre_border-TeXcolor={RGB}{32,32,32},%
pre_box-decoration-break=slice,
% pre_border-top-width=5pt,% will be ignored due to non-zero radii
% pre_border-right-width=10pt,
% pre_border-bottom-width=15pt,
% pre_border-left-width=20pt,
pre_border-width=3pt,% sets equally the four border-widths,
% needed for rounded corners
pre_border-top-left-radius=20pt,
@ -1286,8 +1321,18 @@ Here is a random example (not especially recommended!):
""",
}
In future, it is hoped to add further CSS properties such as ``font`` or
``color``.
.. important::
In future, it is hoped to add further CSS properties such as ``font`` or
``color``. For time being if you want to modify the text color in a
:dudir:`warning`, you have to add something such as this in the preamble:
.. code-block:: latex
% redefine sphinxwarning environment to color its contents
\renewenvironment{sphinxwarning}[1]
{\begin{sphinxheavybox}\sphinxstrong{#1} \color{red}}% <-- text in red
{\end{sphinxheavybox}}
LaTeX macros and environments
@ -1547,7 +1592,7 @@ Environments
of the notice, for example ``Warning:`` for :dudir:`warning` directive, if
English is the document language). Their default definitions use either the
*sphinxheavybox* (for the last 5 ones) or the *sphinxlightbox*
environments, configured to use the parameters (colours, border thickness)
environments, configured to use the parameters (colors, border thickness)
specific to each type, which can be set via ``'sphinxsetup'`` string.
.. versionchanged:: 1.5
@ -1557,7 +1602,7 @@ Environments
- Environment for the :rst:dir:`seealso` directive: ``sphinxseealso``.
It takes one argument which will be the localized string ``See also``. Its
default definition maintains the legacy behaviour: the localized ``See
default definition maintains the legacy behavior: the localized ``See
also``, followed with a colon, will be rendered using ``\sphinxstrong``.
Nothing particular is done for the contents.

171
sphinx/texinputs/sphinx.sty
View File

@ -186,22 +186,20 @@ will be set to white}%
% latter, were used under an aliased name. They got removed at 6.2.0.
%
% notices/admonitions
% the dimensions for notices/admonitions are kept as macros and assigned to
% \spx@notice@border at time of use, hence \DeclareStringOption is ok for this
\newdimen\spx@notice@border
\DeclareStringOption[0.5pt]{noteborder}
\DeclareStringOption[0.5pt]{hintborder}
\DeclareStringOption[0.5pt]{importantborder}
\DeclareStringOption[0.5pt]{tipborder}
% Compatibility layer to share for these notice types common code
% with the one for warning, danger, ..., in sphinxlatexadmonitions.sty
\def\spx@note@border {\spx@opt@noteborder}
\def\spx@hint@border {\spx@opt@hintborder}
\def\spx@important@border{\spx@opt@importantborder}
\def\spx@tip@border {\spx@opt@tipborder}
% The warning type notices are handled in the "CSS" section below.
% 6.2.0 does not define \spx@opt@warningborder etc... macros
% but only \spx@warning@border etc...
% 5.1.0 added much customizability to warning, caution, attention, danger and
% error types of notices via an enhanced sphinxheavybox environment.
% 6.2.0 has added the possiblity to use the same kind of rendering also for
% note, hint, important, and tip.
% All this is now handled below in the "CSS" section. Legacy user interface
% for options is kept working, but all of it is handled in the "CSS" section.
% We do define here some non-documented booleans which will serve internally.
% There is no reason for user to know about them, except if it is desired to
% toggle mid-way in the document whether note, hint, important, and tip
% should use the "lightbox" or the "heavybox" rendering.
\DeclareBoolOption[false]{heavynote}
\DeclareBoolOption[false]{heavyhint}
\DeclareBoolOption[false]{heavyimportant}
\DeclareBoolOption[false]{heavytip}
% footnotes
\DeclareStringOption[\mbox{ }]{AtStartFootnote}
% we need a public macro name for direct use in latex file
@ -254,11 +252,21 @@ will be set to white}%
% Default color chosen to be as in minted.sty LaTeX package!
\sphinxDeclareSphinxColorOption{VerbatimHighlightColor}{{rgb}{0.878,1,1}}
% admonition boxes, "light" style
% border color defaults to black
% at 6.2.0 also background color is possible, but it then triggers
% usage of the "sphinxheavybox" from sphinxlatexadmonitions.sty.
\sphinxDeclareSphinxColorOption{noteBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{hintBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{importantBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{tipBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{noteBgColor}{{rgb}{1,1,1}}
\sphinxDeclareSphinxColorOption{hintBgColor}{{rgb}{1,1,1}}
\sphinxDeclareSphinxColorOption{importantBgColor}{{rgb}{1,1,1}}
\sphinxDeclareSphinxColorOption{tipBgColor}{{rgb}{1,1,1}}
% admonition boxes, "heavy" style
% border color defaults to black and background color to white
% As long as the color are not explicitly set via user options,
% the sphinxpackageboxes.sty code will actually not use them anyhow.
\sphinxDeclareSphinxColorOption{warningBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{cautionBorderColor}{{rgb}{0,0,0}}
\sphinxDeclareSphinxColorOption{attentionBorderColor}{{rgb}{0,0,0}}
@ -285,18 +293,18 @@ will be set to white}%
\def\spxstring@none{none}
\def\spxstring@clone{clone}
%
% Refactoring at 6.2.0
% --------------------
% Refactoring (and extension) at 6.2.0
% ------------------------------------
%
% - Legacy \dimen registers \sphinxverbatimborder, \sphinxverbatimsep,
% \sphinxshadowsep, \sphinxshadowsize, and \sphinxshadowrule,
% which had been deprecated have finally been removed,
% - No \dimen registers used at all (at some point the \dimen's
% \spxdimen@pre@border and \spxdimen@topic@border were still defined)
% as all dimensions are stored in macros. Dimen registers are used only
% by the box macros of sphinxpackageboxes.sty, and are initialized from
% the macro storage relative to each type (code-block, topic, ...)
% at time of use.
%
% - No \dimen registers used here, all dimensions are stored in macros.
%
% - "note/hint/..." types of admonitions now accept same user interface as
% for "warning/danger/...", and if this is used, they will be rendered
% using sphinxheavybox, not sphinxlightbox from sphinxlatexadmonitions.sty
%
% 6.2.0 batch defines in one go all auxiliaries for code blocks, topics,
% and warning-type admonitions. Some needed add-ons due to maintaining
@ -351,6 +359,10 @@ will be set to white}%
% macro prefix option prefix legacy option init value
\spx@tempa{spx@pre@} {pre_} {verbatimborder} \fboxrule
\spx@tempa{spx@topic@} {div.topic_} {shadowrule} \fboxrule
\spx@tempa{spx@note@} {div.note_} {noteborder} {0.5pt}
\spx@tempa{spx@hint@} {div.hint_} {hintborder} {0.5pt}
\spx@tempa{spx@important@}{div.important_}{importantborder}{0.5pt}
\spx@tempa{spx@tip@} {div.tip_} {tipborder} {0.5pt}
\spx@tempa{spx@warning@} {div.warning_} {warningborder} {1pt}
\spx@tempa{spx@caution@} {div.caution_} {cautionborder} {1pt}
\spx@tempa{spx@attention@}{div.attention_}{attentionborder}{1pt}
@ -389,10 +401,18 @@ will be set to white}%
% #1 macro prefix #6 option prefix init value
\spx@tempa{spx@pre@} {pre_} \fboxsep
\spx@tempa{spx@topic@} {div.topic_} {5pt}
% MEMO: prior to 5.1.0 padding was not separately customizable
% from border width for warning type admonitions. The below
% keeps the legacy behavior of a constant borderwidth+padding.
% The dim expression is not evaluated yet, only at time of use.
% MEMO: prior to 6.2.0, "note" type admonitions used sphinxlightbox automatically
% and had no interface to set the padding parameters needed by sphinxheavybox.
% At 6.2.0 they acquire such interface and the default is set as for legacy
% default of "warning" type.
\spx@tempa{spx@note@} {div.note_} {\dimexpr.6\baselineskip-\spx@note@border\relax}
\spx@tempa{spx@hint@} {div.hint_} {\dimexpr.6\baselineskip-\spx@hint@border\relax}
\spx@tempa{spx@important@}{div.important_} {\dimexpr.6\baselineskip-\spx@important@border\relax}
\spx@tempa{spx@tip@} {div.tip_} {\dimexpr.6\baselineskip-\spx@tip@border\relax}
% MEMO: prior to 5.1.0 padding was not separately customizable from border
% width for warning type admonitions. The below keeps the legacy behavior of a
% constant borderwidth+padding. The dim expression is not evaluated yet, only
% at time of use.
\spx@tempa{spx@warning@} {div.warning_} {\dimexpr.6\baselineskip-\spx@warning@border\relax}
\spx@tempa{spx@caution@} {div.caution_} {\dimexpr.6\baselineskip-\spx@caution@border\relax}
\spx@tempa{spx@attention@}{div.attention_} {\dimexpr.6\baselineskip-\spx@attention@border\relax}
@ -424,12 +444,16 @@ will be set to white}%
% macro prefix option prefix init value
\spx@tempa{spx@pre@} {pre_} {3pt}% new default at 6.0.0
\spx@tempa{spx@topic@} {div.topic_} \z@
\spx@tempa{spx@note@} {div.note_} \z@ % new at 6.2.0
\spx@tempa{spx@hint@} {div.hint_} \z@ % new at 6.2.0
\spx@tempa{spx@important@}{div.important_} \z@ % new at 6.2.0
\spx@tempa{spx@tip@} {div.tip_} \z@ % new at 6.2.0
\spx@tempa{spx@warning@} {div.warning_} \z@
\spx@tempa{spx@caution@} {div.caution_} \z@
\spx@tempa{spx@attention@}{div.attention_} \z@
\spx@tempa{spx@danger@} {div.danger_} \z@
\spx@tempa{spx@error@} {div.error_} \z@
\spx@tempa{spx@box@} {box_} {3pt}% new and tentative default at 6.2.0
\spx@tempa{spx@box@} {box_} {3pt}% new at 6.2.0
% Shadow keys
%
@ -442,12 +466,16 @@ will be set to white}%
% macro prefix
\spx@tempa{spx@pre@}
\spx@tempa{spx@topic@}
\spx@tempa{spx@note@} % new at 6.2.0
\spx@tempa{spx@hint@} % new at 6.2.0
\spx@tempa{spx@important@} % new at 6.2.0
\spx@tempa{spx@tip@} % new at 6.2.0
\spx@tempa{spx@warning@}
\spx@tempa{spx@caution@}
\spx@tempa{spx@attention@}
\spx@tempa{spx@danger@}
\spx@tempa{spx@error@}
\spx@tempa{spx@box@}% new at 6.2.0
\spx@tempa{spx@box@} % new at 6.2.0
%
\def\spx@tempa#1{% #1 = macro prefix
\expandafter\spx@tempb
@ -483,6 +511,10 @@ will be set to white}%
\spx@tempa{spx@topic@} {div.topic_}
% This corresponds to the legacy parameters of ShadowBox
\spx@topic@shadow@setter 4pt 4pt {} \@nnil
\spx@tempa{spx@note@} {div.note_} % new at 6.2.0
\spx@tempa{spx@hint@} {div.hint_} % new at 6.2.0
\spx@tempa{spx@important@}{div.important_} % new at 6.2.0
\spx@tempa{spx@tip@} {div.tip_} % new at 6.2.0
\spx@tempa{spx@warning@} {div.warning_}
\spx@tempa{spx@caution@} {div.caution_}
\spx@tempa{spx@attention@}{div.attention_}
@ -490,7 +522,7 @@ will be set to white}%
\spx@tempa{spx@error@} {div.error_}
\spx@tempa{spx@box@} {box_}% new at 6.2.0
% Support for legacy shadowsize
% Support for legacy shadowsize (topic/contents)
% This definition was broken at 5.1.0 and fixed at 6.1.2
\define@key{sphinx}{shadowsize}{%
\edef\spx@topic@shadow@xoffset{\number\dimexpr#1\relax sp}%
@ -520,6 +552,10 @@ will be set to white}%
% macro prefix
\spx@tempa{spx@pre@}
\spx@tempa{spx@topic@}
\spx@tempa{spx@note@}
\spx@tempa{spx@hint@}
\spx@tempa{spx@important@}
\spx@tempa{spx@tip@}
\spx@tempa{spx@warning@}
\spx@tempa{spx@caution@}
\spx@tempa{spx@attention@}
@ -553,17 +589,21 @@ will be set to white}%
\csname KV@sphinx@pre_border-TeXcolor\endcsname
\expandafter\let\expandafter\KV@sphinx@VerbatimColor
\csname KV@sphinx@pre_background-TeXcolor\endcsname
% macro prefix option prefix color name prefix
% MEMO: prior to 6.2.0, internal color names started with sphinxtopic, not
% sphinxTopic, and it was sphinxTopicBackgroundColor, not sphinxtopicBgColor.
% macro prefix option prefix color name prefix
\spx@tempa{spx@topic@} {div.topic_} {sphinxtopic}% (no legacy interface)
\spx@tempa{spx@note@} {div.note_} {sphinxnote} % new at 6.2.0
\spx@tempa{spx@hint@} {div.hint_} {sphinxhint} % new at 6.2.0
\spx@tempa{spx@important@}{div.important_} {sphinximportant} % new at 6.2.0
\spx@tempa{spx@tip@} {div.tip_} {sphinxtip} % new at 6.2.0
\spx@tempa{spx@warning@} {div.warning_} {sphinxwarning}
\spx@tempa{spx@caution@} {div.caution_} {sphinxcaution}
\spx@tempa{spx@attention@}{div.attention_} {sphinxattention}
\spx@tempa{spx@danger@} {div.danger_} {sphinxdanger}
\spx@tempa{spx@error@} {div.error_} {sphinxerror}
\spx@tempa{spx@box@} {box_} {sphinxbox}% new at 6.2.0
% Keep legacy sphinxsetup interface for warning type notices
% Keep legacy sphinxsetup color options interface for "strong" admonitions
\def\spx@tempa#1#2{% #1 = option prefix, #2 = legacy option prefix
\expandafter\let\csname KV@sphinx@#2BorderColor\expandafter\endcsname
\csname KV@sphinx@#1border-TeXcolor\endcsname
@ -576,6 +616,71 @@ will be set to white}%
\spx@tempa{div.danger_} {danger}
\spx@tempa{div.error_} {error}
% Let us recreate the legacy {note,...}BorderColor option interface
\def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy option prefix
\expandafter\let\csname KV@sphinx@#2BorderColor\expandafter\endcsname
\csname KV@sphinx@#1border-TeXcolor\endcsname
}
\spx@tempa{div.note_} {note}
\spx@tempa{div.hint_} {hint}
\spx@tempa{div.important_} {important}
\spx@tempa{div.tip_} {tip}
% For note type admonitions, redefine all CSS-like named options to trigger
% the "heavybox" path. This goes via rather hardcore TeX here.
%
% MEMO: the noteBorderColor and noteborder legacy options have already been
% re-created and they do not trigger the "heavybox" as their meaning will not
% be modified in the loop below contrarily to their CSS counterparts
% border-TeXcolor and border-width.
\def\spx@tempa#1{\if\relax#1\expandafter\@gobble
\else
\toks@{##1}%
\expandafter\def\csname KV@sphinx@div.note_#1\expandafter\endcsname
\the\toks0\expandafter{%
\csname spx@opt@heavynotetrue\expandafter\expandafter\expandafter\endcsname
\csname KV@sphinx@div.note_#1\endcsname{##1}}%
\expandafter\def\csname KV@sphinx@div.hint_#1\expandafter\endcsname
\the\toks0\expandafter{%
\csname spx@opt@heavyhinttrue\expandafter\expandafter\expandafter\endcsname
\csname KV@sphinx@div.hint_#1\endcsname{##1}}%
\expandafter\def\csname KV@sphinx@div.important_#1\expandafter\endcsname
\the\toks0\expandafter{%
\csname spx@opt@heavyimportanttrue\expandafter\expandafter\expandafter\endcsname
\csname KV@sphinx@div.important_#1\endcsname{##1}}%
\expandafter\def\csname KV@sphinx@div.tip_#1\expandafter\endcsname
\the\toks0\expandafter{%
\csname spx@opt@heavytiptrue\expandafter\expandafter\expandafter\endcsname
\csname KV@sphinx@div.tip_#1\endcsname{##1}}%
\fi
\spx@tempa
}
\spx@tempa{border-width}%
{border-top-width}{border-right-width}{border-bottom-width}{border-left-width}%
{box-decoration-break}%
{padding}%
{padding-top}{padding-right}{padding-bottom}{padding-left}%
{border-radius}%
{border-top-left-radius}{border-top-right-radius}%
{border-bottom-right-radius}{border-bottom-left-radius}%
{box-shadow}%
{border-TeXcolor}{background-TeXcolor}{box-shadow-TeXcolor}%
\relax
% Now we add at 6.2.0 {note,...}BgColor named options which will trigger
% the "heavybox" as they are \let to the background-TeXColor option which has
% already been enhanced to set the boolean for rendering via "heavybox".
% This is in contrast with legacy {note,...}BorderColor.
\def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy style option prefix
\expandafter\let\csname KV@sphinx@#2BgColor\expandafter\endcsname
\csname KV@sphinx@#1background-TeXcolor\endcsname
}
\spx@tempa{div.note_} {note}
\spx@tempa{div.hint_} {hint}
\spx@tempa{div.important_} {important}
\spx@tempa{div.tip_} {tip}
\DeclareDefaultOption{\@unknownoptionerror}
\ProcessKeyvalOptions*
% don't allow use of maxlistdepth via \sphinxsetup.

148
sphinx/texinputs/sphinxlatexadmonitions.sty
View File

@ -11,6 +11,7 @@
% This is a dispatch supporting
%
% - note, hint, important, tip (via sphinxlightbox)
% (also optionally via sphinxheavybox since 6.2.0)
% - warning, caution, attention, danger, error (via sphinxheavybox)
%
% Each sphinx<notice name> environment can be redefined by user.
@ -35,7 +36,14 @@
% Some are quite plain
\newenvironment{sphinxseealso}[1]{\sphinxstrong{#1:}\par\nopagebreak}{}
% the spx@notice@bordercolor etc are set in the sphinxadmonition environment
% This \dimen register is a legacy relic from Sphinx 1.5, as well as
% spx@notice@border@color (used in sphinxlightbox environment and set in
% sphinxadmonition environment) which one could dispose of, using \spx@notice
% which is defined by sphinxadmonition environment. Let's simply keep as used
% since 1.5.
\newdimen\spx@notice@border
% spx@notice@bordercolor and \spx@notice@border are set in sphinxadmonition environment
\newenvironment{sphinxlightbox}{%
\par
\noindent{\color{spx@notice@bordercolor}%
@ -51,78 +59,59 @@
\rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
{\linewidth}{\spx@notice@border}}\hss}\allowbreak
}% end of sphinxlightbox environment definition
% may be renewenvironment'd by user for complete customization
\newenvironment{sphinxnote}[1]
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
\newenvironment{sphinxhint}[1]
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
\newenvironment{sphinximportant}[1]
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
\newenvironment{sphinxtip}[1]
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
% or just use the package options
% these are needed for common handling by notice environment of lightbox
% and heavybox but they are currently not used by lightbox environment
% and there is consequently no corresponding package option
\definecolor{sphinxnoteBgColor}{rgb}{1,1,1}
\definecolor{sphinxhintBgColor}{rgb}{1,1,1}
\definecolor{sphinximportantBgColor}{rgb}{1,1,1}
\definecolor{sphinxtipBgColor}{rgb}{1,1,1}
% Others get more distinction
% This setup macro has somewhat peculiar names for colors, this is
% heritage of the evolution of code while keeping a common base for both
% "warning"-type and "note"-type notices and backward compatibility
\def\spx@admonitions@boxes@fcolorbox@setup{%
\spx@boxes@fcolorbox@setup
{\spx@noticetype}{spx@notice@bordercolor}%
{spx@notice@bgcolor}%
{sphinx\spx@noticetype ShadowColor}%
}
% rescue code in case sphinxheavybox is used for note-like notices
% (this is executed if there is no radius.topleft associated macro)
\def\spx@admonitions@boxes@fcolorbox@setup@fallback{%
\spx@boxes@border@top \spx@notice@border
\spx@boxes@border@right \spx@notice@border
\spx@boxes@border@bottom\spx@notice@border
\spx@boxes@border@left \spx@notice@border
\spx@boxes@border \spx@notice@border
% legacy behavior for padding
\spx@boxes@padding@top \dimexpr.6\baselineskip-\spx@notice@border\relax
\spx@boxes@padding@right \spx@boxes@padding@top
\spx@boxes@padding@bottom\spx@boxes@padding@top
\spx@boxes@padding@left \spx@boxes@padding@top
% straight corners
\spx@boxes@radius@topleft \z@
\spx@boxes@radius@topright \z@
\spx@boxes@radius@bottomright \z@
\spx@boxes@radius@bottomleft \z@
% legacy has no shadow (no need to set \ifspx@boxes@shadowinbbox)
\spx@boxes@withshadowfalse
\spx@boxes@insetshadowfalse
\spx@boxes@withshadowcolorfalse
% assume background color although there is no public interface,
% sphinxnoteBgColor et al. are defined above and let to white
\spx@boxes@withbackgroundcolortrue
\sphinxcolorlet{spx@boxes@backgroundcolor}{spx@notice@bgcolor}%
% assume always with border color (for simplicity sake, again, and this
% time there is a public interface)
\spx@boxes@withbordercolortrue
\sphinxcolorlet{spx@boxes@bordercolor}{spx@notice@bordercolor}%
\def\spx@boxes@fcolorbox{\spx@boxes@fcolorbox@rectangle}%
}
% note/hint/important/tip notices
%
% 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:
%
% \newenvironment{sphinxhint}[1]
% {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
%
% It was possible for user to \renewenvironment this to use sphinxheavybox,
% but this had stopped functioning at 5.1.0 which had greatly enhanced the
% sphinxheavybox environment and the needed support macros existed only for
% warning, caution, attention, danger, and error admonitions. At 6.1.0 a
% patch was added to allow the \renewenvironment method to work again for
% note, hint, important, tip to use sphinxheavybox.
%
% Then at 6.2.0, note, hint, important, tip can now access full customization
% of sphinxheavybox: CSS-named alike options (if used) trigger sphinxheavybox.
% The \renewenvironment method still works but then only common border width,
% non-configurable padding, straight corners and no shadow are all implied,
% as long as the related CSS-named options are not used.
\newenvironment{sphinxnote}[1]
{\edef\spx@env{sphinx\ifspx@opt@heavynote heavy\else light\fi box}%
\expanded{\noexpand\begin{\spx@env}}\sphinxstrong{#1} }
{\expandafter\end\expandafter{\spx@env}}
\newenvironment{sphinxhint}[1]
{\edef\spx@env{sphinx\ifspx@opt@heavyhint heavy\else light\fi box}%
\expanded{\noexpand\begin{\spx@env}}\sphinxstrong{#1} }
{\expandafter\end\expandafter{\spx@env}}
\newenvironment{sphinximportant}[1]
{\edef\spx@env{sphinx\ifspx@opt@heavyimportant heavy\else light\fi box}%
\expanded{\noexpand\begin{\spx@env}}\sphinxstrong{#1} }
{\expandafter\end\expandafter{\spx@env}}
\newenvironment{sphinxtip}[1]
{\edef\spx@env{sphinx\ifspx@opt@heavytip heavy\else light\fi box}%
\expanded{\noexpand\begin{\spx@env}}\sphinxstrong{#1} }
{\expandafter\end\expandafter{\spx@env}}
% warning/caution/attention/danger/error get more distinction
%
% Code adapted from framed.sty's "snugshade" environment.
% Nesting works (inner frames do not allow page breaks).
\newenvironment{sphinxheavybox}{\par
\ifcsname spx@\spx@noticetype @radius@topleft\endcsname
\expandafter\@firstoftwo
\else
% attempt to use sphinxheavybox without the circa 20 needed style
% parameters, i.e., for one of the light notice types
\expandafter\@secondoftwo
\fi
\spx@admonitions@boxes@fcolorbox@setup
\spx@admonitions@boxes@fcolorbox@setup@fallback
% 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}{spx@notice@bordercolor}%
{spx@notice@bgcolor}%
{sphinx\spx@noticetype ShadowColor}%
% Those are used by sphinxVerbatim if the \ifspx@inframed boolean is true
\setlength{\FrameRule}{0.5\dimexpr\spx@boxes@border@top+\spx@boxes@border@bottom\relax}%
% MEMO: prior to 5.1.0 \FrameSep was determined as 0.6\baselineskip -
@ -183,7 +172,17 @@
% arrange for similar spacing below frame as for "light" boxes.
\vskip .4\baselineskip
}% end of sphinxheavybox environment definition
% may be renewenvironment'd by user for complete customization
% - Since 1.5 these environments are named individually to allow user to
% redefine them entirely.
%
% - Since 5.1.0, sphinxheavybox is more versatile and four border widths, four
% padding widths, four corner radii, optional shadow, and three colors can all
% be modified via CSS-named alike options.
%
% - Since 6.2.0, also note/hint/important/tip notices can use these options
% and then they go automatically via sphinxheavybox. If only the legacy options
% are used, they keep using sphinxlightbox.
\newenvironment{sphinxwarning}[1]
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
\newenvironment{sphinxcaution}[1]
@ -194,19 +193,18 @@
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
\newenvironment{sphinxerror}[1]
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
% or just use package options
% the main dispatch for all types of notices
\newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
% can't use #1 directly in definition of end part
\def\spx@noticetype {#1}%
% set parameters of heavybox/lightbox
% set the parameters common to lightbox and heavybox environments
\sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
\sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
\spx@notice@border \dimexpr\csname spx@#1@border\endcsname\relax
% start specific environment, passing the heading as argument
% trigger the sphinx<type> environment, #2=heading is passed as argument
\begin{sphinx#1}{#2}}
% workaround some LaTeX "feature" of \end command
{\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
% workaround some LaTeX "feature" of \end command (can't use "sphinx#1" here)
{\expanded{\noexpand\end{sphinx\spx@noticetype}}}
\endinput