diff --git a/CHANGES.rst b/CHANGES.rst index fae64268a22..ac359fc8cba 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -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' + ` 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 ---------- diff --git a/bindep.txt b/bindep.txt index 2c67a766f1b..88470492b35 100644 --- a/bindep.txt +++ b/bindep.txt @@ -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] diff --git a/doc/latex.rst b/doc/latex.rst index 952d7dfa159..d6855021c8b 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -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`` +.. important:: + + 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._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 two horizontal rules used by Sphinx in LaTeX for styling - a :dudir:`note` type admonition. + The color for the admonition border. + + Default: ``{RGB}{134,152,155}``. - Default: ``{rgb}{0,0,0}`` (black) + .. 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 + .. versionchanged:: 7.4.0 + |notetextcolors| - The optional color for the contents. + The color for the admonition contents. - Default: unset (uses ambient text color, a priori black) + 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}{148,0,0}`` except for ``error`` which uses ``red``. - Default: ``{rgb}{0,0,0}`` (black) + .. versionchanged:: 7.4.0 .. only:: latex |wgbdcolorslatex| - The color for the admonition frame. + The color for the admonition border. + + Default: ``{RGB}{148,0,0}`` except for ``error`` which uses ``red``. - Default: ``{rgb}{0,0,0}`` (black) + .. 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:: ... - 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 ... * 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.``, ``sphinx`` (using ``sphinxheavybox``) + :dudir:`note`, ``div.note``, ``sphinxnote`` + :dudir:`warning`, ``div.warning``, ``sphinxwarning`` + further admonition types ````, ``div.``, ``sphinx`` + :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 ```` 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`. - ``_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. | ``_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``. - | ``_border-top-left-radius``, | ``_border-top-right-radius``, | ``_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: + + * ``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 - * ``\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. + :dudir:`topic` and :dudir:`note`\ -like admonitions acquire (at least one) + rounded corners. See a remark above about traps with spaces in LaTeX. - ``_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._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 ``\sphinxstyletitle`` 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._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._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' ` 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}`` - ``\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``. diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index 9c538ee85d5..082de794a03 100644 --- a/doc/usage/builders/index.rst +++ b/doc/usage/builders/index.rst @@ -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' + ` ``iconpackage`` key for more. + Additional packages are needed in some circumstances: * ``texlive-lang-cyrillic`` for Cyrillic (and also then diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py index 1962328d766..94473e7b838 100644 --- a/sphinx/ext/todo.py +++ b/sphinx/ext/todo.py @@ -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: diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 6c31f329c65..633b244e180 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -3,10 +3,13 @@ % % Adapted from the old python.sty, mostly written by Fred Drake, % by Georg Brandl. -% +% This has now grown to become a full-fledged LaTeX support, split +% among multiple files, some of which provide features unavailable +% from usual LaTeX packages in interaction with the mark-up produced +% by the Sphinx LaTeX writer. \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2023/03/19 v6.2.0 LaTeX package (Sphinx markup)] +\ProvidesPackage{sphinx}[2024/07/01 v7.4.0 Sphinx LaTeX package (sphinx-doc)] % provides \ltx@ifundefined % (many packages load ltxcmds: graphicx does for pdftex and lualatex but @@ -34,26 +37,26 @@ } %% important build warnings use an undefined reference to induce latexmk %% into complaining (once per warning) at very end of console output -\newcommand\sphinxbuildwarning[1]{% - \ifcsname sphinx_emitted_#1\endcsname +\newcommand\sphinxbuildwarning[2][]{% + \ifcsname sphinx_emitted_#2\endcsname \else - \global\expandafter\let\csname sphinx_emitted_#1\endcsname\@empty + \global\expandafter\let\csname sphinx_emitted_#2\endcsname\@empty \AtEndDocument{\hbox{% should the printing of text be made conditional on - % some boolean? + % some boolean? (7.4.0 answers this by adding an + % optional argument and testing it here for emptiness + % but no usage is made of this novelty yet.) + \if\relax\detokenize{#1}\relax + % No [], print a red warning text at very end of document \bfseries\color{red}% - \@nameuse{sphinx_buildwarning_#1}% + \@nameuse{sphinx_buildwarning_#2}% + \fi % place an undefined reference deliberately \let\nfss@text\@gobble % no ?? - \ref{!!\@nameuse{sphinx_buildwarning_#1}}% - }}% + \ref{!!\@nameuse{sphinx_buildwarning_#2}}% + }% + }% \fi } -\@namedef{sphinx_buildwarning_coloursyntax}{% - The colours whose definition used xcolor syntax were set to white - as xcolor was not found; check the latex log warnings for details} -\@namedef{sphinx_buildwarning_colorblend}{% - Command \string\sphinxcolorblend\space seen but ignored in tables - as xcolor was not found; check the latex log warnings for details} \@namedef{sphinx_buildwarning_badtitlesec}{% Your system has titlesec version 2.10.1 which causes disappearance of section numbers; check the latex log warning for details} @@ -63,29 +66,28 @@ \@namedef{sphinx_buildwarning_badfootnotes}{% Footnote rendering may have had problems, due to extra package or document class; check latex log for instructions}% - +\@namedef{sphinx_buildwarning_badiconpackage}{% + You have set iconpackage=\spx@opt@iconpackage, but this LaTeX package + is not found}% %% OPTION HANDLING % - % We generally first handle options then load packages, but we need -% \definecolor from xcolor/color to handle the options. +% \definecolor and \colorlet from xcolor to handle the options. +% Support for colour options +% -------------------------- +% At 7.4.0, package xcolor is required (which has allowed to get rid of +% annoying fall-back branches). Internals here got refactored to some extent. +% % MEMO: xcolor \fcolorbox coloured boxes render better in some PDF viewers % than with color package \fcolorbox. Since 1.6.3, Sphinx uses only its own % custom variant of \fcolorbox when handling code-blocks. But \fcolorbox -% appears also in Pygmentize output mark-up. Also, since 5.3.0, 'sphinxsetup' -% color options get a richer input syntax if Sphinx knows xcolor is loaded, -% and the \sphinxcolorblend (for tables) is made available only if xcolor is -% loaded. -\IfFileExists{xcolor.sty}{ +% appears also in Pygmentize output mark-up. % Should Sphinx load xcolor with its dvipsnames and svgnames options? - \RequirePackage{xcolor} -}{ - \RequirePackage{color} -} +\RequirePackage{xcolor} -% the \colorlet of xcolor (if at all loaded) is overkill for most internal use +% the \colorlet of xcolor is overkill for our internal usage here \newcommand{\sphinxcolorlet}[2] {\expandafter\let\csname\@backslashchar color@#1\expandafter\endcsname \csname\@backslashchar color@#2\endcsname } @@ -93,6 +95,8 @@ % (5.3.0) Allow colour options to use both the \definecolor and the \colorlet % syntaxes, for example VerbatimColor={gray}{0.9} or VerbatimColor=red!10 % In the latter case we need the real \colorlet from xcolor package. +% Prior to 7.4.0 xcolor was not required and thus \spx@colorlet was configured +% to raise a warning in case of absence of xcolor. \def\spx@defineorletcolor#1{% \def\spx@definedcolor{{#1}}% \futurelet\spx@token\spx@defineorlet} @@ -101,21 +105,17 @@ \expandafter\spx@definecolor\else\expandafter\spx@colorlet\fi} \def\spx@colorlet#1\relax{\expandafter\colorlet\spx@definedcolor{#1}} \def\spx@definecolor{\expandafter\definecolor\spx@definedcolor} -% -\@ifpackageloaded{xcolor}% - {}% - {% xcolor not loaded because it was not found in the LaTeX installation -\def\spx@colorlet#1\relax{% - \sphinxbuildwarning{coloursyntax}% - \PackageWarning{sphinx}{% -Sorry, the #1 syntax requires package xcolor,\MessageBreak -which was not found on your TeX/LaTeX installation.\MessageBreak -\@spaces\expandafter\@firstofone\spx@definedcolor\MessageBreak -will be set to white}% - \expandafter\definecolor\spx@definedcolor{rgb}{1,1,1}% - }% end of redefinition of \spx@colorlet - }% end of xcolor not found branch - +% These internals refactored at 7.4.0: +\newcommand*{\spx@DeclareColorOption}[3][]{% +% #1 = almost always "sphinx" but left empty for a few for legacy reasons +% #2 = option name, but internal colour name is #1#2 (i.e. with prefix) +% #3 = initial default colour with either \definecolor or \colorlet syntax + % Set the initial default + \spx@defineorletcolor{#1#2}#3\relax + % Set the key handler to accept both \definecolor and \colorlet syntax + % The key name does not have the #1 prefix from the colour name + \define@key{sphinx}{#2}{\spx@defineorletcolor{#1#2}##1\relax}% +}% % Handle options via "kvoptions" (later loaded by hyperref anyhow) \RequirePackage{kvoptions} @@ -159,10 +159,15 @@ will be set to white}% \define@key{sphinx}{bookmarksdepth}{\AtBeginDocument{\hypersetup{bookmarksdepth=#1}}} \AtBeginDocument{\define@key{sphinx}{bookmarksdepth}{\hypersetup{bookmarksdepth=#1}}} % \DeclareBoolOption[false]{usespart}% not used + +% Code-blocks +% ----------- +% % INFO: the keys for padding and border widths were extended at 5.1.0, % and legacy names for user interface were kept, but their definitions % are delayed further down. The legacy internally used dimen registers % \sphinxverbatimborder and \sphinxverbatimsep got removed at 6.2.0. +% More code-blocks related options are found in "CSS" part below. \DeclareBoolOption[true]{verbatimwithframe} \DeclareBoolOption[true]{verbatimwrapslines} \DeclareBoolOption[false]{verbatimforcewraps} @@ -180,70 +185,50 @@ will be set to white}% \DeclareStringOption % must use braces to hide the brackets [{\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\m@th\hookrightarrow$}}}]% {verbatimcontinued} -% topic boxes + +% Topic boxes +% ----------- % % 5.1.0 added new keys for configuration. The legacy keys shadowsep, -% shadowsize, shadowrule were kept for backward compatibility. Unfortunately -% this had bugs due to typos, which got fixed later at 6.1.2. +% shadowsize, shadowrule were kept for backward compatibility. +% 5.1.2 fixed some bugs. % % All configuration is now to be found in the "CSS" section below. % -% \sphinxshadowsep, \sphinxshadowsize, \sphinxshadowrule \dimen registers -% became at 5.1.0 either no-op or, for the latter, were used under an aliased -% name. They got removed at 6.2.0. -% -% notices/admonitions -% -% 5.1.0 added much customizability to warning, caution, attention, danger and -% error types of notices via an enhanced sphinxheavybox environment. -% -% 6.2.0 added the possibility to use the same kind of rendering also for -% note, hint, important, and tip. -% -% Legacy user interface for options was kept working. All of it is handled in -% the "CSS" section below. -% -% These 6.2.0 added booleans 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 +% 6.2.0 removed \sphinxshadowsep, \sphinxshadowsize, \sphinxshadowrule +% \dimen registers + +% Footnotes +% --------- \DeclareStringOption[\mbox{ }]{AtStartFootnote} % we need a public macro name for direct use in latex file \newcommand*{\sphinxAtStartFootnote}{\spx@opt@AtStartFootnote} % no such need for this one, as it is used inside other macros \DeclareStringOption[\leavevmode\unskip]{BeforeFootnote} -% some font styling. + +% Some font styling +% ----------------- +% TODO: the replacement of old syntax \py@HeaderFamily as used +% in sphinxlatexstyle{page,headings}.sty and sphinx{manual,howto}.cls +% has never been really put in place. Hence this isolated tidbit here. \DeclareStringOption[\sffamily\bfseries]{HeaderFamily} -% colours -% same problems as for dimensions: we want the key handler to use \definecolor. -% first, some colours with no prefix, for backward compatibility -\newcommand*{\sphinxDeclareColorOption}[2]{% - % set the initial default; only \definecolor syntax for defaults! - \definecolor{#1}#2% - % set the key handler to accept both \definecolor and \colorlet syntax - \define@key{sphinx}{#1}{\spx@defineorletcolor{#1}##1\relax}% -}% -\sphinxDeclareColorOption{TitleColor}{{rgb}{0.126,0.263,0.361}} -\sphinxDeclareColorOption{InnerLinkColor}{{rgb}{0.208,0.374,0.486}} -\sphinxDeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}} -\sphinxDeclareColorOption{VerbatimColor}{{gray}{0.95}} -\sphinxDeclareColorOption{VerbatimBorderColor}{{RGB}{32,32,32}} -% all other colours will be named with a "sphinx" prefix -\newcommand*{\sphinxDeclareSphinxColorOption}[2]{% - % set the initial default; only \definecolor syntax for defaults! - \definecolor{sphinx#1}#2% - % set the key handler to accept both \definecolor and \colorlet syntax - \define@key{sphinx}{#1}{\spx@defineorletcolor{sphinx#1}##1\relax}% -}% -% table row colors -\sphinxDeclareSphinxColorOption{TableRowColorHeader}{{gray}{0.86}} -\sphinxDeclareSphinxColorOption{TableRowColorOdd}{{gray}{0.92}} -\sphinxDeclareSphinxColorOption{TableRowColorEven}{{gray}{0.98}} + +% Some legacy colour options +% -------------------------- +% +\spx@DeclareColorOption{TitleColor}{{rgb}{0.126,0.263,0.361}} +\spx@DeclareColorOption{InnerLinkColor}{{rgb}{0.208,0.374,0.486}} +\spx@DeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}} +% The Verbatim ones are "legacy" only since 5.1.0... call it "new-legacy" ;-) +\spx@DeclareColorOption{VerbatimColor}{{RGB}{242,242,242}}% same as {gray}{0.95} +\spx@DeclareColorOption{VerbatimBorderColor}{{RGB}{32,32,32}} +% All other colours will be internally assigned a "sphinx" prefix + +% Table row colors (since 6.0.0) +% ---------------- +\spx@DeclareColorOption[sphinx]{TableRowColorHeader}{{gray}{0.86}} +\spx@DeclareColorOption[sphinx]{TableRowColorOdd}{{gray}{0.92}} +\spx@DeclareColorOption[sphinx]{TableRowColorEven}{{gray}{0.98}} % if not set, the "Merge" colour will keep in sync with the "Row" colour \def\sphinxTableMergeColorHeader{sphinxTableRowColorHeader} \define@key{sphinx}{TableMergeColorHeader}{% @@ -261,37 +246,67 @@ will be set to white}% \def\sphinxTableMergeColorEven{sphinxTableMergeColorEven}% }% % 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}} -\sphinxDeclareSphinxColorOption{dangerBorderColor}{{rgb}{0,0,0}} -\sphinxDeclareSphinxColorOption{errorBorderColor}{{rgb}{0,0,0}} -% BgColor should have been from the start BackgroundColor for better -% match with CSS property names, but this is legacy interface -% which is too late to change because the internal color names -% and not only the option names have been documented at user level. -\sphinxDeclareSphinxColorOption{warningBgColor}{{rgb}{1,1,1}} -\sphinxDeclareSphinxColorOption{cautionBgColor}{{rgb}{1,1,1}} -\sphinxDeclareSphinxColorOption{attentionBgColor}{{rgb}{1,1,1}} -\sphinxDeclareSphinxColorOption{dangerBgColor}{{rgb}{1,1,1}} -\sphinxDeclareSphinxColorOption{errorBgColor}{{rgb}{1,1,1}} +\spx@DeclareColorOption[sphinx]{VerbatimHighlightColor}{{rgb}{0.878,1,1}} + +% Notices/admonitions +% ------------------- +% +% 5.1.0 added much customizability to warning, caution, attention, danger and +% error types of notices via an enhanced sphinxheavybox environment. +% +% 6.2.0 added the possibility to use the same kind of rendering also for +% note, hint, important, and tip. +% +% Legacy user interface for options was kept working. All of it is handled in +% the "CSS" section below. +% +% 6.2.0 added booleans to serve internally as a record of whether the +% note, hint, important and tip admonitions used the legacy "lightbox" or +% the then enhanced "heavybox" environment. +% +% 7.4.0 uses "heavybox" environment from sphinxlatexadmonitions in all cases, +% hence the booleans mentioned above have been removed as well as the rather +% complex TeX code which was done so that these booleans were made true if +% and only if the CSS-named keys had been made usage of via 'sphinxsetup'. +% +% The "light style" implemented in sphinxlatexadmonitions.sty as +% "sphinxlightbox" is not used. Also, admonitions by default have a "title +% row", and the corresponding options are only named in the CSS style which is +% implemented further below. Here we define options having a legacy name. +% +% seealso directive is also using "heavybox" at 7.4.0 acquiring the same +% customizability as admonitions. +% todo directive also. +\definecolor{sphinx-admonition-bgcolor} {RGB}{247, 247, 247}% #F7F7F7 +\definecolor{sphinx-admonition-bordercolor} {RGB}{134, 152, 155}% #86989B +\definecolor{sphinx-warning-bordercolor} {RGB}{148, 0, 0}% #940000 +\definecolor{sphinx-error-bordercolor} {RGB}{180, 0, 0}% #B40000 +\spx@DeclareColorOption[sphinx]{noteBorderColor} {sphinx-admonition-bordercolor} +\spx@DeclareColorOption[sphinx]{hintBorderColor} {sphinx-admonition-bordercolor} +\spx@DeclareColorOption[sphinx]{importantBorderColor}{sphinx-admonition-bordercolor} +\spx@DeclareColorOption[sphinx]{tipBorderColor} {sphinx-admonition-bordercolor} +\spx@DeclareColorOption[sphinx]{seealsoBorderColor} {sphinx-admonition-bordercolor}% 7.4.0 +\spx@DeclareColorOption[sphinx]{todoBorderColor} {sphinx-admonition-bordercolor}% 7.4.0 +% +\spx@DeclareColorOption[sphinx]{noteBgColor} {sphinx-admonition-bgcolor} +\spx@DeclareColorOption[sphinx]{hintBgColor} {sphinx-admonition-bgcolor} +\spx@DeclareColorOption[sphinx]{importantBgColor}{sphinx-admonition-bgcolor} +\spx@DeclareColorOption[sphinx]{tipBgColor} {sphinx-admonition-bgcolor} +\spx@DeclareColorOption[sphinx]{seealsoBgColor} {sphinx-admonition-bgcolor}% 7.4.0 +\spx@DeclareColorOption[sphinx]{todoBgColor} {sphinx-admonition-bgcolor}% 7.4.0 +% +\spx@DeclareColorOption[sphinx]{warningBorderColor} {sphinx-warning-bordercolor} +\spx@DeclareColorOption[sphinx]{cautionBorderColor} {sphinx-warning-bordercolor} +\spx@DeclareColorOption[sphinx]{attentionBorderColor}{sphinx-warning-bordercolor} +\spx@DeclareColorOption[sphinx]{dangerBorderColor} {sphinx-warning-bordercolor} +\spx@DeclareColorOption[sphinx]{errorBorderColor} {sphinx-error-bordercolor} +% +\spx@DeclareColorOption[sphinx]{warningBgColor} {sphinx-admonition-bgcolor} +\spx@DeclareColorOption[sphinx]{cautionBgColor} {sphinx-admonition-bgcolor} +\spx@DeclareColorOption[sphinx]{attentionBgColor}{sphinx-admonition-bgcolor} +\spx@DeclareColorOption[sphinx]{dangerBgColor} {sphinx-admonition-bgcolor} +\spx@DeclareColorOption[sphinx]{errorBgColor} {sphinx-admonition-bgcolor} +% %%%%%%%% % % Additions of CSS-like keys at 5.1.0 (and possibility of rounded boxes) @@ -324,14 +339,25 @@ will be set to white}% % finally been removed entirely. No more \dimen register is used here only % storage in macros. % +% Restyling at 7.4.0 with new defaults for all admonition types +% ------------------------------------------------------------- +% +% So far the 5.1.0 added possibilities for fancier boxes had been used by +% default only for code-blocks, and admonitions kept their old-fashioned +% legacy styles. At 7.4.0, as a follow-up to the revamped styles of +% admonitions in the HTML sphinx13 theme (PR #12439), it is decided to +% apply similar styling for PDF output. Also the seealso directive +% is handled as an admonition with the same customizability. And the +% todo directive. +% \def\spxstring@none{none} \def\spxstring@clone{clone} % % Border keys -% +% At 7.4.0 refactoring to avoid defining legacy \spx@@border +% macros which are (now) used nowhere, only @top, @right, @bottom, @left. \def\spx@tempa#1{% #1 = macro prefix \expandafter\spx@tempb - \csname #1border\expandafter\endcsname \csname #1border@top\expandafter\endcsname \csname #1border@right\expandafter\endcsname \csname #1border@bottom\expandafter\endcsname @@ -340,99 +366,100 @@ will be set to white}% \csname #1border@opentrue\expandafter\endcsname \csname #1border@openfalse\endcsname }% -\def\spx@tempb #1#2#3#4#5#6#7#8#9{% #9 = option prefix - \define@key{sphinx}{#9border-top-width}{\def#2{##1}}% - \define@key{sphinx}{#9border-right-width}{\def#3{##1}}% - \define@key{sphinx}{#9border-bottom-width}{\def#4{##1}}% - \define@key{sphinx}{#9border-left-width}{\def#5{##1}}% - \define@key{sphinx}{#9border-width}{% - \def#1{##1}% MEMO: not immediately expanded, should this be changed? - \def#2{#1}\let#3#2\let#4#2\let#5#2% +\def\spx@tempb #1#2#3#4#5#6#7#8#9{% #8 = option prefix + \define@key{sphinx}{#8border-top-width}{\def#1{##1}}% + \define@key{sphinx}{#8border-right-width}{\def#2{##1}}% + \define@key{sphinx}{#8border-bottom-width}{\def#3{##1}}% + \define@key{sphinx}{#8border-left-width}{\def#4{##1}}% + \define@key{sphinx}{#8border-width}{% + % MEMO: not immediately expanded, should this be changed? + \def#1{##1}\let#2#1\let#3#1\let#4#1% }% - \newif#6% - \define@key{sphinx}{#9box-decoration-break}% + \newif#5% + % 6.2.0 has added support for box-decoration-break also to admonition + % directives, formerly the option setting was ignored for them. + \define@key{sphinx}{#8box-decoration-break}% {\begingroup\edef\spx@tempa{##1}\expandafter\endgroup - \ifx\spx@tempa\spxstring@clone#8\else#7\fi}% - \spx@tempc{#9}% option prefix -} -\def\spx@tempc #1#2{% #1 = option prefix, #2 = legacy option name + \ifx\spx@tempa\spxstring@clone#7\else#6\fi}% + % 7.4.0 sets the default behaviour to "slice" not only for code-blocks but + % also for admonitions, as the latter now have a background colour each. + #6% + % #8 = option prefix (with underscore), #9 = legacy option name % keep legacy option names as aliases to new-named options - \expandafter\let\csname KV@sphinx@#2\expandafter\endcsname - \csname KV@sphinx@#1border-width\endcsname + \expandafter\let\csname KV@sphinx@#9\expandafter\endcsname + \csname KV@sphinx@#8border-width\endcsname % init border-width (fetches next argument) - \csname KV@sphinx@#1border-width\endcsname + \csname KV@sphinx@#8border-width\endcsname } -% MEMO: prior to 6.2.0 the \fboxrule value (0.4pt, a priori) was frozen here via -% a \dimen assignment done immediately. Now it remains \fboxrule until being used. +% MEMO: from 6.2.0 to 7.4.0 (excluive) \fboxrule was used in the first +% two, and was resolved only at location of use. At 7.4.0, we again +% use 0.4pt rather and not \fboxrule dimen register. % 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@pre@} {pre_} {verbatimborder} {0.4pt} +\spx@tempa{spx@topic@} {div.topic_} {shadowrule} {0.5pt}% mod. at 7.4.0 \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@seealso@} {div.seealso_} {seealsoborder} {0.5pt}% new at 7.4.0 +\spx@tempa{spx@todo@} {div.todo_} {todoborder} {0.5pt}% new at 7.4.0 \spx@tempa{spx@warning@} {div.warning_} {warningborder} {1pt} \spx@tempa{spx@caution@} {div.caution_} {cautionborder} {1pt} \spx@tempa{spx@attention@}{div.attention_}{attentionborder}{1pt} \spx@tempa{spx@danger@} {div.danger_} {dangerborder} {1pt} -\spx@tempa{spx@error@} {div.error_} {errorborder} {1pt} +\spx@tempa{spx@error@} {div.error_} {errorborder} {1.25pt}% mod. at 7.4.0 % this one new at 6.2.0: (we do not create a "legacy name" for it) -\spx@tempa{spx@box@} {box_} {box_border-width}\fboxrule -% Set default box-decoration-break style for codeblocks to slice -\spx@pre@border@opentrue % new default at 6.0.0: slice, not clone -% 6.2.0 has added support for box-decoration-break=slice to all -% other directives, formerly the option setting was ignored for them. +\spx@tempa{spx@box@} {box_} {box_border-width}{0.4pt} +% Reset default box-decoration-break style to "clone" for \sphinxbox, +% but anyhow this is ignored as \sphinxbox produces unbreakable boxes. +\spx@box@border@openfalse % Padding keys -% +% At 7.4.0, \spx@@padding internal macros removed, only @top, @right, +% @bottom, @left are actually needed by sphinxpackageboxes.sty. \def\spx@tempa#1{% \expandafter\spx@tempb - \csname #1padding\expandafter\endcsname \csname #1padding@top\expandafter\endcsname \csname #1padding@right\expandafter\endcsname \csname #1padding@bottom\expandafter\endcsname \csname #1padding@left\endcsname }% -\def\spx@tempb #1#2#3#4#5#6{% #6 = option prefix - \define@key{sphinx}{#6padding-top}{\def#2{##1}}% - \define@key{sphinx}{#6padding-right}{\def#3{##1}}% - \define@key{sphinx}{#6padding-bottom}{\def#4{##1}}% - \define@key{sphinx}{#6padding-left}{\def#5{##1}}% - \define@key{sphinx}{#6padding}{% - \def#1{##1}% - \def#2{#1}\let#3#2\let#4#2\let#5#2% +\def\spx@tempb #1#2#3#4#5#6#7#8#9{% #5 = option prefix + \define@key{sphinx}{#5padding-top}{\def#1{##1}}% + \define@key{sphinx}{#5padding-right}{\def#2{##1}}% + \define@key{sphinx}{#5padding-bottom}{\def#3{##1}}% + \define@key{sphinx}{#5padding-left}{\def#4{##1}}% + \define@key{sphinx}{#5padding}{% + \def#1{##1}\let#2#1\let#3#1\let#4#1% }% - % initialization (will fetch "init" argument next): - \csname KV@sphinx@#6padding\endcsname + % initial defaults + \def#1{#6}\def#2{#7}\def#3{#8}\def#4{#9}% } % MEMO: prior to 6.2.0 the \fboxsep value (3pt, a priori) was frozen here via -% a \dimen assignment done immediately. Now it remains \fboxsep until being used. -% #1 macro prefix #6 option prefix init value -\spx@tempa{spx@pre@} {pre_} \fboxsep -\spx@tempa{spx@topic@} {div.topic_} {5pt} -% 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 acquired such interface and the default is set as for legacy -% default of "warning" type. I hesitated using \fboxsep, but if I did I would -% then need to explain how to change "note etc..." into behaving exactly -% as "warning etc...", which goes via the \dimexpr here which is too scary to -% put sanely into documentation. -\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 (so that it dynamically adapts to the border width setting). -% MEMO: I could use everywhere \spx@notice@border, as sphinxadmonition environment -% configures it to hold the \spx@@border value. -\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} -\spx@tempa{spx@danger@} {div.danger_} {\dimexpr.6\baselineskip-\spx@danger@border\relax} -\spx@tempa{spx@error@} {div.error_} {\dimexpr.6\baselineskip-\spx@error@border\relax} -\spx@tempa{spx@box@} {box_} \fboxsep +% a \dimen assignment done immediately. From 6.2.0 to 7.4.0 an unfrozen +% \fboxsep was used, and at 7.4.0 it is again explicit 3pt. +% The defaults for admonitions were all modified at 7.4.0. +% For topic/contents and all admonitions the horizontal padding plus borders +% are put inside the text area (i.e. do not go into the margins). +% In order for perfect exact same vertical alignment of contents from all such +% directives, the value of horizontal border-width+padding is kept constant +% (equal to 7.5pt since 7.4.0). +% #1 macro prefix #6 option prefix top right bottom left +\spx@tempa{spx@pre@} {pre_} {3pt}{3pt}{3pt}{3pt} +\spx@tempa{spx@topic@} {div.topic_} {10pt}{7pt}{12pt}{7pt} +% 7.4.0 drops legacy settings which linked strangely padding with border width +\spx@tempa{spx@note@} {div.note_} {6pt}{7pt}{6pt}{7pt} +\spx@tempa{spx@hint@} {div.hint_} {6pt}{7pt}{6pt}{7pt} +\spx@tempa{spx@important@}{div.important_} {6pt}{7pt}{6pt}{7pt} +\spx@tempa{spx@tip@} {div.tip_} {6pt}{7pt}{6pt}{7pt} +\spx@tempa{spx@seealso@} {div.seealso_} {6pt}{7pt}{6pt}{7pt} +\spx@tempa{spx@todo@} {div.todo_} {6pt}{7pt}{6pt}{7pt} +\spx@tempa{spx@warning@} {div.warning_} {6pt}{6.5pt}{6pt}{6.5pt} +\spx@tempa{spx@caution@} {div.caution_} {6pt}{6.5pt}{6pt}{6.5pt} +\spx@tempa{spx@attention@}{div.attention_} {6pt}{6.5pt}{6pt}{6.5pt} +\spx@tempa{spx@danger@} {div.danger_} {6pt}{6.5pt}{6pt}{6.5pt} +\spx@tempa{spx@error@} {div.error_} {6pt}{6.25pt}{6pt}{6.25pt} +\spx@tempa{spx@box@} {box_} {3pt}{3pt}{3pt}{3pt} % define legacy verbatimsep key as alias of pre_padding key \expandafter\let\expandafter\KV@sphinx@verbatimsep\csname KV@sphinx@pre_padding\endcsname % define legacy shadowsep key as alias of div.topic_padding key @@ -450,30 +477,35 @@ will be set to white}% \csname #1radius@bottomright\expandafter\endcsname \csname #1radius@bottomleft\endcsname }% -\def\spx@tempb #1#2#3#4#5{% #5 = option prefix +\def\spx@tempb #1#2#3#4#5#6#7#8#9{% #5 = option prefix \define@key{sphinx}{#5border-top-left-radius}{\def#1{##1}}% \define@key{sphinx}{#5border-top-right-radius}{\def#2{##1}}% \define@key{sphinx}{#5border-bottom-right-radius}{\def#3{##1}}% \define@key{sphinx}{#5border-bottom-left-radius}{\def#4{##1}}% \define@key{sphinx}{#5border-radius}{\def#1{##1}\let#2#1\let#3#1\let#4#1}% - \csname KV@sphinx@#5border-radius\endcsname % fetches next argument + \def#1{#6}\def#2{#7}\def#3{#8}\def#4{#9}% } % The init value for corner radius in code-blocks was \z@ (i.e. 0pt) prior -% to 6.0.0., then 3pt, then \fboxsep at 6.2.0 as padding is \fboxsep, -% and \fboxsep=3pt per default (also with platex). -% macro prefix option prefix init value -\spx@tempa{spx@pre@} {pre_} \fboxsep -\spx@tempa{spx@topic@} {div.topic_} \z@ -\spx@tempa{spx@note@} {div.note_} \z@ -\spx@tempa{spx@hint@} {div.hint_} \z@ -\spx@tempa{spx@important@}{div.important_} \z@ -\spx@tempa{spx@tip@} {div.tip_} \z@ -\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_} \fboxsep +% to 6.0.0., then 3pt, then \fboxsep at 6.2.0 as padding was also \fboxsep. +% At 7.4.0: +% - the 3pt is used (which is normal value of \fboxsep). +% - some admonitions use rounded corners as well. +% - topic boxed have only their bottom right corner rounded. +% macro prefix option prefix tl tr br bl +\spx@tempa{spx@pre@} {pre_} {3pt}{3pt}{3pt}{3pt} +\spx@tempa{spx@topic@} {div.topic_} \z@ \z@ {12pt} \z@ +\spx@tempa{spx@note@} {div.note_} {5pt}{5pt}{5pt}{5pt} +\spx@tempa{spx@hint@} {div.hint_} {5pt}{5pt}{5pt}{5pt} +\spx@tempa{spx@important@}{div.important_} \z@\z@\z@\z@ +\spx@tempa{spx@tip@} {div.tip_} {5pt}{5pt}{5pt}{5pt} +\spx@tempa{spx@seealso@} {div.seealso_} \z@\z@\z@\z@ +\spx@tempa{spx@todo@} {div.todo_} \z@\z@\z@\z@ +\spx@tempa{spx@warning@} {div.warning_} \z@\z@\z@\z@ +\spx@tempa{spx@caution@} {div.caution_} \z@\z@\z@\z@ +\spx@tempa{spx@attention@}{div.attention_} \z@\z@\z@\z@ +\spx@tempa{spx@danger@} {div.danger_} \z@\z@\z@\z@ +\spx@tempa{spx@error@} {div.error_} \z@\z@\z@\z@ +\spx@tempa{spx@box@} {box_} {3pt}{3pt}{3pt}{3pt} % Shadow keys % @@ -494,6 +526,8 @@ will be set to white}% \spx@tempa{spx@hint@} \spx@tempa{spx@important@} \spx@tempa{spx@tip@} +\spx@tempa{spx@seealso@}% 7.4.0 +\spx@tempa{spx@todo@}% 7.4.0 \spx@tempa{spx@warning@} \spx@tempa{spx@caution@} \spx@tempa{spx@attention@} @@ -541,6 +575,8 @@ will be set to white}% \spx@tempa{spx@hint@} {div.hint_} \spx@tempa{spx@important@}{div.important_} \spx@tempa{spx@tip@} {div.tip_} +\spx@tempa{spx@seealso@} {div.seealso_} +\spx@tempa{spx@todo@} {div.todo_} \spx@tempa{spx@warning@} {div.warning_} \spx@tempa{spx@caution@} {div.caution_} \spx@tempa{spx@attention@}{div.attention_} @@ -552,7 +588,6 @@ will be set to white}% % This definition was broken due to a typo at 5.1.0 and got fixed at 6.1.2 % MEMO: at 6.2.0 this no longer does \number\dimexpr in an \edef. Reason is to % keep in sync with div.topic_box-shadow handling of xoffset and yoffset. -% Attention in particular to \ifdim context, we add a \dimexpr to the one here. \define@key{sphinx}{shadowsize}{% \def\spx@topic@shadow@xoffset{#1}% \let\spx@topic@shadow@yoffset\spx@topic@shadow@xoffset @@ -564,8 +599,9 @@ will be set to white}% \fi }% -% Color keys -% (four of them: border, background, shadow and the text color) +% Color keys, TeXextras key, keys for admonition titles with icon +% +% Historical remarks to be removed at some point: % % Some problems due to legacy naming scheme which had diverging conventions % for code-blocks (VerbatimBorderColor, VerbatimColor) and admonitions @@ -574,27 +610,31 @@ will be set to white}% % example sphinxwarningBgColor are also documented at user level, they are not % only internally used. % -% For topic directive, "legacy" (by this I mean Sphinx around 2016-2017 after -% my first additions to LaTeX) had no interface for colors, so I could change -% some internals with no breakage during 5.x up to 6.2.0. So topic -% (shadowbox) could be unified with admonitions (sphinxheavybox), and the -% "set-up" macros could all be moved into a single one in the -% sphinxpackageboxes.sty file, with only one argument holding the directive -% type. +% For topic directive, "legacy" (around 2016-2017) had no interface for +% colours, so some internals could be changed with no breakage during 5.x up +% to 6.2.0. For example topic (shadowbox) could be unified with admonitions +% (sphinxheavybox), and the "setup" macros could all be moved into a single +% one in the sphinxpackageboxes.sty file, with only one argument holding the +% directive type. % -% It was then needed only for sphinxlatexliterals.sty to let its +% It was then needed only by sphinxlatexliterals.sty to let its emitted % \spx@verb@boxes@fcolorbox@setup incorporate some extra adjustment. % -% We associate a boolean to each color, so that the box code can -% decide to insert a \color command or consider it is not needed. +% 7.4.0 removes usages of booleans relative to usage of a colour for +% background or border which were there to optimize the boxing code from +% sphinxpackageboxes.sty when colours where not needed. These were internal +% macros so their removal should not be considered breaking. +% We keep the infrastructure for "shadowcolor" and "textcolor" because the +% defaults for them remain not to have specific colour. +% +% 7.4.0 adds keys for admonition titles: for background and foreground colors, +% and for icons (whose defaults are picked from Free Fontawesome 5). \def\spx@tempa#1{% \expandafter\spx@tempb \csname if#1withshadowcolor\expandafter\endcsname - \csname if#1withbordercolor\expandafter\endcsname - \csname if#1withbackgroundcolor\expandafter\endcsname \csname if#1withtextcolor\endcsname }% -\def\spx@tempb#1#2#3#4{\newif#1\newif#2\newif#3\newif#4}% +\def\spx@tempb#1#2{\newif#1\newif#2}% % macro prefix \spx@tempa{spx@pre@} \spx@tempa{spx@topic@} @@ -602,6 +642,8 @@ will be set to white}% \spx@tempa{spx@hint@} \spx@tempa{spx@important@} \spx@tempa{spx@tip@} +\spx@tempa{spx@seealso@} +\spx@tempa{spx@todo@} \spx@tempa{spx@warning@} \spx@tempa{spx@caution@} \spx@tempa{spx@attention@} @@ -611,29 +653,36 @@ will be set to white}% % \def\spx@tempa#1{% #1 = macro prefix \expandafter\spx@tempb - \csname #1withbordercolortrue\expandafter\endcsname - \csname #1withbackgroundcolortrue\expandafter\endcsname \csname #1withshadowcolortrue\expandafter\endcsname - \csname #1withtextcolortrue\endcsname + \csname #1withtextcolortrue\expandafter\endcsname + \csname #1TeXextras\endcsname } -\def\spx@tempb#1#2#3#4#5#6{% #5 = option prefix, #6 = color name prefix - \define@key{sphinx}{#5border-TeXcolor}% - {#1\spx@defineorletcolor{#6BorderColor}##1\relax}% - \define@key{sphinx}{#5background-TeXcolor}% - {#2\spx@defineorletcolor{#6BgColor}##1\relax}% - \define@key{sphinx}{#5box-shadow-TeXcolor}% - {#3\spx@defineorletcolor{#6ShadowColor}##1\relax}% - \define@key{sphinx}{#5TeXcolor}% - {#4\spx@defineorletcolor{#6TextColor}##1\relax}% +% 7.4.0 adds options for a title. They have an action only for admonitions, +% seealso and todo directives. +\def\spx@tempb#1#2#3#4#5{% #4 = option prefix, #5 = color name prefix + \define@key{sphinx}{#4border-TeXcolor}% + {\spx@defineorletcolor{#5BorderColor}##1\relax}% + \define@key{sphinx}{#4background-TeXcolor}% + {\spx@defineorletcolor{#5BgColor}##1\relax}% + \define@key{sphinx}{#4title-background-TeXcolor}% + {\spx@defineorletcolor{#5TtlBgColor}##1\relax}% + \define@key{sphinx}{#4title-foreground-TeXcolor}% + {\spx@defineorletcolor{#5TtlFgColor}##1\relax}% + \define@key{sphinx}{#4title-icon}% + {\@namedef{#5TtlIcon}{##1}}% + \define@key{sphinx}{#4box-shadow-TeXcolor}% + {#1\spx@defineorletcolor{#5ShadowColor}##1\relax}% + \define@key{sphinx}{#4TeXcolor}% + {#2\spx@defineorletcolor{#5TextColor}##1\relax}% + \define@key{sphinx}{#4TeXextras}% + {\def#3{##1}}% } % macro prefix option prefix color name prefix \spx@tempa{spx@pre@} {pre_} {Verbatim} % (memo: internal VerbatimShadowColor was formerly sphinxVerbatimShadowColor) % internal legacy color name is VerbatimColor not VerbatimBgColor, so redefine: \define@key{sphinx}{pre_background-TeXcolor}% - {\spx@pre@withbackgroundcolortrue\spx@defineorletcolor{VerbatimColor}#1\relax}% - \spx@pre@withbordercolortrue % 6.0.0 VerbatimBorderColor {RGB}{32,32,32} - \spx@pre@withbackgroundcolortrue % 6.0.0 VerbatimColor {gray}{0.95} + {\spx@defineorletcolor{VerbatimColor}#1\relax}% % Keep legacy option names working \expandafter\let\expandafter\KV@sphinx@VerbatimBorderColor \csname KV@sphinx@pre_border-TeXcolor\endcsname @@ -646,6 +695,8 @@ will be set to white}% \spx@tempa{spx@hint@} {div.hint_} {sphinxhint} \spx@tempa{spx@important@}{div.important_} {sphinximportant} \spx@tempa{spx@tip@} {div.tip_} {sphinxtip} +\spx@tempa{spx@seealso@} {div.seealso_} {sphinxseealso} +\spx@tempa{spx@todo@} {div.todo_} {sphinxtodo} \spx@tempa{spx@warning@} {div.warning_} {sphinxwarning} \spx@tempa{spx@caution@} {div.caution_} {sphinxcaution} \spx@tempa{spx@attention@}{div.attention_} {sphinxattention} @@ -666,11 +717,12 @@ will be set to white}% \spx@tempa{div.error_} {error} % Keep legacy sphinxsetup BorderColor for =note, hint, ... - % which will not trigger sphinxheavybox - % Add "legacy" hintTextColor etc... that will not trigger sphinxheavybox + % Add "legacy" names BgColor (added at 7.4.0) and TextColor \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 + \expandafter\let\csname KV@sphinx@#2BgColor\expandafter\endcsname + \csname KV@sphinx@#1background-TeXcolor\endcsname \expandafter\let\csname KV@sphinx@#2TextColor\expandafter\endcsname \csname KV@sphinx@#1TeXcolor\endcsname } @@ -679,28 +731,7 @@ will be set to white}% \spx@tempa{div.important_} {important} \spx@tempa{div.tip_} {tip} -% The TeXextras key -% -\def\spx@tempa#1{% #1 = macro prefix - \expandafter\spx@tempb\csname #1TeXextras\endcsname -} -\def\spx@tempb#1#2{% #2 = option prefix - \define@key{sphinx}{#2TeXextras}{\def#1{##1}}% -} -% macro prefix option prefix -\spx@tempa{spx@pre@} {pre_} -\spx@tempa{spx@topic@} {div.topic_} -\spx@tempa{spx@note@} {div.note_} -\spx@tempa{spx@hint@} {div.hint_} -\spx@tempa{spx@important@}{div.important_} -\spx@tempa{spx@tip@} {div.tip_} -\spx@tempa{spx@warning@} {div.warning_} -\spx@tempa{spx@caution@} {div.caution_} -\spx@tempa{spx@attention@}{div.attention_} -\spx@tempa{spx@danger@} {div.danger_} -\spx@tempa{spx@error@} {div.error_} -\spx@tempa{spx@box@} {box_} - % Add "legacy" hintTeXextras etc... that will not trigger sphinxheavybox + % Add "legacy" hintTeXextras etc... \def\spx@tempa#1#2{% #1 = CSS like option prefix, #2 = legacy option prefix \expandafter\let\csname KV@sphinx@#2TeXextras\expandafter\endcsname \csname KV@sphinx@#1TeXextras\endcsname @@ -710,64 +741,147 @@ will be set to white}% \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. + % At 7.4.0, let topic/contents boxes acquire background and border colours + % and give the shadow some colour other than black + \setkeys{sphinx}{div.topic_border-TeXcolor=sphinx-admonition-bordercolor, + div.topic_background-TeXcolor=sphinx-admonition-bgcolor, + div.topic_box-shadow-TeXcolor={RGB}{108,108,108}, + } + + +% 7.4.0 lets all types of admonitions style especially their titlss. +% The Sphinx default colours for admonition titles are copied from PR #12486 +% which modified sphinx13.css (see also earlier #12439) +% The actual code using the colours and icons whose defaults are set here +% is to be found in sphinxlatexadmonitions.sty. +% +% MEMO: unfortunately xcolor does NOT implement HSL but only HSB! +% So the sphinx13.css colours specified via hsl() got converted to RGB here +\definecolor{sphinx-admonition-title-bgcolor}{RGB}{229,229,229} % hsl(0, 0%, 90%); +\definecolor{sphinx-admonition-title-fgcolor}{RGB}{127,127,127} % hsl(0, 0%, 50%); +\definecolor{sphinx-warning-title-bgcolor} {RGB}{248,228,210} % hsl(28.5, 74%, 90%); +\definecolor{sphinx-warning-title-fgcolor} {RGB}{221,122,33} % hsl(28.5, 74%, 50%); +\definecolor{sphinx-note-title-bgcolor} {RGB}{208,222,250} % hsl(219.5, 84%, 90%); +\definecolor{sphinx-note-title-fgcolor} {RGB}{20,93,234} % hsl(219.5, 84%, 50%); +\definecolor{sphinx-success-title-bgcolor} {RGB}{220,239,230} % hsl(150, 36.7%, 90%); +\definecolor{sphinx-success-title-fgcolor} {RGB}{81,174,128} % hsl(150, 36.7%, 50%); +\definecolor{sphinx-error-title-bgcolor} {RGB}{238,220,220} % hsl(0, 37%, 90%); +\definecolor{sphinx-error-title-fgcolor} {RGB}{174,80,80} % hsl(0, 37%, 50%); +\definecolor{sphinx-todo-title-bgcolor} {RGB}{226,204,254} % hsl(266.8, 100%, 90%); +\definecolor{sphinx-todo-title-fgcolor} {RGB}{113,0,255} % hsl(266.8, 100%, 50%); + +% Now use the above colours as default settings, following the choices +% done in sphinx13.css +\setkeys{sphinx}{ + div.note_title-background-TeXcolor=sphinx-note-title-bgcolor, + div.note_title-foreground-TeXcolor=sphinx-note-title-fgcolor, +% + div.hint_title-background-TeXcolor=sphinx-success-title-bgcolor, + div.hint_title-foreground-TeXcolor=sphinx-success-title-fgcolor, + div.tip_title-background-TeXcolor=sphinx-success-title-bgcolor, + div.tip_title-foreground-TeXcolor=sphinx-success-title-fgcolor, + div.seealso_title-background-TeXcolor=sphinx-success-title-bgcolor, + div.seealso_title-foreground-TeXcolor=sphinx-success-title-fgcolor, + div.todo_title-background-TeXcolor=sphinx-todo-title-bgcolor, + div.todo_title-foreground-TeXcolor=sphinx-todo-title-fgcolor, +% + div.important_title-background-TeXcolor=sphinx-warning-title-bgcolor, + div.important_title-foreground-TeXcolor=sphinx-warning-title-fgcolor, + div.caution_title-background-TeXcolor=sphinx-warning-title-bgcolor, + div.caution_title-foreground-TeXcolor=sphinx-warning-title-fgcolor, + div.warning_title-background-TeXcolor=sphinx-warning-title-bgcolor, + div.warning_title-foreground-TeXcolor=sphinx-warning-title-fgcolor, % -% 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 -% div.note_border-TeXcolor and div.note_border-width, and to the noteBgColor -% etc... which are handled below. + div.attention_title-background-TeXcolor=sphinx-error-title-bgcolor, + div.attention_title-foreground-TeXcolor=sphinx-error-title-fgcolor, + div.danger_title-background-TeXcolor=sphinx-error-title-bgcolor, + div.danger_title-foreground-TeXcolor=sphinx-error-title-fgcolor, + div.error_title-background-TeXcolor=sphinx-error-title-bgcolor, + div.error_title-foreground-TeXcolor=sphinx-error-title-fgcolor, % -% This goes via rather hardcore TeX here. -\def\spx@tempa#1{\if\relax#1\expandafter\@gobble +% TODO: implement todo (sic) +% +} + +% 7.4.0 Support for icons in admonition titles +% We try to +% - get Sphinx PDF builds to process fine in absence of fontawesome5 +% - use fontawesome5 if present, but not if user prefers another package +% - provide an interface for using other LaTeX code for icons +% - provide an interface for using some other package than fontawesome5 +% Indeed we can't load fontawesome5 unconditionally even if available, +% as it proves incompatible with fontawesome package. +% We thus must delay its loading. +\IfFileExists{fontawesome5.sty}{% + \DeclareStringOption[fontawesome5]{iconpackage}% +}% +{% + \IfFileExists{fontawesome.sty} + {\DeclareStringOption[fontawesome]{iconpackage}} + {\DeclareStringOption[none]{iconpackage}}% +}% +\newcommand\spx@faIcon[3][]{}% +% The hacky definition of \spx@faIcon above is to let it by default swallow +% the icon macro and the \sphinxtitlerowaftericonspacecmd (see +% \sphinxdotitlerowwithicon in sphinxlatexadmonitions.sty) which inserts +% a space between it and title. See how \spx@faIcon is used below. +% +% If user sets a title-icon key to some LaTeX code of their own, of course +% \spx@faIcon is not executed and the inserted space will thus be there, as +% expected. +% +\def\spxstring@fontawesome{fontawesome} +\def\spxstring@fontawesomev{fontawesome5} +\AtBeginDocument{% + \ifx\spx@opt@iconpackage\spxstring@none \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}}% + \IfFileExists{\spx@opt@iconpackage.sty} + {\RequirePackage{\spx@opt@iconpackage}% + \ifx\spx@opt@iconpackage\spxstring@fontawesomev + \renewcommand\spx@faIcon{\faIcon}% + \else + \ifx\spx@opt@iconpackage\spxstring@fontawesome + \renewcommand\spx@faIcon[2][]{\faicon{##2}}% + % The \ifdefined's are a bit silly because we know that + % fontawesome.sty does not provide it, but perhaps + % there can be some new release of that package? + \ifdefined\faicon@lightbulb\else + \let\faicon@lightbulb\faLightbulbO + \fi + \ifdefined\faicon@radiation\else + \let\faicon@radiation\faBolt + \fi + \ifdefined\faicon@pen\else + \let\faicon@pen\faPencil + \fi + % if neither has been required, \spx@faIcon will simply swallow + % its argument (and follwing space macro) and it is up to user + % to set the keys appropriately. + \fi\fi % + }% + {% + \sphinxbuildwarning{badiconpackage}% + \PackageWarningNoLine{sphinx}{% + You have set iconpackage=\spx@opt@iconpackage\MessageBreak + But \spx@opt@iconpackage.sty is not found by LaTeX} + }% \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}{TeXcolor}% - {TeXextras}% -\relax - -% Now we add at 6.2.0 BgColor et al. options which will trigger the -% "heavybox" as they are \let to the div._background-TeXColor option -% which has already been enhanced to set the boolean for rendering via -% "heavybox". This is in contrast with legacy BorderColor, -% and with the new TeXcolor and TeXextras. - \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} + +\setkeys{sphinx}{ +% Icon defaults. + div.note_title-icon = \spx@faIcon{info-circle}, + div.hint_title-icon = \spx@faIcon[regular]{lightbulb}, + div.tip_title-icon = \spx@faIcon[regular]{lightbulb}, + div.seealso_title-icon = \spx@faIcon{share}, + div.todo_title-icon = \spx@faIcon{pen}, + div.important_title-icon = \spx@faIcon{pause-circle}, + div.caution_title-icon = \spx@faIcon{radiation}, + div.warning_title-icon = \spx@faIcon{exclamation-triangle}, + div.attention_title-icon = \spx@faIcon{exclamation-triangle}, + div.danger_title-icon = \spx@faIcon{radiation}, + div.error_title-icon = \spx@faIcon{times-circle}, +} \newif\ifspx@opt@box@addstrut \expandafter\def\csname KV@sphinx@box_addstrut\endcsname#1{% @@ -918,20 +1032,23 @@ will be set to white}% } % Some of these defaults got already set. But we now list them all explicitly % for a complete initial configuration of reset storage. -% +% At 7.4.0, \fboxrule and \fboxsep replaced by 0.4pt and 3pt which are anyhow +% the defaults for these LaTeX dimensions. \let\spx@boxes@sphinxbox@defaults\@gobble \sphinxboxsetup{% - border-width=\fboxrule,% <-not really needed to avoid EOL space - padding=\fboxsep,% but done here out of habit - border-radius=\fboxsep,% - box-shadow=none,% -% As xcolor is perhaps not loaded we can not use background-TeXcolor=VerbatimColor -% which would not be compatible with \definecolor syntax. - border-TeXcolor={RGB}{32,32,32},% the default VerbatimBorderColor - background-TeXcolor={gray}{0.95},% the default VerbatimColor - box-shadow-TeXcolor={rgb}{0,0,0},% - TeXextras={},% - addstrut=false% (a final comma here would not hurt) + border-width=0.4pt, + padding=3pt, + border-radius=0.4pt, + box-shadow=none, +% MEMO: as xcolor is loaded, \spx@defineorletcolor has a "\colorlet" branch +% which makes this syntax acceptable and avoids duplicating here the values. + border-TeXcolor=VerbatimBorderColor, + background-TeXcolor=VerbatimColor, +% 7.4.0 modified the color of the shadow (anyhow box-shadow is set above to none +% so no shadow is drawn), to be as the new shadow colour of topic boxes. + box-shadow-TeXcolor={RGB}{108,108,108}, + TeXextras={}, + addstrut=false, }% \RequirePackage{sphinxpackageboxes} \input{sphinxlatexadmonitions.sty} diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index a31ae4ce3a2..c0f6578fc3e 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -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 to use sphinxlightbox (or optionally +% sphinxheavybox since 6.2.0), +% - warning, caution, attention, danger, error to use sphinxheavybox. % -% - note, hint, important, tip (via sphinxlightbox) -% (also optionally via sphinxheavybox since 6.2.0) -% - warning, caution, attention, danger, error (via sphinxheavybox) +% At 7.4.0 all admonitions use sphinxheavybox. % -% Each sphinx environment can be redefined by user. -% The defaults are customizable via various colour and dimension -% settings, cf sphinx docs (latex customization). +% - 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} 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 environments to replace at 6.2.0 -% formerly hard-coded \sphinxstrong{#1} -% 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 to allow user to -% redefine them entirely. +% Since 1.5 these environments are named individually sphinxnote, sphinxhint, +% etc... 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. -% -% 6.2.0 also adds one layer of mark-up via \sphinxnotetitle etc..., because -% the former \sphinxstrong{#1} 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 +% 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 added one layer of mark-up via \sphinxnotetitle etc..., because +% the former \sphinxstrong{#1} 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 sphinxShadowColor, % 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 \sphinxstyletitle is mapped to using \sphinxdotitlerowwithicon{} +% +% 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 +% environments, 7.4.0 inserts an extra \def\spx@noticetype{} in their +% definitions, so that they can be used independently of sphinxadmonition +% dispatcher. +% +% MEMO: direct usage of these environments does not execute the div._TeXextras +% and div._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@@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 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._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{} + % 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 diff --git a/sphinx/texinputs/sphinxlatexliterals.sty b/sphinx/texinputs/sphinxlatexliterals.sty index 3a73a76619e..8acea9f7638 100644 --- a/sphinx/texinputs/sphinxlatexliterals.sty +++ b/sphinx/texinputs/sphinxlatexliterals.sty @@ -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}% diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty index d90009035d2..1655fbc65e3 100644 --- a/sphinx/texinputs/sphinxlatexstyletext.sty +++ b/sphinx/texinputs/sphinxlatexstyletext.sty @@ -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}} diff --git a/sphinx/texinputs/sphinxlatextables.sty b/sphinx/texinputs/sphinxlatextables.sty index 380fc1705e4..9f3944a6591 100644 --- a/sphinx/texinputs/sphinxlatextables.sty +++ b/sphinx/texinputs/sphinxlatextables.sty @@ -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}% - }% - } %%%%%%%%%%%%%%%%%% diff --git a/sphinx/texinputs/sphinxpackageboxes.sty b/sphinx/texinputs/sphinxpackageboxes.sty index b0d3707062f..234505147d5 100644 --- a/sphinx/texinputs/sphinxpackageboxes.sty +++ b/sphinx/texinputs/sphinxpackageboxes.sty @@ -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