diff --git a/CHANGES.rst b/CHANGES.rst index 26214a18220..7f488907189 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -4,12 +4,17 @@ Release 7.4.0 (in development) Dependencies ------------ +* LaTeX: the ``xcolor`` package is now required. + Incompatible changes -------------------- Deprecated ---------- +* LaTeX: the ``sphinxlightbox`` environment is not used anymore, all types + of admonitions use ``sphinxheavybox``. + Features added -------------- diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 6c31f329c65..e426597f10a 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 @@ -48,12 +51,6 @@ }}% \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 +60,29 @@ \@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_fontawesome5ismissing}{% + As fontawesome5 LaTeX package is not found, admonition titles + default to not using icons; check div.note\string_title-icon and + similar options for how to configure your own.} %% 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 +90,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 +100,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 +% #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 +154,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 +180,49 @@ 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}} +\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 +% ---------------- +\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 +240,62 @@ 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. +\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 +\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]{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]{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} {red} +% +\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 +328,24 @@ 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, 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. +% \def\spxstring@none{none} \def\spxstring@clone{clone} % % Border keys -% +% At 7.4.0 refactoring to avoid defining legacy \spx@@border +% macros which are 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,20 +354,20 @@ 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{% #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% + \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 + \ifx\spx@tempa\spxstring@clone#7\else#6\fi}% + \spx@tempc{#8}% option prefix } \def\spx@tempc #1#2{% #1 = option prefix, #2 = legacy option name % keep legacy option names as aliases to new-named options @@ -362,77 +376,69 @@ will be set to white}% % init border-width (fetches next argument) \csname KV@sphinx@#1border-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 which is its default. % 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.4pt} \spx@tempa{spx@note@} {div.note_} {noteborder} {0.5pt} \spx@tempa{spx@hint@} {div.hint_} {hintborder} {0.5pt} \spx@tempa{spx@important@}{div.important_}{importantborder}{0.5pt} \spx@tempa{spx@tip@} {div.tip_} {tipborder} {0.5pt} -\spx@tempa{spx@warning@} {div.warning_} {warningborder} {1pt} -\spx@tempa{spx@caution@} {div.caution_} {cautionborder} {1pt} -\spx@tempa{spx@attention@}{div.attention_}{attentionborder}{1pt} -\spx@tempa{spx@danger@} {div.danger_} {dangerborder} {1pt} -\spx@tempa{spx@error@} {div.error_} {errorborder} {1pt} +\spx@tempa{spx@seealso@} {div.seealso_} {seealsoborder} {0.5pt}% new at 7.4.0 +\spx@tempa{spx@warning@} {div.warning_} {warningborder} {1.5pt}% mod. at 7.4.0 +\spx@tempa{spx@caution@} {div.caution_} {cautionborder} {1.5pt}% mod. at 7.4.0 +\spx@tempa{spx@attention@}{div.attention_}{attentionborder}{1.5pt}% mod. at 7.4.0 +\spx@tempa{spx@danger@} {div.danger_} {dangerborder} {1.5pt}% mod. at 7.4.0 +\spx@tempa{spx@error@} {div.error_} {errorborder} {2pt} % 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 +\spx@tempa{spx@box@} {box_} {box_border-width}{0.4pt} % 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. % 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. +% #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}{12pt}{12pt}{12pt} +% 7.4.0 drops legacy settings which linked strangely padding with border width +\spx@tempa{spx@note@} {div.note_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@hint@} {div.hint_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@important@}{div.important_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@tip@} {div.tip_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@seealso@} {div.seealso_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@warning@} {div.warning_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@caution@} {div.caution_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@attention@}{div.attention_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@danger@} {div.danger_} {6pt}{12pt}{6pt}{12pt} +\spx@tempa{spx@error@} {div.error_} {6pt}{12pt}{6pt}{12pt} +\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 +456,32 @@ 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). +% At 7.4.0 some admonitions use rounded corners as well. +% 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@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 +502,7 @@ 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@warning@} \spx@tempa{spx@caution@} \spx@tempa{spx@attention@} @@ -541,6 +550,7 @@ 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@warning@} {div.warning_} \spx@tempa{spx@caution@} {div.caution_} \spx@tempa{spx@attention@}{div.attention_} @@ -564,8 +574,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 +585,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 +% colors, 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 "set-up" 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 % \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 Fontawasome 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 +617,7 @@ will be set to white}% \spx@tempa{spx@hint@} \spx@tempa{spx@important@} \spx@tempa{spx@tip@} +\spx@tempa{spx@seealso@} \spx@tempa{spx@warning@} \spx@tempa{spx@caution@} \spx@tempa{spx@attention@} @@ -611,29 +627,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, +% and seealso. +\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 +669,7 @@ 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@warning@} {div.warning_} {sphinxwarning} \spx@tempa{spx@caution@} {div.caution_} {sphinxcaution} \spx@tempa{spx@attention@}{div.attention_} {sphinxattention} @@ -666,11 +690,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 +704,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 +714,105 @@ 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: 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. +% 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%); +%% +%% TODO: support todo (sic). +%% Currently the LaTeX mark-up is +%% \begin{sphinxadmonition}{note}{Todo:} and actually even worse +%% \begin{sphinxadmonition}{note}{\label{some tag}Todo:} but the \label +%% can not work correctly as there is no target from a LaTeX counter. +%% +%%\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%); + +% The support for default icons: +\IfFileExists{fontawesome5.sty}{% + \RequirePackage{fontawesome5} + \@namedef{sphinx-icon-pencil}{\faIcon{pencil-alt}} + \@namedef{sphinx-icon-question}{\faIcon{question-circle}} + \@namedef{sphinx-icon-info}{\faIcon{info-circle}} + \@namedef{sphinx-icon-flame}{\faIcon{fire-alt}} + \@namedef{sphinx-icon-spark}{\faIcon{radiation}}% we did not find a good match + % to sphinx13.css svg spark icon in fontawesome 5 LaTeX package + \@namedef{sphinx-icon-warning}{\faIcon{exclamation-triangle}} + \@namedef{sphinx-icon-failure}{\faIcon{skull-crossbones}}% + % but times-circle would be more alike sphinx13.css --icon-failure +}% +{% no fontawasome5.sty + \sphinxbuildwarning{fontawesome5ismissing}% + \PackageWarningNoLine{sphinx}{fontawesome5 not available!\MessageBreak + Default admonition titles will use no icons.\MessageBreak + Check div.note_title-icon and similar options} +} + +% 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, % -% This goes via rather hardcore TeX here. -\def\spx@tempa#1{\if\relax#1\expandafter\@gobble - \else - \toks@{##1}% - \expandafter\def\csname KV@sphinx@div.note_#1\expandafter\endcsname - \the\toks0\expandafter{% - \csname spx@opt@heavynotetrue\expandafter\expandafter\expandafter\endcsname - \csname KV@sphinx@div.note_#1\endcsname{##1}}% - \expandafter\def\csname KV@sphinx@div.hint_#1\expandafter\endcsname - \the\toks0\expandafter{% - \csname spx@opt@heavyhinttrue\expandafter\expandafter\expandafter\endcsname - \csname KV@sphinx@div.hint_#1\endcsname{##1}}% - \expandafter\def\csname KV@sphinx@div.important_#1\expandafter\endcsname - \the\toks0\expandafter{% - \csname spx@opt@heavyimportanttrue\expandafter\expandafter\expandafter\endcsname - \csname KV@sphinx@div.important_#1\endcsname{##1}}% - \expandafter\def\csname KV@sphinx@div.tip_#1\expandafter\endcsname - \the\toks0\expandafter{% - \csname spx@opt@heavytiptrue\expandafter\expandafter\expandafter\endcsname - \csname KV@sphinx@div.tip_#1\endcsname{##1}}% - \fi - \spx@tempa + 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.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, +% + 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=red, +% +% TODO: implement todo (sic) +% +% Icon defaults. These names are copied over from sphinx13.css +% and their actual LaTeX definitions are above and emulate the svg +% icons, if fontawesome5 was found, else they expand to do nothing. + div.note_title-icon=\@nameuse{sphinx-icon-pencil}, + div.hint_title-icon=\@nameuse{sphinx-icon-question}, + div.tip_title-icon=\@nameuse{sphinx-icon-info}, + div.seealso_title-icon=\@nameuse{sphinx-icon-info}, + div.important_title-icon=\@nameuse{sphinx-icon-flame}, + div.caution_title-icon=\@nameuse{sphinx-icon-spark}, + div.warning_title-icon=\@nameuse{sphinx-icon-warning}, + div.attention_title-icon=\@nameuse{sphinx-icon-warning}, + div.danger_title-icon=\@nameuse{sphinx-icon-spark}, + div.error_title-icon=\@nameuse{sphinx-icon-failure}, } -\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} \newif\ifspx@opt@box@addstrut \expandafter\def\csname KV@sphinx@box_addstrut\endcsname#1{% @@ -918,20 +963,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..5cf69e3d5d8 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -1,25 +1,40 @@ %% 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. % % - sphinxadmonition (environment) -% This is a dispatch supporting +% This is a dispatch which originally configured +% +% - note, hint, important, tip to use sphinxlightbox or optionnaly +% sphinxheavybox since 6.2.0. +% - warning, caution, attention, danger, error to use sphinxheavybox. +% +% At 7.4.0 all admonitions use sphinxheavybox. % -% - note, hint, important, tip (via sphinxlightbox) -% (also optionally via sphinxheavybox since 6.2.0) -% - warning, caution, attention, danger, error (via sphinxheavybox) +% - all environments sphinxnote, sphinxwarning, etc... can be redefined +% as will by user. Thay have one parameter #1 which is the title. % -% Each sphinx environment can be redefined by user. -% The defaults are customizable via various colour and dimension -% settings, cf sphinx docs (latex customization). +% - all default sphinxnote, sphinxwarning, etc... use associated +% one-argment macros \sphinxstylenotetitle, \sphinxstylewarningtitle, +% etc which can be redefined, and whose 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 only for projects with LaTeX +% code which used it via custom definitions done in preamble or +% via raw latex directive. % % 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 +44,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,58 +72,42 @@ {\linewidth}{\spx@notice@border}}\hss}\allowbreak }% end of sphinxlightbox environment definition -% note/hint/important/tip notices +% Since 1.5 these environments are named individually sphinxnote, sphinxhint, +% etc... to allow user to redefine them entirely. % -% Since 1.5 these environments are named individually to allow user to -% redefine them entirely. -% -% The Sphinx definitions were done like this, prior to 6.2.0: +% The Sphinx definitions for note/hint/important/tip notices were done like +% this, prior to 6.2.0: % % \newenvironment{sphinxhint}[1] % {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}} % -% The more complex definition below will branch to sphinxheavybox if a certain -% boolean associated to the notice type is true. This boolean is set to true -% whenever a CSS-named alike options for the notice type has been used in -% sphinxsetup. The old coding as above would still work, with the new options -% being then simply ignored. A user redefinition will probably either use -% directly sphinxlightbox or sphinxheavybox or something else, with no need to -% test the boolean. -% -% 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 seealso directive. % +% The 7.4.0 sphinxheavybox has an "optional" argument [], which actually +% is mandatory and must be the admonition type. It is needed only for the +% the boolean \ifspx@@border@open. +% The 7.4.0 version of sphinxheavybox is executed *after* the suitable +% \spx@boxes@fcolorbox@setup{}. Formerly it did it itself. +% +% Catch a missing mandatory [] +\def\ifspx@@border@open{\PackageError{sphinxlatexadmonitions} + {Missing type for sphinxheavybox} + {Please check sphinxlatexadmonitions.sty + for comments}% + \iffalse} + % 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}% +\newenvironment{sphinxheavybox}[1][]{% + \par % Those are used by sphinxVerbatim if the \ifspx@inframed boolean is true \setlength{\FrameRule}{0.5\dimexpr\spx@boxes@border@top+\spx@boxes@border@bottom\relax}% % MEMO: prior to 5.1.0 \FrameSep was determined as 0.6\baselineskip - @@ -148,7 +139,7 @@ }% % 6.2.0 adds support for div._box-decoration-break=slice. % (it is yet undecided if slice style should inhibit a bottom shadow) - \csname ifspx@\spx@noticetype @border@open\endcsname + \csname ifspx@#1@border@open\endcsname \def\FirstFrameCommand {\spx@boxes@fcolorbox@setup@openbottom\FrameCommand}% \def\MidFrameCommand @@ -205,16 +196,77 @@ % 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. +% Rather than rely on such a macro being set we have refactored sphinxheavybox +% to take an optional argument (the various [note], [hint] etc...) to transmit +% the notice type (it does not have to be an admonition type, only to be +% something which \spx@boxes@fcolorbox@setup will be able to handle). +% +% This way the environments sphinxwarning et al. as defined next can be used +% directly in other contexts without originating from sphinxadmonition. And +% now we can let sphinxseealso use sphinxheavybox, despite the seealso +% directive not being handled by Sphinx LaTeX writer as an admonition type. +% +% MEMO: the \spx@boxes@fcolorbox@setup{} are executed first so that +% \sphinxdotitlerowwithicon (see below) can inherit the box parameters, in +% particular whether the top corners are rounded and fit exactly in the frame. +% +% MEMO: direct usage of these environment does not execute the div._TeXextras +% and div._TexColor code, there are only done from the sphinxadmonition wrapper. +\newenvironment{sphinxnote}[1] + {\spx@boxes@fcolorbox@setup{note}\begin{sphinxheavybox}[note]\sphinxstylenotetitle{#1}} + {\end{sphinxheavybox}} +\newenvironment{sphinxhint}[1] + {\spx@boxes@fcolorbox@setup{hint}\begin{sphinxheavybox}[hint]\sphinxstylehinttitle{#1}} + {\end{sphinxheavybox}} +\newenvironment{sphinxtip}[1] + {\spx@boxes@fcolorbox@setup{tip}\begin{sphinxheavybox}[tip]\sphinxstyletiptitle{#1}} + {\end{sphinxheavybox}} +\newenvironment{sphinximportant}[1] + {\spx@boxes@fcolorbox@setup{important}\begin{sphinxheavybox}[important]\sphinxstyleimportanttitle{#1}} + {\end{sphinxheavybox}} \newenvironment{sphinxwarning}[1] - {\begin{sphinxheavybox}\sphinxstylewarningtitle{#1}}{\end{sphinxheavybox}} + {\spx@boxes@fcolorbox@setup{warning}\begin{sphinxheavybox}[warning]\sphinxstylewarningtitle{#1}} + {\end{sphinxheavybox}} \newenvironment{sphinxcaution}[1] - {\begin{sphinxheavybox}\sphinxstylecautiontitle{#1}}{\end{sphinxheavybox}} + {\spx@boxes@fcolorbox@setup{caution}\begin{sphinxheavybox}[caution]\sphinxstylecautiontitle{#1}} + {\end{sphinxheavybox}} \newenvironment{sphinxattention}[1] - {\begin{sphinxheavybox}\sphinxstyleattentiontitle{#1}}{\end{sphinxheavybox}} + {\spx@boxes@fcolorbox@setup{attention}\begin{sphinxheavybox}[attention]\sphinxstyleattentiontitle{#1}} + {\end{sphinxheavybox}} \newenvironment{sphinxdanger}[1] - {\begin{sphinxheavybox}\sphinxstyledangertitle{#1}}{\end{sphinxheavybox}} + {\spx@boxes@fcolorbox@setup{danger}\begin{sphinxheavybox}[danger]\sphinxstyledangertitle{#1}} + {\end{sphinxheavybox}} \newenvironment{sphinxerror}[1] - {\begin{sphinxheavybox}\sphinxstyleerrortitle{#1}}{\end{sphinxheavybox}} + {\spx@boxes@fcolorbox@setup{error}\begin{sphinxheavybox}[error]\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] + {\spx@boxes@fcolorbox@setup{seealso}% + \begin{sphinxheavybox}[seealso]\sphinxstyleseealsotitle{#1}% + \ifspx@seealso@withtextcolor\color{sphinxseealsoTextColor}\fi + \spx@seealso@TeXextras + } + {\end{sphinxheavybox}} % the main dispatch for all types of notices \newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading @@ -227,16 +279,93 @@ % 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.75em\relax} +\newcommand\sphinxdotitlerowwithicon[2]{% #1=type, #2=heading (without final colon) + \kern-\spx@boxes@padding@top + \noindent + \kern-\spx@boxes@padding@left % must have been configured by a prior \spx@boxes@fcolorbox@setup{} + \begingroup + % 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}}% + \sphinxtitlerowaftericonspacecmd + \sphinxstrong{#2}% + \strut}% + }% + \endgroup + \kern-\spx@boxes@padding@right + \par\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}}} +% +% 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..fe7ec33bf2e 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 verything 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..6784225ea63 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 + % 6.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