diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 633b244e180..47caad13659 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -9,7 +9,7 @@ % by the Sphinx LaTeX writer. \NeedsTeXFormat{LaTeX2e}[1995/12/01] -\ProvidesPackage{sphinx}[2024/07/01 v7.4.0 Sphinx LaTeX package (sphinx-doc)] +\ProvidesPackage{sphinx}[2024/07/28 v8.1.0 Sphinx LaTeX package (sphinx-doc)] % provides \ltx@ifundefined % (many packages load ltxcmds: graphicx does for pdftex and lualatex but @@ -350,6 +350,11 @@ % is handled as an admonition with the same customizability. And the % todo directive. % +% 8.1.0: style separately topic, contents, and sidebar directives +% --------------------------------------------------------------- +% +% And use some title row also for them (but without icon, per default). +% \def\spxstring@none{none} \def\spxstring@clone{clone} % @@ -397,6 +402,17 @@ % macro prefix option prefix legacy option init value \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@contents@} {div.contents_} {shadowrule} {0.5pt}% new at 8.1.0 +\spx@tempa{spx@sidebar@} {div.sidebar_} {shadowrule} {1pt}% new at 8.1.0 +\@nameuse{KV@sphinx@div.sidebar_border-left-width}{2pt} +\@nameuse{KV@sphinx@div.sidebar_border-right-width}{2pt} +% let legacy shadowrule key set all topic/contents/sidebar border +% keys to the common value given by user to shadowrule +\def\KV@sphinx@shadowrule #1{% + \@nameuse{KV@sphinx@div.topic_border-width}{#1}% + \@nameuse{KV@sphinx@div.contents_border-width}{#1}% + \@nameuse{KV@sphinx@div.sidebar_border-width}{#1}% +}% \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} @@ -444,9 +460,13 @@ % 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). +% 8.1.0 styles separately topic, contents, and sidebar. % #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} +\spx@tempa{spx@topic@} {div.topic_} {6pt}{7pt}{6pt}{7pt}% mod. at 8.1.0 +% contents styling inherits at 8.1.0 the former 7.4.0 topic defaults +\spx@tempa{spx@contents@} {div.contents_} {10pt}{7pt}{12pt}{7pt}% new at 8.1.0 +\spx@tempa{spx@sidebar@} {div.sidebar_} {6pt}{5.5pt}{6pt}{5.5pt}% new at 8.1.0 % 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} @@ -462,8 +482,13 @@ \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 -\expandafter\let\expandafter\KV@sphinx@shadowsep\csname KV@sphinx@div.topic_padding\endcsname +% let legacy shadowsep key set all topic/contents/sidebar padding +% keys to the common value given by user to shadosep +\def\KV@sphinx@shadowsep #1{% + \@nameuse{KV@sphinx@div.topic_padding}{#1}% + \@nameuse{KV@sphinx@div.contents_padding}{#1}% + \@nameuse{KV@sphinx@div.sidebar_padding}{#1}% +}% % Corner radii keys % @@ -491,9 +516,16 @@ % - 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. +% At 8.1.0 topic, contents and sidebar separately styled. % 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@ +% use four rounded corners (and no shadow) for topic at 8.1.0 +\spx@tempa{spx@topic@} {div.topic_} {8pt}{8pt}{8pt}{8pt} +% contents inherits at 8.1.0 the 7.4.0 former styling of topic +\spx@tempa{spx@contents@} {div.contents_} \z@ \z@ {12pt} \z@ +% make sidebard distinctive as we can't really safely implement +% it with text flowing around it, but rather as a full width block +\spx@tempa{spx@sidebar@} {div.sidebar_} {12pt}\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@ @@ -522,6 +554,8 @@ % macro prefix \spx@tempa{spx@pre@} \spx@tempa{spx@topic@} +\spx@tempa{spx@contents@}% 8.1.0 +\spx@tempa{spx@sidebar@}% 8.1.0 \spx@tempa{spx@note@} \spx@tempa{spx@hint@} \spx@tempa{spx@important@} @@ -569,8 +603,14 @@ } \spx@tempa{spx@pre@} {pre_} \spx@tempa{spx@topic@} {div.topic_} -% This corresponds to the legacy parameters of ShadowBox - \spx@topic@shadow@setter 4pt 4pt {} \@nnil +\spx@tempa{spx@contents@} {div.contents_} +\spx@tempa{spx@sidebar@} {div.sidebar_} +% This corresponds to the legacy parameters for topic/contents/sidebar, +% but they are now only kept for contents + \spx@contents@shadow@setter 4pt 4pt {} \@nnil +% sidebard has only small shadow at bottom + \spx@sidebar@shadow@setter 0pt 2pt {} \@nnil +% topic has no shadow, nothing additional to do here \spx@tempa{spx@note@} {div.note_} \spx@tempa{spx@hint@} {div.hint_} \spx@tempa{spx@important@}{div.important_} @@ -584,18 +624,27 @@ \spx@tempa{spx@error@} {div.error_} \spx@tempa{spx@box@} {box_} -% Support for legacy shadowsize (topic/contents) +% Support for legacy shadowsize (topic/contents/sidebar) % 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. \define@key{sphinx}{shadowsize}{% \def\spx@topic@shadow@xoffset{#1}% - \let\spx@topic@shadow@yoffset\spx@topic@shadow@xoffset + \let\spx@contents@shadow@xoffset\spx@topic@shadow@xoffset + \let\spx@topic@shadow@yoffset \spx@topic@shadow@xoffset + \let\spx@contents@shadow@yoffset\spx@topic@shadow@xoffset + \let\spx@sidebar@shadow@yoffset \spx@topic@shadow@xoffset \ifdim\dimexpr\spx@topic@shadow@xoffset=\z@ \spx@topic@withshadowfalse + \spx@contents@withshadowfalse + \spx@sidebar@withshadowfalse \else \spx@topic@withshadowtrue \spx@topic@insetshadowfalse + \spx@contents@withshadowtrue + \spx@contents@insetshadowfalse + \spx@sidebar@withshadowtrue + \spx@sidebar@insetshadowfalse \fi }% @@ -638,6 +687,8 @@ % macro prefix \spx@tempa{spx@pre@} \spx@tempa{spx@topic@} +\spx@tempa{spx@contents@} +\spx@tempa{spx@sidebar@} \spx@tempa{spx@note@} \spx@tempa{spx@hint@} \spx@tempa{spx@important@} @@ -691,6 +742,8 @@ % (6.2.0 modified some internal namings for the colors of topic boxes) % macro prefix option prefix color name prefix \spx@tempa{spx@topic@} {div.topic_} {sphinxtopic}% (no legacy interface) +\spx@tempa{spx@contents@} {div.contents_} {sphinxcontents}% 8.1.0 (no legacy interface) +\spx@tempa{spx@sidebar@} {div.sidebar_} {sphinxsidebar}% 8.1.0 (no legacy interface) \spx@tempa{spx@note@} {div.note_} {sphinxnote} \spx@tempa{spx@hint@} {div.hint_} {sphinxhint} \spx@tempa{spx@important@}{div.important_} {sphinximportant} @@ -743,12 +796,19 @@ % At 7.4.0, let topic/contents boxes acquire background and border colours % and give the shadow some colour other than black + % 8.1.0 styles separately topic/contents/sidebar + % topic has no shadow but we keep 7.4.0 color in case it gets needed \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}, + div.contents_border-TeXcolor=sphinx-admonition-bordercolor, + div.contents_background-TeXcolor=sphinx-admonition-bgcolor, + div.contents_box-shadow-TeXcolor={RGB}{108,108,108}, + div.sidebar_border-TeXcolor=sphinx-admonition-bordercolor, + div.sidebar_background-TeXcolor=sphinx-admonition-bgcolor, + div.sidebar_box-shadow-TeXcolor=sphinx-admonition-bordercolor!80, } - % 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) @@ -799,8 +859,14 @@ div.error_title-background-TeXcolor=sphinx-error-title-bgcolor, div.error_title-foreground-TeXcolor=sphinx-error-title-fgcolor, % -% TODO: implement todo (sic) -% +% 8.1.0 add title rows, but will not use icons per default, so +% the fgcolor setting will be used only if user uses title-icon key + div.topic_title-background-TeXcolor=sphinx-admonition-title-bgcolor, + div.topic_title-foreground-TeXcolor=sphinx-admonition-title-fgcolor, + div.contents_title-background-TeXcolor=sphinx-admonition-title-bgcolor, + div.contents_title-foreground-TeXcolor=sphinx-admonition-title-fgcolor, + div.sidebar_title-background-TeXcolor=sphinx-note-title-bgcolor, + div.sidebar_title-foreground-TeXcolor=sphinx-note-title-fgcolor, } % 7.4.0 Support for icons in admonition titles @@ -881,6 +947,11 @@ div.attention_title-icon = \spx@faIcon{exclamation-triangle}, div.danger_title-icon = \spx@faIcon{radiation}, div.error_title-icon = \spx@faIcon{times-circle}, +% (no default icons set-up for contents/topic/sidebar directives, +% as the Sphinx definitions for the environements use +% \sphinxdotitlerowwithouticon, but this can be changed by user +% via renew'd environment, if desired. Then the icon keys +% must be set). } \newif\ifspx@opt@box@addstrut @@ -1051,6 +1122,8 @@ addstrut=false, }% \RequirePackage{sphinxpackageboxes} +% TODO: convert everything to packages which will allow ``Requiring'' them +% possibly twice without errors from \newcommand executed twice. \input{sphinxlatexadmonitions.sty} \input{sphinxlatexliterals.sty} \input{sphinxlatexshadowbox.sty} diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index c0f6578fc3e..80b4483c76d 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -1,7 +1,8 @@ %% NOTICES AND ADMONITIONS % % change this info string if making any custom modification -\ProvidesFile{sphinxlatexadmonitions.sty}[2024/07/01 v7.4.0 admonitions] +% TODO: convert all .sty files into using \ProvidesPackage not \ProvidesFile +\ProvidesFile{sphinxlatexadmonitions.sty}[2024/07/28 v8.1.0 admonitions] % Provides support for this output mark-up from Sphinx latex writer: % @@ -28,7 +29,8 @@ % 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) +% admonition. (new with 7.4.0; definitions moved to sphinxlatexstyletext.sty +% at 8.1.0) % % The sphinxlightbox environment is kept for backward compatiblity, for user % custom code which used it via custom definitions done in preamble or via @@ -43,7 +45,8 @@ % so \sphinxstrong{#1} which was its former default is used above). % -% Requires: +% Requires: (these Require are only for clarity, macro definitions in TeX +% can be done in any order whatsoever, of course prior to use...) \RequirePackage{sphinxpackageboxes} % 7.4.0 removes unneeded \spx@boxes@border \RequirePackage{framed}% used by sphinxheavybox @@ -300,86 +303,4 @@ % 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/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty index a2a1a0e393e..91463a39efc 100644 --- a/sphinx/texinputs/sphinxlatexshadowbox.sty +++ b/sphinx/texinputs/sphinxlatexshadowbox.sty @@ -1,11 +1,13 @@ %% TOPIC AND CONTENTS BOXES % % change this info string if making any custom modification -\ProvidesFile{sphinxlatexshadowbox.sty}[2023/03/19 sphinxShadowBox] +\ProvidesFile{sphinxlatexshadowbox.sty}[2024/07/28 v8.1.0 sphinxShadowBox] % Provides support for this output mark-up from Sphinx latex writer: % -% - sphinxShadowBox (environment) +% - sphinxtopic, sphinxcontents, sphinxsidebar (environments) +% These wrappers replace at 8.1.0 former direct use of sphinxShadowBox +% environment which did not allow separate styling. % % Dependencies (they do not need to be defined at time of loading): % @@ -45,9 +47,39 @@ % in contrast with the framing used for literal blocks, also based, but in a % more sophisticated way on usage of \MakeFramed/\endMakeFramed, and % adjusting to current text indentation. -\newenvironment{sphinxShadowBox} +% +% At 8.1.0, sphinxShadowBox takes an optional argument #1 and uses it as +% \spx@boxes@fcolorbox@setup{#1} rather than \spx@boxes@fcolorbox@setup{topic}. +% Some hesitation whether to move this line to newly added sphinxtopic, +% sphinxcontents and sphinxsidebar environmments. But anyhow the environment +% also requires later knowing a few more things: sphinxTextColor and +% spx@@texextras. +% +\newenvironment{sphinxtopic} + {\begin{sphinxShadowBox}\relax}{\end{sphinxShadowBox}} +\newenvironment{sphinxcontents} + {\begin{sphinxShadowBox}[contents]}{\end{sphinxShadowBox}} +% Arguably sphinxsidebar should rather use a wrapfig or similar environment +% but this is so dysfunctional in LaTeX (except for self-written documents) +% so we prefer to not venture into such a potential quagmire and keep the +% legacy rendering. +\newenvironment{sphinxsidebar} + {\begin{sphinxShadowBox}[sidebar]}{\end{sphinxShadowBox}} + +% The #1 defaulting to topic must be such that all parameters expected by +% \spx@boxes@fcolorbox@setup actually do exist, see CSS options in sphinx.sty +% which is what defines them for contents, topic, and sidebar. +% +% Fortunately the #1 is not needed in \end{sphinxShadowBox} so we don't have +% to work around a LaTeX conception bug that such #1 can not be used as is in +% the definition of the \end part of an environment. +% +% MEMO: the "shadow" is not really drawn directly by this environment but +% indirectly via the configuration which is passed over to \spx@boxes@fcolorbox, +% which is the macro creating frame and (perhaps but not necessarily) a shadow. +\newenvironment{sphinxShadowBox}[1][topic]% {% - \spx@boxes@fcolorbox@setup{topic}% + \spx@boxes@fcolorbox@setup{#1}% % we will use the dimen registers from sphinxpackageboxes.sty which now hold % the values from options related to topic/contents % MEMO: \spx@boxes@fcolorbox creates an \hbox but does not quit vertical @@ -56,7 +88,7 @@ \def\FrameCommand {\spx@boxes@fcolorbox}% % 6.2.0 adds support for div.topic_box-decoration-break=slice. % (it is yet undecided if slice style should inhibit a bottom shadow) - \ifspx@topic@border@open + \@nameuse{ifspx@#1@border@open}% \def\FirstFrameCommand {\spx@boxes@fcolorbox@setup@openbottom\FrameCommand}% \def\MidFrameCommand @@ -97,10 +129,10 @@ \@setminipage }% \color@begingroup % workaround upstream framed.sty bug - \ifspx@topic@withtextcolor - \color{sphinxtopicTextColor}% + \@nameuse{ifspx@#1@withtextcolor}% + \color{sphinx#1TextColor}% \fi - \spx@topic@TeXextras + \@nameuse{spx@#1@TeXextras}% }% {% insert the "endminipage" code \par\unskip diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty index 1655fbc65e3..59c0f474ef8 100644 --- a/sphinx/texinputs/sphinxlatexstyletext.sty +++ b/sphinx/texinputs/sphinxlatexstyletext.sty @@ -1,11 +1,117 @@ %% TEXT STYLING % % change this info string if making any custom modification -\ProvidesFile{sphinxlatexstyletext.sty}[2024/07/01 v7.4.0 text styling] +\ProvidesFile{sphinxlatexstyletext.sty}[2024/07/28 v8.1.0 text styling] -% 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. +% 8.1.0 moves here from sphinxlatexadmonitions.sty the title row material, +% as it may now also be used to topic/contents/sidebar directives so we +% use a shared location here. +% TODO: allow these next three settings to be customized individually. +% This can however already be done at user level by \renewcommand +% inside renew'ed environments sphinxnote, sphinxhint etc... +\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{% + \parbox[t]{\linewidth}{% 7.4.0 used \makebox, but wrapping of long titles + % possibly needed for generic admonition or topic. + \sphinxAtStartPar + \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 + \par + }% + }% + \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 were all using a boring plain \sphinxstrong{#1}, +% now we use as default 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: + +% must be used in an environment to limit scope of some changes +\newcommand\sphinxdotitlerowwithouticon[2]{% + \let\sphinxtitlerowaftericonspacecmd\empty + \sphinxcolorlet{sphinx#1TtlFgColor}{black}% only to give it some definition + \sphinxdotitlerowwithicon{#1}{#2}% +} +% 8.1.0 styles topic/contents/sidebar with a title row, too. +% Prior to 8.1.0, definitions use \protected\def but there does not seem +% to be any reason so back to \newcommand +\newcommand\sphinxstyletopictitle[1]{\sphinxdotitlerowwithouticon{topic}{#1}} +\newcommand\sphinxstylecontentstitle[1]{\sphinxdotitlerowwithouticon{contents}{#1}} +\newcommand\sphinxstylesidebartitle[1]{\sphinxdotitlerowwithouticon{sidebar}{#1}} +% No default color background for subtitle. The contents next are injected by +% LaTeX writer after a blank line in source hence will start a new paragrpah. +% The \sphinxAtStartPar here is only for coherence with other text paragraphs, +% but does not have serious necessity (its general role is to allow hyphenation +% for first word in narrow table cells. +\newcommand\sphinxstylesidebarsubtitle[1]{\sphinxAtStartPar\textbf{#1}} % Some custom font markup commands. \protected\def\sphinxstrong#1{\textbf{#1}} @@ -39,10 +145,7 @@ {{\Large\sffamily#1}\nopagebreak\vspace{1mm}} \def\sphinxstyleindexlettergroupDefault #1% {{\Large\sffamily\sphinxnonalphabeticalgroupname}\nopagebreak\vspace{1mm}} -\protected\def\sphinxstyletopictitle #1{\textbf{#1}\par\medskip} -\let\sphinxstylesidebartitle\sphinxstyletopictitle \protected\def\sphinxstyleothertitle #1{\textbf{#1}} -\protected\def\sphinxstylesidebarsubtitle #1{~\\\textbf{#1} \smallskip} % \text.. commands do not allow multiple paragraphs % attention, this one is not self-delimiting \protected\def\sphinxstyletheadfamily {\sffamily} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 4badfa87f85..ed23f3a9f69 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -582,13 +582,22 @@ def depart_problematic(self, node: Element) -> None: self.body.append('}') def visit_topic(self, node: Element) -> None: - self.in_minipage = 1 - self.body.append(CR + r'\begin{sphinxShadowBox}' + CR) + self.in_minipage += 1 + if 'contents' in node.get('classes', []): + self.body.append(CR + r'\begin{sphinxcontents}' + CR) + self.context.append(r'\end{sphinxcontents}' + CR) + else: + self.body.append(CR + r'\begin{sphinxtopic}' + CR) + self.context.append(r'\end{sphinxtopic}' + CR) def depart_topic(self, node: Element) -> None: - self.in_minipage = 0 - self.body.append(r'\end{sphinxShadowBox}' + CR) - visit_sidebar = visit_topic + self.in_minipage -= 1 + self.body.append(self.context.pop()) + + def visit_sidebar(self, node: Element) -> None: + self.in_minipage += 1 + self.body.append(CR + r'\begin{sphinxsidebar}' + CR) + self.context.append(r'\end{sphinxsidebar}' + CR) depart_sidebar = depart_topic def visit_glossary(self, node: Element) -> None: @@ -651,7 +660,10 @@ def visit_title(self, node: Element) -> None: self.body.append(fr'\{self.sectionnames[-1]}{short}{{') self.context.append('}' + CR + self.hypertarget_to(node.parent)) elif isinstance(parent, nodes.topic): - self.body.append(r'\sphinxstyletopictitle{') + if 'contents' in parent.get('classes', []): + self.body.append(r'\sphinxstylecontentstitle{') + else: + self.body.append(r'\sphinxstyletopictitle{') self.context.append('}' + CR) elif isinstance(parent, nodes.sidebar): self.body.append(r'\sphinxstylesidebartitle{')