From e903f383156398b0cae1f69ae6d9d30503baef84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Sun, 28 Jul 2024 13:13:30 +0200 Subject: [PATCH 01/31] LaTeX: make contents, topic, and sidebar separately customizable And give them some nice defaults to start with. --- sphinx/texinputs/sphinx.sty | 97 ++++++++++++++-- sphinx/texinputs/sphinxlatexadmonitions.sty | 91 +-------------- sphinx/texinputs/sphinxlatexshadowbox.sty | 48 ++++++-- sphinx/texinputs/sphinxlatexstyletext.sty | 117 ++++++++++++++++++-- sphinx/writers/latex.py | 24 +++- 5 files changed, 259 insertions(+), 118 deletions(-) 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{') From d6c06143f67e0985c14d2025771d6024b4dfa584 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 29 Jul 2024 10:17:42 +0200 Subject: [PATCH 02/31] Let titlerow macro auto-detect if using or not icon --- sphinx/texinputs/sphinx.sty | 50 ++++----- sphinx/texinputs/sphinxlatexadmonitions.sty | 102 +++++++++++++++++- sphinx/texinputs/sphinxlatexshadowbox.sty | 41 ++++--- sphinx/texinputs/sphinxlatexstyletext.sty | 113 +------------------- 4 files changed, 155 insertions(+), 151 deletions(-) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 47caad13659..15fb655cf2d 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -402,8 +402,8 @@ % 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 +\spx@tempa{spx@contents@} {div.contents_} {shadowrule} {0.5pt}% 8.1.0 +\spx@tempa{spx@sidebar@} {div.sidebar_} {shadowrule} {1pt}% 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 @@ -465,8 +465,8 @@ \spx@tempa{spx@pre@} {pre_} {3pt}{3pt}{3pt}{3pt} \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 +\spx@tempa{spx@contents@} {div.contents_} {10pt}{7pt}{12pt}{7pt}% 8.1.0 +\spx@tempa{spx@sidebar@} {div.sidebar_} {6pt}{5.5pt}{6pt}{5.5pt}% 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} @@ -608,7 +608,7 @@ % 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 +% sidebar 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_} @@ -741,9 +741,11 @@ \csname KV@sphinx@pre_background-TeXcolor\endcsname % (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) +% There was no legacy interface for topic/contents/sidebar +% 8.1.0 allows separate styling for topic/contents/sidebar +\spx@tempa{spx@topic@} {div.topic_} {sphinxtopic} +\spx@tempa{spx@contents@} {div.contents_} {sphinxcontents} +\spx@tempa{spx@sidebar@} {div.sidebar_} {sphinxsidebar} \spx@tempa{spx@note@} {div.note_} {sphinxnote} \spx@tempa{spx@hint@} {div.hint_} {sphinxhint} \spx@tempa{spx@important@}{div.important_} {sphinximportant} @@ -798,16 +800,18 @@ % 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, - } + \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,% #9eacaf + } + % 7.4.0 lets all types of admonitions style especially their titlss. % The Sphinx default colours for admonition titles are copied from PR #12486 @@ -947,11 +951,9 @@ 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). +% MEMO: the new at 8.1.0 defaults for contents/topic/sidebar directives +% use no icons, they use \sphinxdotitlerow which detects automatically +% whether title-icon key has been set or not. } \newif\ifspx@opt@box@addstrut @@ -1122,8 +1124,6 @@ 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 80b4483c76d..91ef1760f6e 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -1,7 +1,6 @@ %% NOTICES AND ADMONITIONS % % change this info string if making any custom modification -% 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: @@ -29,8 +28,7 @@ % 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; definitions moved to sphinxlatexstyletext.sty -% at 8.1.0) +% admonition. (new with 7.4.0) % % The sphinxlightbox environment is kept for backward compatiblity, for user % custom code which used it via custom definitions done in preamble or via @@ -45,8 +43,7 @@ % so \sphinxstrong{#1} which was its former default is used above). % -% Requires: (these Require are only for clarity, macro definitions in TeX -% can be done in any order whatsoever, of course prior to use...) +% Requires: \RequirePackage{sphinxpackageboxes} % 7.4.0 removes unneeded \spx@boxes@border \RequirePackage{framed}% used by sphinxheavybox @@ -303,4 +300,99 @@ % 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} +% 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} +% 7.4.0 used this longer name: +\newcommand\sphinxdotitlerowwithicon{\sphinxdotitlerow} +\newcommand\sphinxdotitlerow[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 + % is needed for generic admonition or topic box. + \sphinxAtStartPar + % 8.1.0 auto-drops extra space if no icon + \sbox\z@{\@nameuse{sphinx#1TtlIcon}}% + \ifdim\wd\z@>\z@ + \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 + }% + \fi + \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 (done in sphinxlatexstyletext.sty) were all using +% a boring plain \sphinxstrong{#1}, now we use a coloured title row. +\newcommand\sphinxstylenotetitle [1]{\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstylehinttitle [1]{\sphinxdotitlerow{hint}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyleimportanttitle[1]{\sphinxdotitlerow{important}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyletiptitle [1]{\sphinxdotitlerow{tip}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstylewarningtitle [1]{\sphinxdotitlerow{warning}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstylecautiontitle [1]{\sphinxdotitlerow{caution}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyleattentiontitle[1]{\sphinxdotitlerow{attention}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyledangertitle [1]{\sphinxdotitlerow{danger}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyleerrortitle [1]{\sphinxdotitlerow{error}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyleseealsotitle [1]{\sphinxdotitlerow{seealso}{\sphinxremovefinalcolon{#1}}} +\newcommand\sphinxstyletodotitle [1]{\sphinxdotitlerow{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 91463a39efc..cfd0cfd97fa 100644 --- a/sphinx/texinputs/sphinxlatexshadowbox.sty +++ b/sphinx/texinputs/sphinxlatexshadowbox.sty @@ -7,7 +7,8 @@ % % - sphinxtopic, sphinxcontents, sphinxsidebar (environments) % These wrappers replace at 8.1.0 former direct use of sphinxShadowBox -% environment which did not allow separate styling. +% environment which did not allow separate styling. Their defaults +% use \sphinxdotitlerow macro from sphinxlatexadmonitions.sty % % Dependencies (they do not need to be defined at time of loading): % @@ -55,17 +56,6 @@ % 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. @@ -145,4 +135,31 @@ \spewnotes } +% 8.1.0 +\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 using a full width display. +\newenvironment{sphinxsidebar} + {\begin{sphinxShadowBox}[sidebar]}{\end{sphinxShadowBox}} + +% TODO: decide if this should be in sphinxlatexstyletext.sty rather +% +% 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]{\sphinxdotitlerow{topic}{#1}} +\newcommand\sphinxstylecontentstitle[1]{\sphinxdotitlerow{contents}{#1}} +\newcommand\sphinxstylesidebartitle[1]{\sphinxdotitlerow{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}} + \endinput diff --git a/sphinx/texinputs/sphinxlatexstyletext.sty b/sphinx/texinputs/sphinxlatexstyletext.sty index 59c0f474ef8..f6ac64c5241 100644 --- a/sphinx/texinputs/sphinxlatexstyletext.sty +++ b/sphinx/texinputs/sphinxlatexstyletext.sty @@ -3,115 +3,10 @@ % change this info string if making any custom modification \ProvidesFile{sphinxlatexstyletext.sty}[2024/07/28 v8.1.0 text styling] -% 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}} +% 7.4.0 has moved all that is related to admonitions to sphinxlatexadmonitions.sty +% 8.1.0 has moved topic/contents/sidebar to sphinxlatexshadowbox.sty +% Most everything left here consists of macros which are part of the latex markup +% produced by the Sphinx LaTeX writer. % Some custom font markup commands. \protected\def\sphinxstrong#1{\textbf{#1}} From 0f1d44612191a8586e7d2770d11461fc071602af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 29 Jul 2024 10:17:51 +0200 Subject: [PATCH 03/31] Docs --- doc/latex.rst | 164 +++++++++++++++++++++++++++++--------------------- 1 file changed, 95 insertions(+), 69 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 821c8329764..1a1b6628291 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -940,32 +940,32 @@ The color used in the above example is available from having passed the Default: ``\fboxrule`` -``shadowsep`` - The separation between contents and frame for contents_ and - :dudir:`topic` boxes. - - See :ref:`additionalcss` for the alias ``div.topic_padding``. +.. important:: - Default: ``5pt`` + At 8.1.0 it became possible to style separately the :dudir:`topic`, + contents_, and :dudir:`sidebar` directives, and each acquired new defaults. + See :ref:`additionalcss`. + The ``shadowsep``, ``shadowsize`` and ``shadowrule`` keys are kept for + backward compatibility only. -``shadowsize`` - The width of the lateral "shadow" to the right and bottom. +``shadowsep`` + This legacy option sets the padding (same in all directions) simultaneously + for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. - See :ref:`additionalcss` for ``div.topic_box-shadow`` which allows to - configure separately the widths of the vertical and horizontal shadows. + .. versionchanged:: 8.1.0 New separate defaults. See :ref:`additionalcss`. - Default: ``4pt`` +``shadowsize`` + This legacy option sets the shadow width simultaneously for the + :dudir:`topic`, contents_, and :dudir:`sidebar` directives. - .. versionchanged:: 6.1.2 - Fixed a regression introduced at ``5.1.0`` which modified unintentionally - the width of topic boxes and worse had made usage of this key break PDF - builds. + .. versionchanged:: 8.1.0 New separate defaults. See :ref:`additionalcss`. ``shadowrule`` - The width of the frame around :dudir:`topic` boxes. See also - :ref:`additionalcss` for ``div.topic_border-width``. - Default: ``\fboxrule`` + This legacy option sets the border-width (same on all sides) simultaneously + for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. + + .. versionchanged:: 8.1.0 New separate defaults. See :ref:`additionalcss`. .. important:: @@ -1148,6 +1148,11 @@ Additional CSS-like ``'sphinxsetup'`` keys set the foreground and background colors for the title as well as the LaTeX code for the icon. +.. versionadded:: 7.4.0 Customizability of the :rst:dir:`seealso` and + :rst:dir:`todo` directives. + +.. versionadded:: 8.1.0 Separate customizability and new defaults for the + :dudir:`topic`, contents_, and :dudir:`sidebar` directives. Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally imported from some genuine CSS external file, but currently they have to be used @@ -1198,18 +1203,16 @@ which is then followed by an underscore, then the property name. :header: Directive, Option prefix, LaTeX environment :rst:dir:`code-block`, ``pre``, ``sphinxVerbatim`` - :dudir:`topic`, ``div.topic``, ``sphinxShadowBox`` - contents_, ``div.topic``, ``sphinxShadowBox`` + :rst:dir:`literalinclude`, ``pre``, ``sphinxVerbatim`` + :dudir:`topic`, ``div.topic``, ``sphinxtopic`` + contents_, ``div.contents``, ``sphinxcontents`` + :dudir:`sidebar`, ``div.sidebar``, ``sphinxsidebar`` :dudir:`note`, ``div.note``, ``sphinxnote`` :dudir:`warning`, ``div.warning``, ``sphinxwarning`` further admonition types ````, ``div.``, ``sphinx`` :rst:dir:`seealso`, ``div.seealso``, ``sphinxseealso`` :rst:dir:`todo`, ``div.todo``, ``sphinxtodo`` - -.. versionadded:: 7.4.0 Customizability of the :rst:dir:`seealso` and - :rst:dir:`todo` directives. - Here are now these options as well as their common defaults. Replace below ```` by the actual prefix as explained above. Don't forget the underscore separating the prefix from the property names. @@ -1224,15 +1227,18 @@ forget the underscore separating the prefix from the property names. The default is that all those dimensions are equal. They are set to: * ``0.4pt`` for :rst:dir:`code-block`, - * ``0.5pt`` for :dudir:`topic` or contents_ directive, + * ``0.5pt`` for :dudir:`topic` and contents_ directive, + * ``1pt`` (top/bottom) and ``2pt`` (left/right) for :dudir:`sidebar` directive, * ``0.5pt`` for :dudir:`note` and other "light" admonitions, * ``0.5pt`` for :rst:dir:`seealso` and :rst:dir:`todo` directives, * ``1pt`` for :dudir:`warning` and other "strong" admonitions except :dudir:`error` which uses ``1.25pt``. - .. versionchanged:: 7.4.0 + .. versionchanged:: 7.4.0 Changed defaults for :dudir:`topic` and + :dudir:`error`. - Changed defaults for :dudir:`topic` and :dudir:`error`. + .. versionchanged:: 8.1.0 Distinct from :dudir:`topic` defaults for + :dudir:`sidebar`. - ``_box-decoration-break`` can be set to either ``clone`` or ``slice`` and configures the behavior at page breaks. @@ -1248,8 +1254,9 @@ forget the underscore separating the prefix from the property names. The defaults: * all four ``3pt`` for :rst:dir:`code-block`, - * ``10pt``, ``7pt``, ``12pt``, ``7pt`` for :dudir:`topic` or - contents_ directive, + * ``6pt``, ``7pt``, ``6pt``, ``7pt`` for :dudir:`topic`, + * ``10pt``, ``7pt``, ``12pt``, ``7pt`` for contents_, + * ``6pt``, ``5.5pt``, ``6pt``, ``5.5pt`` for :dudir:`sidebar`, * ``6pt``, ``7pt``, ``6pt``, ``7pt`` for all "light" admonitions as well as the :rst:dir:`seealso` and :rst:dir:`todo` directives. * ``6pt``, ``6.5pt``, ``6pt``, ``6.5pt`` for the strong admonition types @@ -1263,6 +1270,9 @@ forget the underscore separating the prefix from the property names. vertically across admonition types on same page in PDF. This is only a property of defaults, not a constraint on possible user choices. + .. versionchanged:: 8.1.0 Separate defaults for :dudir:`topic`, contents_, + and :dudir:`sidebar`. + - | ``_border-top-left-radius``, | ``_border-top-right-radius``, | ``_border-bottom-right-radius``, @@ -1274,16 +1284,19 @@ forget the underscore separating the prefix from the property names. The defaults: * ``3pt`` for :rst:dir:`code-block` (since 6.0.0) and all corners, - * ``12pt`` for the bottom right corner of :dudir:`topic`, other corners are - straight, + * ``8pt`` for all corners of :dudir:`topic`, + * ``12pt`` for the bottom right corner of contents_, others use ``0pt``, + * ``12pt`` for the top-left and bottom-right corners for :dudir:`sidebar`, + ``0pt`` for top-right and bottom-left. * all radii set to ``5pt`` for :dudir:`note`, :dudir:`hint` and :dudir:`tip`, * ``0pt``, i.e. straight corners for all other directives. - .. versionchanged:: 7.4.0 + .. versionchanged:: 7.4.0 :dudir:`topic` and :dudir:`note`\ -like + admonitions acquire (at least one) rounded corners. - :dudir:`topic` and :dudir:`note`\ -like admonitions acquire (at least one) - rounded corners. + .. versionchanged:: 8.1.0 Separate defaults for :dudir:`topic`, contents_, + and :dudir:`sidebar`. See a remark above about traps with spaces in LaTeX. - ``_box-shadow`` is special in so far as it may be: @@ -1294,10 +1307,17 @@ forget the underscore separating the prefix from the property names. * or two dimensions followed by the keyword ``inset``. The x-offset and y-offset may be negative. The default is ``none``, - *except* for the :dudir:`topic` or contents_ directives, for which it is - ``4pt 4pt``, i.e. the shadow has a width of ``4pt`` and extends to the right - and below the frame. The lateral shadow then extends into the page right - margin. + *except* for: + + - the contents_ directive: ``4pt 4pt``, i.e. the shadow has a width of + ``4pt`` and extends to the right and below the frame; the lateral shadow + extends into the page right margin, + + - the :dudir:`sidebar` directive: ``0pt 2pt``, i.e. a small shadow at + bottom. + + .. versionchanged:: 8.1.0 No shadow anymore for :dudir:`topic`. + - | ``_border-TeXcolor``, | ``_background-TeXcolor``, | ``_box-shadow-TeXcolor``, @@ -1314,14 +1334,14 @@ forget the underscore separating the prefix from the property names. - ``{HTML}{F7F7F7}`` serves as background color to all. - ``{HTML}{86989B}`` is border color of light admonitions (inclusive of - :rst:dir:`seealso` and :rst:dir:`todo`) as well as of :dudir:`topic` and - contents_ directives. + :rst:dir:`seealso` and :rst:dir:`todo`) as well as of :dudir:`topic`, + contents_ and :dudir:`sidebar` directives. - ``{HTML}{940000}`` is border color or :dudir:`warning`-type admonitions, except :dudir:`error` which uses ``{HTML}{B40000}``. - The only directives displaying a shadow per default are :dudir:`topic` and - contents_ (handled identically at LaTeX level) and their shadow color is - ``{HTML}{6C6C6C}``. For all others the default shadow color is black. + The only directives displaying a shadow per default are contents_ and + :dudir:`sidebar`. The shadow-color for the former is ``{HTML}{6C6C6C}`` + and for the latter ``{HTML}{9EACAF}``. The ``_TeXcolor`` stands for the CSS property "color", i.e. it influences the text color of the contents. As for the three other options, @@ -1340,19 +1360,16 @@ forget the underscore separating the prefix from the property names. start of the contents; for admonitions, this happens after the heading which reproduces the admonition type. -The next keys, for admonitions only, were all three added at 7.4.0. The -default colors are the ones applying to the current HTML rendering of Sphinx -own docs at https://www.sphinx-doc.org. +The next keys, for admonitions, :dudir:`topic`, contents_, and +:dudir:`sidebar`, were all three added at 7.4.0 (and 8.1.0 for the latter three). - ``div._title-background-TeXcolor``: the background color for the title. .. important:: The colored title-row is produced as a result of the Sphinx default - definitions for the various ``\sphinxstyletitle`` commands, see - :ref:`latex-macros`. Custom redefinitions of these commands are - possible, but to re-use the colors and the icon, it is needed to check in - Sphinx LaTeX source code how the default definitions are done. + definitions for the various ``\sphinxstyletitle`` commands, which + employ the ``\sphinxdotitlerow`` LaTeX command. See :ref:`latex-macros`. - ``div._title-foreground-TeXcolor``: the color to be used for the icon (it applies only to the icon, not to the title of the admonition). @@ -1429,24 +1446,20 @@ own docs at https://www.sphinx-doc.org. .. _ellipse: https://ctan.org/pkg/ellipse -The following legacy behavior is currently not customizable: +The following legacy behavior applies: -- For :rst:dir:`code-block`, padding and border-width and shadow (if one adds - one) will go into the margin; the code lines remain at the same place - independently of the values of the padding and border-width, except for - being shifted vertically of course to not overwrite other text due to the - width of the border or external shadow. +- For :rst:dir:`code-block` (or :rst:dir:`literalinclude`), padding and + border-width and shadow (if one adds one) will go into the margin; the code + lines remain at the same place independently of the values of the padding + and border-width, except for being shifted vertically of course to not + overwrite other text due to the width of the border or external shadow. -- For :dudir:`topic` (and contents_) the shadow (if on right) goes into the - page margin, but the border and the extra padding are kept within the text - area. Same for admonitions. +- For all others than :rst:dir:`code-block` (or :rst:dir:`literalinclude`) the + shadow (if on right) goes into the page margin, but the border and the extra + padding are kept within the text area. -- The contents_ and :dudir:`topic` directives are governed by the same options - with ``div.topic`` prefix: the Sphinx LaTeX mark-up uses for both directives - the same ``sphinxShadowBox`` environment which has currently no additional - branching, contrarily to the ``sphinxadmonition`` environment which branches - according to the admonition directive name, e.g. either to ``sphinxnote`` - or ``sphinxwarning`` etc... +- :rst:dir:`code-block` and :rst:dir:`literalinclude` use the same LaTeX + environment and commands and are not separately customizable. LaTeX macros and environments @@ -1565,8 +1578,8 @@ Macros ``\sphinxstyleliteralintitle``; ``\sphinxcode{#1}`` ``\sphinxstylecodecontinued``; ``{\footnotesize(#1)}}`` ``\sphinxstylecodecontinues``; ``{\footnotesize(#1)}}`` - ``\sphinxstylenotetitle``; ``\sphinxdotitlerowwithicon{note}{#1}`` - ``\sphinxstylehinttitle``; ``\sphinxdotitlerowwithicon{hint}{#1}`` + ``\sphinxstylenotetitle``; ``\sphinxdotitlerow{note}{#1}`` + ``\sphinxstylehinttitle``; ``\sphinxdotitlerow{hint}{#1}`` ``\sphinxstyleimportanttitle``; *similar* ``\sphinxstyletiptitle``; *similar* ``\sphinxstylewarningtitle``; *similar* @@ -1576,6 +1589,9 @@ Macros ``\sphinxstyleerrortitle``; *similar* ``\sphinxstyleseealsotitle``; *similar* ``\sphinxstyletodotitle``; *similar* + ``\sphinxstyletopictitle``; *similar* + ``\sphinxstylecontentstitle``; *similar* + ``\sphinxstylesidebartitle``; *similar* .. note:: @@ -1585,10 +1601,11 @@ Macros .. code-block:: latex \newcommand\sphinxstylenotetitle[1]% - {\sphinxdotitlerowwithicon{note}{\sphinxremovefinalcolon{#1}}} + {\sphinxdotitlerow{note}{\sphinxremovefinalcolon{#1}}} The same remark applies to all other similar commands associated with - admonitions. + admonitions. The :dudir:`topic`, contents_, and :dudir:`sidebar` do not + use it as they don't need it. .. versionadded:: 1.5 These macros were formerly hard-coded as non customizable ``\texttt``, @@ -1610,6 +1627,8 @@ Macros if this final colon is to be removed. .. versionadded:: 7.4.0 The ``\sphinxdotitlerowwithicon`` LaTeX command, + (renamed at 8.1.0 ``sphinxdotitlerow``, former name kept for backward + compatibility) whose first argument is the admonition type, so that it can recover the associated colours and icon for the title row, and the second argument gets typeset after the icon. @@ -1618,6 +1637,13 @@ Macros legacy artefact from old ill-designed Sphinx LaTeX writer, which postfixes (still today) the title with a colon automatically. + .. versionchanged:: 8.1.0 LaTeX command ``\sphinxdotitlerow`` detects + automatically if an icon is associated or not with the rendered element. + + .. versionchanged:: 8.1.0 Title rows for :dudir:`topic`, contents_, and + :dudir:`sidebar` directives (which have per defaults no associated + icons). + - ``\sphinxtableofcontents``: A wrapper (defined differently in :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard ``\tableofcontents``. The macro ``\sphinxtableofcontentshook`` is executed From bf34ac656651cc9ddf54766625ee7830a82665c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 29 Jul 2024 10:49:27 +0200 Subject: [PATCH 04/31] Mark-up glitch in docs --- doc/latex.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/latex.rst b/doc/latex.rst index 1a1b6628291..01a076b0816 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -961,7 +961,6 @@ The color used in the above example is available from having passed the .. versionchanged:: 8.1.0 New separate defaults. See :ref:`additionalcss`. ``shadowrule`` - This legacy option sets the border-width (same on all sides) simultaneously for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. From 07adb478cef9fa43fdf72ccf6d4d2ac16be5ef7d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 29 Jul 2024 11:24:01 +0200 Subject: [PATCH 05/31] LaTeX docs missing updates --- doc/latex.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 01a076b0816..0b308d92f1b 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1817,17 +1817,18 @@ Environments .. versionadded:: 6.1.0 .. versionchanged:: 6.2.0 - Colon made part of the mark-up rather than being inserted by the environment for coherence with how admonitions are handled generally. - Environment for the :rst:dir:`todo` directive: ``sphinxtodo``. - It takes one argument which will be the localized string ``Todo`` - followed with a colon. + It takes one argument which will is the localized string ``Todo`` + (with a colon at the end; the default rendering will remove that + colon and put the localized string in its own colored title-row). .. versionadded:: 7.4.0 -- The contents_ directive (with ``:local:`` option) and the - :dudir:`topic` directive are implemented by environment ``sphinxShadowBox``. +- The :dudir:`topic`, contents_ and :dudir:`sidebar` directives + are associated with respectively ``sphinxtopic``, ``sphinxcontents``, + and ``sphinxsidebar`` environments. .. versionadded:: 1.4.2 Former code refactored into an environment allowing page breaks. @@ -1835,7 +1836,12 @@ Environments .. versionchanged:: 1.5 Options ``shadowsep``, ``shadowsize``, ``shadowrule``. -- The literal blocks (via ``::`` or :rst:dir:`code-block`), are + .. versionadded:: 8.1.0 + Separate environments (all three wrappers around ``sphinxShadowBox``) + and separate customizability. + +- The literal blocks (via ``::`` or :rst:dir:`code-block`), and literal + includes (:rst:dir:`literalinclude`) are implemented using ``sphinxVerbatim`` environment which is a wrapper of ``Verbatim`` environment from package ``fancyvrb.sty``. It adds the handling of the top caption and the wrapping of long lines, and a frame which allows From e5e3866ed7c3da5d5b1e6ce89e9429ed4accef18 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 29 Jul 2024 11:48:12 +0200 Subject: [PATCH 06/31] LaTeX docs again, mainly pre-existing typos --- doc/latex.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 0b308d92f1b..732b1fc7572 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1335,7 +1335,7 @@ forget the underscore separating the prefix from the property names. - ``{HTML}{86989B}`` is border color of light admonitions (inclusive of :rst:dir:`seealso` and :rst:dir:`todo`) as well as of :dudir:`topic`, contents_ and :dudir:`sidebar` directives. - - ``{HTML}{940000}`` is border color or :dudir:`warning`-type admonitions, + - ``{HTML}{940000}`` is border color of :dudir:`warning`-type admonitions, except :dudir:`error` which uses ``{HTML}{B40000}``. The only directives displaying a shadow per default are contents_ and @@ -1626,10 +1626,10 @@ Macros if this final colon is to be removed. .. versionadded:: 7.4.0 The ``\sphinxdotitlerowwithicon`` LaTeX command, - (renamed at 8.1.0 ``sphinxdotitlerow``, former name kept for backward + (renamed at 8.1.0 ``\sphinxdotitlerow``, former name kept for backward compatibility) whose first argument is the admonition type, so that it can recover - the associated colours and icon for the title row, and the second + the associated colors and icon for the title row, and the second argument gets typeset after the icon. .. todo:: The fact that we must employ ``\sphinxremovefinalcolon`` is a @@ -1639,9 +1639,8 @@ Macros .. versionchanged:: 8.1.0 LaTeX command ``\sphinxdotitlerow`` detects automatically if an icon is associated or not with the rendered element. - .. versionchanged:: 8.1.0 Title rows for :dudir:`topic`, contents_, and - :dudir:`sidebar` directives (which have per defaults no associated - icons). + .. versionadded:: 8.1.0 Titles of :dudir:`topic`, contents_, and + :dudir:`sidebar` directives styled using ``\sphinxdotitlerow``. - ``\sphinxtableofcontents``: A wrapper (defined differently in :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard From 019d31c7bdc5a76f0ea55e10348bd23484953a00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Wed, 31 Jul 2024 11:07:20 +0200 Subject: [PATCH 07/31] Update LaTeX code comments --- sphinx/texinputs/sphinxlatexadmonitions.sty | 39 +++++++++++---------- sphinx/texinputs/sphinxlatexshadowbox.sty | 23 +++++++++--- 2 files changed, 39 insertions(+), 23 deletions(-) diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index f3041a2ad23..4a48c30c805 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -7,9 +7,6 @@ % % - sphinxseealso environment added at 6.1.0. % -% At 7.4.0 it too now uses sphinxheavybox, and has the same associated -% sphinxsetup CSS keys as admonitions do. -% % - sphinxtodo environment added at 7.4.0. % % - sphinxadmonition (environment) @@ -19,16 +16,21 @@ % sphinxheavybox since 6.2.0), % - warning, caution, attention, danger, error to use sphinxheavybox. % -% At 7.4.0 all admonitions use sphinxheavybox. +% Since 7.4.0 all admonitions use sphinxheavybox. % % - All environments sphinxnote, sphinxwarning, etc... can be redefined as % will by user. Thay have a single parameter #1 which is the title. % -% - The default sphinxnote, sphinxwarning, etc... use associated -% one-argument macros \sphinxstylenotetitle, \sphinxstylewarningtitle, etc -% which can be redefined. Their default is to use \sphinxdotitlerowwithicon -% to typeset the title in a coloured header row at top of the -% admonition. (new with 7.4.0) +% - Also redefinable by user are the one-argument commands +% * \sphinxstylenotetitle, +% * \sphinxstylewarningtitle, +% * etc.... one for each admonition type (also seealso and todo). +% +% - At 7.4.0, all commands of previous item use \sphinxdotitlerow. +% (the 7.4.0 name, still usable, was \sphinxdotitlerowwithicon; the 8.1.0 +% version is also used for topic, contents and sidebar directives, see +% sphinxlatexshadowbox.sty, and handles both "with icon" and "without +% icon" situations). % % The sphinxlightbox environment is kept for backward compatiblity, for user % custom code which used it via custom definitions done in preamble or via @@ -42,20 +44,21 @@ % (the 7.4.0 redefined \sphinxstylenotetitle will not work in sphinxlightbox, % so \sphinxstrong{#1} which was its former default is used above). -% -% Requires: -\RequirePackage{sphinxpackageboxes} -% 7.4.0 removes unneeded \spx@boxes@border -\RequirePackage{framed}% used by sphinxheavybox -% % Dependencies (they do not need to be defined at time of loading): % % - of course the various colour and dimension options handled via sphinx.sty -% % - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty +% - \savenotes/\spewnotes from sphinxpackagefootnote.sty +% - \ifspx@inframed defined in sphinx.sty +% - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty +% +% They are required either before or after by sphinx.sty anyhow, but for +% clarity we list them here: +\RequirePackage{framed} +\RequirePackage{sphinxlatexgraphics} +\RequirePackage{sphinxpackagefootnote} +\RequirePackage{sphinxpackageboxes} % -% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox) - % Provides: (also in sphinxlatexliterals.sty) % Only needed here by legacy (deprecated) sphinxlightbox environment. \providecommand*\sphinxvspacefixafterfrenchlists{% diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty index 0f7819255f0..620d52ee2ab 100644 --- a/sphinx/texinputs/sphinxlatexshadowbox.sty +++ b/sphinx/texinputs/sphinxlatexshadowbox.sty @@ -5,20 +5,33 @@ % Provides support for this output mark-up from Sphinx latex writer: % -% - sphinxtopic, sphinxcontents, sphinxsidebar (environments) +% - Environments: sphinxtopic, sphinxcontents, and sphinxsidebar. +% % These wrappers replace at 8.1.0 former direct use of sphinxShadowBox -% environment which did not allow separate styling. Their defaults -% use \sphinxdotitlerow macro from sphinxlatexadmonitions.sty +% environment which did not allow separate styling. +% +% - Commands: \sphinxstyletopictitle, \sphinxstylecontentstitle, and +% \sphinxstylesidebartitle. +% +% At 8.1.0 they default to use \sphinxdotitlerow whose definiion is done in +% sphinxlatexadmonitions.sty. There is also \sphinxstylesidebarsubtitle +% which does not use \sphinxdotitlerow. % % Dependencies (they do not need to be defined at time of loading): % % - of course the various colour and dimension options handled via sphinx.sty % - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty -% - \savenotes/\spewnotes from sphinxpackagefootnote +% - \savenotes/\spewnotes from sphinxpackagefootnote.sty % - \ifspx@inframed defined in sphinx.sty +% - \sphinxdotitlerow from sphinxlatexadmonitions.sty +% - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty % -% Requires: +% They are required either before or after by sphinx.sty anyhow, but for +% clarity we list them here: \RequirePackage{framed} +\RequirePackage{sphinxlatexgraphics} +\RequirePackage{sphinxpackagefootnote} +\RequirePackage{sphinxlatexadmonitions} \RequirePackage{sphinxpackageboxes} % At 5.1.0 the code formerly here in a definition of \spx@ShadowFBox has been From 617b80cab283a494aa6a5e7ca928035efb22a9a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Wed, 31 Jul 2024 11:20:04 +0200 Subject: [PATCH 08/31] Update CHANGES for PR #12704 --- CHANGES.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index 1d04bc27010..faeb9b0d5ae 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -13,6 +13,10 @@ Deprecated Features added -------------- +* #12704: LaTeX: make :dudir:`contents `, :dudir:`topic`, + and :dudir:`sidebar` directives separately customizable for PDF output. + Patch by Jean-François B. + Bugs fixed ---------- From ed08c49f5dc858e7c93d2be8d481c45cd71d2ff8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Wed, 31 Jul 2024 11:29:32 +0200 Subject: [PATCH 09/31] Again LaTeX code comments --- sphinx/texinputs/sphinxlatexadmonitions.sty | 4 ++-- sphinx/texinputs/sphinxlatexshadowbox.sty | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/sphinx/texinputs/sphinxlatexadmonitions.sty b/sphinx/texinputs/sphinxlatexadmonitions.sty index 4a48c30c805..2d50b2eb313 100644 --- a/sphinx/texinputs/sphinxlatexadmonitions.sty +++ b/sphinx/texinputs/sphinxlatexadmonitions.sty @@ -52,9 +52,9 @@ % - \ifspx@inframed defined in sphinx.sty % - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty % -% They are required either before or after by sphinx.sty anyhow, but for -% clarity we list them here: \RequirePackage{framed} +% Those are required either before or after by sphinx.sty anyhow, but for +% clarity we list them here: \RequirePackage{sphinxlatexgraphics} \RequirePackage{sphinxpackagefootnote} \RequirePackage{sphinxpackageboxes} diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty index 620d52ee2ab..ec892bc3b4f 100644 --- a/sphinx/texinputs/sphinxlatexshadowbox.sty +++ b/sphinx/texinputs/sphinxlatexshadowbox.sty @@ -26,9 +26,9 @@ % - \sphinxdotitlerow from sphinxlatexadmonitions.sty % - \spx@boxes@fcolorbox@setup from sphinxpackageboxes.sty % -% They are required either before or after by sphinx.sty anyhow, but for -% clarity we list them here: \RequirePackage{framed} +% Those are required either before or after by sphinx.sty anyhow, but for +% clarity we list them here: \RequirePackage{sphinxlatexgraphics} \RequirePackage{sphinxpackagefootnote} \RequirePackage{sphinxlatexadmonitions} From 8ee7838a9c6073c3a15e78cc47fadb468869dbae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Thu, 8 Aug 2024 21:50:18 +0200 Subject: [PATCH 10/31] Use 2pt for sidebar top border width to better match the bottom 1pt+2pt --- sphinx/texinputs/sphinx.sty | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 81e9623f0c7..39d92142fcc 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -403,9 +403,8 @@ \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}% 8.1.0 -\spx@tempa{spx@sidebar@} {div.sidebar_} {shadowrule} {1pt}% 8.1.0 -\@nameuse{KV@sphinx@div.sidebar_border-left-width}{2pt} -\@nameuse{KV@sphinx@div.sidebar_border-right-width}{2pt} +\spx@tempa{spx@sidebar@} {div.sidebar_} {shadowrule} {2pt}% 8.1.0 +\@nameuse{KV@sphinx@div.sidebar_border-bottom-width}{1pt} % 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{% From fcb260705e7dc134245371b2f49842c84682416f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Thu, 8 Aug 2024 21:54:57 +0200 Subject: [PATCH 11/31] Update docs --- doc/latex.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 732b1fc7572..f6de04a3343 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1227,7 +1227,8 @@ forget the underscore separating the prefix from the property names. * ``0.4pt`` for :rst:dir:`code-block`, * ``0.5pt`` for :dudir:`topic` and contents_ directive, - * ``1pt`` (top/bottom) and ``2pt`` (left/right) for :dudir:`sidebar` directive, + * ``2pt`` (but bottom-width only at ``1pt`` with a ``2pt`` shadow, see + below) for :dudir:`sidebar` directive, * ``0.5pt`` for :dudir:`note` and other "light" admonitions, * ``0.5pt`` for :rst:dir:`seealso` and :rst:dir:`todo` directives, * ``1pt`` for :dudir:`warning` and other "strong" admonitions except @@ -1313,7 +1314,7 @@ forget the underscore separating the prefix from the property names. extends into the page right margin, - the :dudir:`sidebar` directive: ``0pt 2pt``, i.e. a small shadow at - bottom. + bottom of width ``2pt`` (the border bottom-width being set to ``1pt``). .. versionchanged:: 8.1.0 No shadow anymore for :dudir:`topic`. From 2d94c6032efc1fa0d7f1f2da3d4abb1348170f84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 12 Aug 2024 19:00:03 +0200 Subject: [PATCH 12/31] Update doc/latex.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- doc/latex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/latex.rst b/doc/latex.rst index f6de04a3343..34d79b9d135 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1448,7 +1448,7 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and The following legacy behavior applies: -- For :rst:dir:`code-block` (or :rst:dir:`literalinclude`), padding and +- For :rst:dir:`code-block` or :rst:dir:`literalinclude`, padding and border-width and shadow (if one adds one) will go into the margin; the code lines remain at the same place independently of the values of the padding and border-width, except for being shifted vertically of course to not From 6825831e397ef14ef093eb6970972c2ac91c811d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 09:14:01 +0200 Subject: [PATCH 13/31] No default shadow for sidebar, thinner borders, docs updates --- doc/latex.rst | 91 ++++++++++------------- sphinx/texinputs/sphinx.sty | 9 +-- sphinx/texinputs/sphinxlatexshadowbox.sty | 4 +- 3 files changed, 45 insertions(+), 59 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 34d79b9d135..1b6b20670c4 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -942,30 +942,23 @@ The color used in the above example is available from having passed the .. important:: - At 8.1.0 it became possible to style separately the :dudir:`topic`, - contents_, and :dudir:`sidebar` directives, and each acquired new defaults. - See :ref:`additionalcss`. - The ``shadowsep``, ``shadowsize`` and ``shadowrule`` keys are kept for - backward compatibility only. + Since 8.1.0 it is possible to style separately the :dudir:`topic`, + contents_, and :dudir:`sidebar` directives, and their defaults differ. + See :ref:`additionalcss`. The next three keys are kept as legacy + interface not distinguishing between the three directives. ``shadowsep`` This legacy option sets the padding (same in all directions) simultaneously for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. - .. versionchanged:: 8.1.0 New separate defaults. See :ref:`additionalcss`. - ``shadowsize`` This legacy option sets the shadow width simultaneously for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. - .. versionchanged:: 8.1.0 New separate defaults. See :ref:`additionalcss`. - ``shadowrule`` This legacy option sets the border-width (same on all sides) simultaneously for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. - .. versionchanged:: 8.1.0 New separate defaults. See :ref:`additionalcss`. - .. important:: At 7.4.0 all admonitions (not only danger-type) use the possibilities @@ -1227,8 +1220,7 @@ forget the underscore separating the prefix from the property names. * ``0.4pt`` for :rst:dir:`code-block`, * ``0.5pt`` for :dudir:`topic` and contents_ directive, - * ``2pt`` (but bottom-width only at ``1pt`` with a ``2pt`` shadow, see - below) for :dudir:`sidebar` directive, + * ``1pt`` for :dudir:`sidebar` directive, * ``0.5pt`` for :dudir:`note` and other "light" admonitions, * ``0.5pt`` for :rst:dir:`seealso` and :rst:dir:`todo` directives, * ``1pt`` for :dudir:`warning` and other "strong" admonitions except @@ -1306,17 +1298,15 @@ forget the underscore separating the prefix from the property names. * or two dimensions (separated by a space), * or two dimensions followed by the keyword ``inset``. - The x-offset and y-offset may be negative. The default is ``none``, - *except* for: - - - the contents_ directive: ``4pt 4pt``, i.e. the shadow has a width of - ``4pt`` and extends to the right and below the frame; the lateral shadow - extends into the page right margin, + The x-offset and y-offset may be negative. A negative x-offset means + that the shadow is on the left. Whether positive or negative it extends + into the page margin. - - the :dudir:`sidebar` directive: ``0pt 2pt``, i.e. a small shadow at - bottom of width ``2pt`` (the border bottom-width being set to ``1pt``). + The default is ``none`` *except* for the contents_ directive which uses + ``4pt 4pt``. - .. versionchanged:: 8.1.0 No shadow anymore for :dudir:`topic`. + .. versionchanged:: 8.1.0 + No shadow per default for :dudir:`topic` and :dudir:`sidebar`. - | ``_border-TeXcolor``, | ``_background-TeXcolor``, @@ -1578,25 +1568,25 @@ Macros ``\sphinxstyleliteralintitle``; ``\sphinxcode{#1}`` ``\sphinxstylecodecontinued``; ``{\footnotesize(#1)}}`` ``\sphinxstylecodecontinues``; ``{\footnotesize(#1)}}`` - ``\sphinxstylenotetitle``; ``\sphinxdotitlerow{note}{#1}`` - ``\sphinxstylehinttitle``; ``\sphinxdotitlerow{hint}{#1}`` - ``\sphinxstyleimportanttitle``; *similar* - ``\sphinxstyletiptitle``; *similar* - ``\sphinxstylewarningtitle``; *similar* - ``\sphinxstylecautiontitle``; *similar* - ``\sphinxstyleattentiontitle``; *similar* - ``\sphinxstyledangertitle``; *similar* - ``\sphinxstyleerrortitle``; *similar* - ``\sphinxstyleseealsotitle``; *similar* - ``\sphinxstyletodotitle``; *similar* - ``\sphinxstyletopictitle``; *similar* - ``\sphinxstylecontentstitle``; *similar* - ``\sphinxstylesidebartitle``; *similar* + ``\sphinxstylenotetitle``; ``\sphinxdotitlerow{note}{#1}`` + ``\sphinxstylehinttitle``; ``\sphinxdotitlerow{hint}{#1}`` + ``\sphinxstyleimportanttitle``; ``\sphinxdotitlerow{important}{#1}`` + ``\sphinxstyletiptitle``; ``\sphinxdotitlerow{tip}{#1}`` + ``\sphinxstylewarningtitle``; ``\sphinxdotitlerow{warning}{#1}`` + ``\sphinxstylecautiontitle``; ``\sphinxdotitlerow{caution}{#1}`` + ``\sphinxstyleattentiontitle``; ``\sphinxdotitlerow{attention}{#1}`` + ``\sphinxstyledangertitle``; ``\sphinxdotitlerow{danger}{#1}`` + ``\sphinxstyleerrortitle``; ``\sphinxdotitlerow{error}{#1}`` + ``\sphinxstyleseealsotitle``; ``\sphinxdotitlerow{seealso}{#1}`` + ``\sphinxstyletodotitle``; ``\sphinxdotitlerow{todo}{#1}`` + ``\sphinxstyletopictitle``; ``\sphinxdotitlerow{topic}{#1}`` + ``\sphinxstylecontentstitle``; ``\sphinxdotitlerow{contents}{#1}`` + ``\sphinxstylesidebartitle``; ``\sphinxdotitlerow{sidebar}{#1}`` .. note:: To let this table fit on the page width in PDF output we have lied a bit - and the actual definition of ``\sphinxstylenotetitle`` is: + and the actual definition of, for example, ``\sphinxstylenotetitle`` is: .. code-block:: latex @@ -1605,7 +1595,7 @@ Macros The same remark applies to all other similar commands associated with admonitions. The :dudir:`topic`, contents_, and :dudir:`sidebar` do not - use it as they don't need it. + use ``\sphinxremovefinalcolon`` as they don't need it. .. versionadded:: 1.5 These macros were formerly hard-coded as non customizable ``\texttt``, @@ -1626,22 +1616,21 @@ Macros directive, with a final colon. Wrap it as ``\sphinxremovefinalcolon{#1}`` if this final colon is to be removed. - .. versionadded:: 7.4.0 The ``\sphinxdotitlerowwithicon`` LaTeX command, - (renamed at 8.1.0 ``\sphinxdotitlerow``, former name kept for backward - compatibility) - whose first argument is the admonition type, so that it can recover - the associated colors and icon for the title row, and the second - argument gets typeset after the icon. + .. versionadded:: 7.4.0 + ``\sphinxdotitlerowwithicon`` LaTeX command. - .. todo:: The fact that we must employ ``\sphinxremovefinalcolon`` is a - legacy artefact from old ill-designed Sphinx LaTeX writer, - which postfixes (still today) the title with a colon automatically. + .. versionchanged:: 8.1.0 + ``\sphinxdotitlerowwithicon`` now detects automatically if an icon is + associated or not with the rendered element used as first argument. - .. versionchanged:: 8.1.0 LaTeX command ``\sphinxdotitlerow`` detects - automatically if an icon is associated or not with the rendered element. + .. versionadded:: 8.1.0 + ``\sphinxdotitlerow`` as alias to ``\sphinxdotitlerowwithicon`` with + a more appropriate name. - .. versionadded:: 8.1.0 Titles of :dudir:`topic`, contents_, and - :dudir:`sidebar` directives styled using ``\sphinxdotitlerow``. + .. versionadded:: 8.1.0 + Titles of :dudir:`topic`, contents_, and :dudir:`sidebar` directives are + also styled using ``\sphinxdotitlerow`` (they have no default icons + associated with them). - ``\sphinxtableofcontents``: A wrapper (defined differently in :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 39d92142fcc..e40637e109e 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -403,8 +403,7 @@ \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}% 8.1.0 -\spx@tempa{spx@sidebar@} {div.sidebar_} {shadowrule} {2pt}% 8.1.0 -\@nameuse{KV@sphinx@div.sidebar_border-bottom-width}{1pt} +\spx@tempa{spx@sidebar@} {div.sidebar_} {shadowrule} {1pt}% 8.1.0 % 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{% @@ -465,7 +464,7 @@ \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}% 8.1.0 -\spx@tempa{spx@sidebar@} {div.sidebar_} {6pt}{5.5pt}{6pt}{5.5pt}% 8.1.0 +\spx@tempa{spx@sidebar@} {div.sidebar_} {6pt}{6.5pt}{6pt}{6.5pt}% 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} @@ -607,9 +606,7 @@ % 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 -% sidebar has only small shadow at bottom - \spx@sidebar@shadow@setter 0pt 2pt {} \@nnil -% topic has no shadow, nothing additional to do here +% topic and sidebar default to no shadow \spx@tempa{spx@note@} {div.note_} \spx@tempa{spx@hint@} {div.hint_} \spx@tempa{spx@important@}{div.important_} diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty index ec892bc3b4f..147e266a5f9 100644 --- a/sphinx/texinputs/sphinxlatexshadowbox.sty +++ b/sphinx/texinputs/sphinxlatexshadowbox.sty @@ -150,7 +150,7 @@ % 8.1.0 \newenvironment{sphinxtopic} - {\begin{sphinxShadowBox}\relax}{\end{sphinxShadowBox}} + {\begin{sphinxShadowBox}}{\end{sphinxShadowBox}} \newenvironment{sphinxcontents} {\begin{sphinxShadowBox}[contents]}{\end{sphinxShadowBox}} % Arguably sphinxsidebar should rather use a wrapfig or similar environment @@ -164,7 +164,7 @@ % % 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 +% to be any reason so back to \newcommand. \newcommand\sphinxstyletopictitle[1]{\sphinxdotitlerow{topic}{#1}} \newcommand\sphinxstylecontentstitle[1]{\sphinxdotitlerow{contents}{#1}} \newcommand\sphinxstylesidebartitle[1]{\sphinxdotitlerow{sidebar}{#1}} From 81df7cf47f73719f46b7a64f082da16ee7508012 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 09:34:59 +0200 Subject: [PATCH 14/31] Fix shadowsize key got broken for sidebar --- sphinx/texinputs/sphinx.sty | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index e40637e109e..dd30b6ea89c 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -627,6 +627,7 @@ \define@key{sphinx}{shadowsize}{% \def\spx@topic@shadow@xoffset{#1}% \let\spx@contents@shadow@xoffset\spx@topic@shadow@xoffset + \let\spx@sidebar@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 From 6d274466c6f4a547ed97834216b1bb0cdcd5f14f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 09:44:25 +0200 Subject: [PATCH 15/31] Apply suggestion to doc/latex.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- doc/latex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/latex.rst b/doc/latex.rst index 1b6b20670c4..99212a8b139 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1439,7 +1439,7 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and The following legacy behavior applies: - For :rst:dir:`code-block` or :rst:dir:`literalinclude`, padding and - border-width and shadow (if one adds one) will go into the margin; the code + border-width and shadow (if any) will go into the margin; the code lines remain at the same place independently of the values of the padding and border-width, except for being shifted vertically of course to not overwrite other text due to the width of the border or external shadow. From b48973f023064131b0157919da748274a1f6b0bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 09:45:32 +0200 Subject: [PATCH 16/31] Apply a suggestion to doc/latex.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- doc/latex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/latex.rst b/doc/latex.rst index 99212a8b139..140e80d7db5 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1444,7 +1444,7 @@ The following legacy behavior applies: and border-width, except for being shifted vertically of course to not overwrite other text due to the width of the border or external shadow. -- For all others than :rst:dir:`code-block` (or :rst:dir:`literalinclude`) the +- For the other directives, the shadow (if on right) goes into the page margin, but the border and the extra padding are kept within the text area. From 5eff50e8dabfef8b355e11e12c9a9d1928a2fdbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 10:22:14 +0200 Subject: [PATCH 17/31] Fix #12778 --- sphinx/texinputs/sphinx.sty | 9 +++------ tests/roots/test-root/conf.py | 13 +++++++++---- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index dd30b6ea89c..7e37d536b12 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -587,13 +587,10 @@ % used here. Since 6.2.0, expansion is delayed to time of use as for % the other dimensions handled above. This is synched with an added % encapsulation in \dimexpr...\relax by the "setup" from - % sphinxpackageboxes.sty. An induced regression had to be fixed in - % the sphinxShadowBox environment as it was using in an \ifdim the - % \spx@topic@shadow@yoffset macro, now holding by default 4pt+\z@ - % rather than an already digested 262144sp. The +\z@ is in case ##2 - % is empty. + % sphinxpackageboxes.sty. \else #1% - \def#6{##1}\def#7{##2+\z@}% + \def#6{##1}% + \if\relax\detokenize{##2}\relax\let#7#6\else\def#7{##2}\fi \if\relax\detokenize{##3}\relax#4\else#3\fi \fi }% diff --git a/tests/roots/test-root/conf.py b/tests/roots/test-root/conf.py index 1cc5c2f8fc7..21ec2922e97 100644 --- a/tests/roots/test-root/conf.py +++ b/tests/roots/test-root/conf.py @@ -70,10 +70,15 @@ % shadowrule=1pt, shadowsep=10pt, - shadowsize=10pt, - div.topic_border-width=2pt,% alias to shadowrule - div.topic_padding=6pt,% alias to shadowsep - div.topic_box-shadow=5pt,% overrides/alias shadowsize + shadowsize=-10pt, + div.topic_border-width=2pt, + div.topic_padding=6pt, + div.topic_box-shadow=5pt, + div.contents_border-width=3pt, + div.contents_padding=10pt, + div.contents_box-shadow=none, + div.sidebar_border-width=0pt, + div.sidebar_border-radius=0pt, % noteBorderColor={RGB}{204,204,204}, hintBorderColor={RGB}{204,204,204}, From 4de5e3746a54ab8d749d6bc597fa95df2785de04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 10:27:51 +0200 Subject: [PATCH 18/31] Update CHANGES.rst with #12778 fix --- CHANGES.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGES.rst b/CHANGES.rst index 3e6d87ed3c2..adb9a86d7bd 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -45,6 +45,9 @@ Bugs fixed Note, the priority of the transform has been changed from 200 to 622, so that it now runs after the docutils ``Footnotes`` resolution transform. Patch by Chris Sewell. +* #12778: LaTeX: let :ref:`'sphinxsetup' ` + ``div.topic_box-shadow`` key if used with only one dimension set both + x-offset and y-offset as per documentation. * #12587: Do not warn when potential ambiguity detected during Intersphinx resolution occurs due to duplicate targets that differ case-insensitively. Patch by James Addison. From c0054d24badc155f4ce7c80232058ea8c143524c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 10:28:12 +0200 Subject: [PATCH 19/31] Use [topic] explicitly for sphinxtopic wrapper of sphinxShadowBox --- sphinx/texinputs/sphinxlatexshadowbox.sty | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty index 147e266a5f9..555ede26f15 100644 --- a/sphinx/texinputs/sphinxlatexshadowbox.sty +++ b/sphinx/texinputs/sphinxlatexshadowbox.sty @@ -150,7 +150,7 @@ % 8.1.0 \newenvironment{sphinxtopic} - {\begin{sphinxShadowBox}}{\end{sphinxShadowBox}} + {\begin{sphinxShadowBox}[topic]}{\end{sphinxShadowBox}} \newenvironment{sphinxcontents} {\begin{sphinxShadowBox}[contents]}{\end{sphinxShadowBox}} % Arguably sphinxsidebar should rather use a wrapfig or similar environment From 7f633d822398065c6234e4cfce6ca936b75cef54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 10:51:33 +0200 Subject: [PATCH 20/31] Use \newcommand* for \sphinxstyletopictitle and friends --- sphinx/texinputs/sphinxlatexshadowbox.sty | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sphinx/texinputs/sphinxlatexshadowbox.sty b/sphinx/texinputs/sphinxlatexshadowbox.sty index 555ede26f15..53a333845aa 100644 --- a/sphinx/texinputs/sphinxlatexshadowbox.sty +++ b/sphinx/texinputs/sphinxlatexshadowbox.sty @@ -165,14 +165,14 @@ % 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]{\sphinxdotitlerow{topic}{#1}} -\newcommand\sphinxstylecontentstitle[1]{\sphinxdotitlerow{contents}{#1}} -\newcommand\sphinxstylesidebartitle[1]{\sphinxdotitlerow{sidebar}{#1}} +\newcommand*\sphinxstyletopictitle[1]{\sphinxdotitlerow{topic}{#1}} +\newcommand*\sphinxstylecontentstitle[1]{\sphinxdotitlerow{contents}{#1}} +\newcommand*\sphinxstylesidebartitle[1]{\sphinxdotitlerow{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}} +\newcommand*\sphinxstylesidebarsubtitle[1]{\sphinxAtStartPar\textbf{#1}} \endinput From cb795d67664964ad901565bb91a76c3a8aa0b351 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 11:23:38 +0200 Subject: [PATCH 21/31] Add test --- .../test-latex-contents-topic-sidebar/conf.py | 0 .../index.rst | 19 ++++++++++++ tests/test_builders/test_build_latex.py | 30 +++++++++++++++++++ 3 files changed, 49 insertions(+) create mode 100644 tests/roots/test-latex-contents-topic-sidebar/conf.py create mode 100644 tests/roots/test-latex-contents-topic-sidebar/index.rst diff --git a/tests/roots/test-latex-contents-topic-sidebar/conf.py b/tests/roots/test-latex-contents-topic-sidebar/conf.py new file mode 100644 index 00000000000..e69de29bb2d diff --git a/tests/roots/test-latex-contents-topic-sidebar/index.rst b/tests/roots/test-latex-contents-topic-sidebar/index.rst new file mode 100644 index 00000000000..d47e867f64d --- /dev/null +++ b/tests/roots/test-latex-contents-topic-sidebar/index.rst @@ -0,0 +1,19 @@ +test-contents-et-al +=================== + +.. contents:: + +test-topic +---------- + +.. topic:: Title of topic + + text of topic + +test-sidebar +------------ + +.. sidebar:: Title of sidebar + :subtitle: sub-title + + text of sidebar diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py index fb0f1bf4c57..0b79a826f93 100644 --- a/tests/test_builders/test_build_latex.py +++ b/tests/test_builders/test_build_latex.py @@ -2272,3 +2272,33 @@ def test_latex_rubric(app): content = (app.outdir / 'test.tex').read_text(encoding='utf8') assert r'\subsubsection*{This is a rubric}' in content assert r'\subsection*{A rubric with a heading level 2}' in content + + +@pytest.mark.sphinx('latex', testroot='latex-contents-topic-sidebar') +def test_latex_contents_topic_sidebar(app): + app.build() + result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') + + assert ( + '\\begin{sphinxcontents}\n' + '\\sphinxstylecontentstitle{Contents}\n' + ) in result + + assert ( + '\\begin{sphinxtopic}\n' + '\\sphinxstyletopictitle{Title of topic}\n' + '\n' + '\\sphinxAtStartPar\n' + 'text of topic\n' + '\\end{sphinxtopic}\n' + ) in result + + assert ( + '\\begin{sphinxsidebar}\n' + '\\sphinxstylesidebartitle{Title of sidebar}\n' + '\\sphinxstylesidebarsubtitle{sub\\sphinxhyphen{}title}\n' + '\n' + '\\sphinxAtStartPar\n' + 'text of sidebar\n' + '\\end{sphinxsidebar}\n' + ) in result From 67fff7041af3482718cf9171bc8bb79038633ab2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 11:41:20 +0200 Subject: [PATCH 22/31] Dear Ruff your style is not my taste! --- tests/test_builders/test_build_latex.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py index 0b79a826f93..8283a48a88a 100644 --- a/tests/test_builders/test_build_latex.py +++ b/tests/test_builders/test_build_latex.py @@ -2280,8 +2280,7 @@ def test_latex_contents_topic_sidebar(app): result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') assert ( - '\\begin{sphinxcontents}\n' - '\\sphinxstylecontentstitle{Contents}\n' + '\\begin{sphinxcontents}\n\\sphinxstylecontentstitle{Contents}\n' ) in result assert ( From 97a432354085ce57766d398031f3d46dab6897d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Tue, 13 Aug 2024 11:49:14 +0200 Subject: [PATCH 23/31] Ruff: calm down now! --- tests/test_builders/test_build_latex.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py index 8283a48a88a..5c90adfac56 100644 --- a/tests/test_builders/test_build_latex.py +++ b/tests/test_builders/test_build_latex.py @@ -2279,9 +2279,7 @@ def test_latex_contents_topic_sidebar(app): app.build() result = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') - assert ( - '\\begin{sphinxcontents}\n\\sphinxstylecontentstitle{Contents}\n' - ) in result + assert '\\begin{sphinxcontents}\n\\sphinxstylecontentstitle{Contents}\n' in result assert ( '\\begin{sphinxtopic}\n' From 6626dfe4d27a0337bb7a8d8d2affd6c0fb17c9ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 16:15:34 +0200 Subject: [PATCH 24/31] Update doc/latex.rst (suggestion 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- doc/latex.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 140e80d7db5..1eb361632de 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1140,10 +1140,12 @@ Additional CSS-like ``'sphinxsetup'`` keys set the foreground and background colors for the title as well as the LaTeX code for the icon. -.. versionadded:: 7.4.0 Customizability of the :rst:dir:`seealso` and +.. versionadded:: 7.4.0 + Customizability of the :rst:dir:`seealso` and :rst:dir:`todo` directives. -.. versionadded:: 8.1.0 Separate customizability and new defaults for the +.. versionadded:: 8.1.0 + Separate customizability and new defaults for the :dudir:`topic`, contents_, and :dudir:`sidebar` directives. Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally From 75ae99863af622347f8f969fab61b7f815797181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B=2E?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 16:28:55 +0200 Subject: [PATCH 25/31] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> --- doc/latex.rst | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index 1eb361632de..e892fd4bd88 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1301,8 +1301,8 @@ forget the underscore separating the prefix from the property names. * or two dimensions followed by the keyword ``inset``. The x-offset and y-offset may be negative. A negative x-offset means - that the shadow is on the left. Whether positive or negative it extends - into the page margin. + that the shadow is on the left. The shadow extends into the page margin, + whether the offset is positive or negative. The default is ``none`` *except* for the contents_ directive which uses ``4pt 4pt``. @@ -1446,9 +1446,8 @@ The following legacy behavior applies: and border-width, except for being shifted vertically of course to not overwrite other text due to the width of the border or external shadow. -- For the other directives, the - shadow (if on right) goes into the page margin, but the border and the extra - padding are kept within the text area. +- For the other directives, the shadow (if on right) goes into the page margin, + but the border and the extra padding are kept within the text area. - :rst:dir:`code-block` and :rst:dir:`literalinclude` use the same LaTeX environment and commands and are not separately customizable. @@ -1588,7 +1587,7 @@ Macros .. note:: To let this table fit on the page width in PDF output we have lied a bit - and the actual definition of, for example, ``\sphinxstylenotetitle`` is: + For instance, the actual definition of ``\sphinxstylenotetitle`` is: .. code-block:: latex @@ -1619,15 +1618,14 @@ Macros if this final colon is to be removed. .. versionadded:: 7.4.0 - ``\sphinxdotitlerowwithicon`` LaTeX command. + Added the ``\sphinxdotitlerowwithicon`` LaTeX command. .. versionchanged:: 8.1.0 ``\sphinxdotitlerowwithicon`` now detects automatically if an icon is associated or not with the rendered element used as first argument. .. versionadded:: 8.1.0 - ``\sphinxdotitlerow`` as alias to ``\sphinxdotitlerowwithicon`` with - a more appropriate name. + Make ``\sphinxdotitlerow`` an alias to ``\sphinxdotitlerowwithicon``. .. versionadded:: 8.1.0 Titles of :dudir:`topic`, contents_, and :dudir:`sidebar` directives are @@ -1812,11 +1810,12 @@ Environments environment for coherence with how admonitions are handled generally. - Environment for the :rst:dir:`todo` directive: ``sphinxtodo``. - It takes one argument which will is the localized string ``Todo`` + It takes one argument, namely the localization of ``Todo`` (with a colon at the end; the default rendering will remove that colon and put the localized string in its own colored title-row). .. versionadded:: 7.4.0 + - The :dudir:`topic`, contents_ and :dudir:`sidebar` directives are associated with respectively ``sphinxtopic``, ``sphinxcontents``, and ``sphinxsidebar`` environments. From 842a770cf5d6b34d38241aa4108ad8b67190a24f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 16:37:18 +0200 Subject: [PATCH 26/31] Line wrap after 8.1.0 (and one 7.4.0) in multiple versionchanged --- doc/latex.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/latex.rst b/doc/latex.rst index e892fd4bd88..acb58b37d10 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1228,11 +1228,11 @@ forget the underscore separating the prefix from the property names. * ``1pt`` for :dudir:`warning` and other "strong" admonitions except :dudir:`error` which uses ``1.25pt``. - .. versionchanged:: 7.4.0 Changed defaults for :dudir:`topic` and - :dudir:`error`. + .. versionchanged:: 7.4.0 + Changed defaults for :dudir:`topic` and :dudir:`error`. - .. versionchanged:: 8.1.0 Distinct from :dudir:`topic` defaults for - :dudir:`sidebar`. + .. versionchanged:: 8.1.0 + Distinct from :dudir:`topic` defaults for :dudir:`sidebar`. - ``_box-decoration-break`` can be set to either ``clone`` or ``slice`` and configures the behavior at page breaks. @@ -1264,8 +1264,8 @@ forget the underscore separating the prefix from the property names. vertically across admonition types on same page in PDF. This is only a property of defaults, not a constraint on possible user choices. - .. versionchanged:: 8.1.0 Separate defaults for :dudir:`topic`, contents_, - and :dudir:`sidebar`. + .. versionchanged:: 8.1.0 + Separate defaults for :dudir:`topic`, contents_, and :dudir:`sidebar`. - | ``_border-top-left-radius``, | ``_border-top-right-radius``, @@ -1289,8 +1289,8 @@ forget the underscore separating the prefix from the property names. .. versionchanged:: 7.4.0 :dudir:`topic` and :dudir:`note`\ -like admonitions acquire (at least one) rounded corners. - .. versionchanged:: 8.1.0 Separate defaults for :dudir:`topic`, contents_, - and :dudir:`sidebar`. + .. versionchanged:: 8.1.0 + Separate defaults for :dudir:`topic`, contents_, and :dudir:`sidebar`. See a remark above about traps with spaces in LaTeX. - ``_box-shadow`` is special in so far as it may be: From b46ef6e701924094edef36080d30f2d233d06e1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 16:38:03 +0200 Subject: [PATCH 27/31] A full stop --- doc/latex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/latex.rst b/doc/latex.rst index acb58b37d10..931bddfbcfb 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1586,7 +1586,7 @@ Macros .. note:: - To let this table fit on the page width in PDF output we have lied a bit + To let this table fit on the page width in PDF output we have lied a bit. For instance, the actual definition of ``\sphinxstylenotetitle`` is: .. code-block:: latex From 1b920aa0c7ad1e225e88df16aa4bfd1965fe96de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 16:39:16 +0200 Subject: [PATCH 28/31] Better wording for horizontal shadows extending into margin --- doc/latex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/latex.rst b/doc/latex.rst index 931bddfbcfb..9eec00a8ae3 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1446,7 +1446,7 @@ The following legacy behavior applies: and border-width, except for being shifted vertically of course to not overwrite other text due to the width of the border or external shadow. -- For the other directives, the shadow (if on right) goes into the page margin, +- For the other directives, shadows extend horizontally into the page margins, but the border and the extra padding are kept within the text area. - :rst:dir:`code-block` and :rst:dir:`literalinclude` use the same LaTeX From fc148fd94f65c82e662fdf1a1958a7be9318eef5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 16:44:30 +0200 Subject: [PATCH 29/31] Use indents of 2 spaces not 4 at some locations in LaTeX code --- sphinx/texinputs/sphinx.sty | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 7e37d536b12..0b7bc5e4c8e 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -407,9 +407,9 @@ % 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}% + \@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} @@ -483,9 +483,9 @@ % 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}% + \@nameuse{KV@sphinx@div.topic_padding}{#1}% + \@nameuse{KV@sphinx@div.contents_padding}{#1}% + \@nameuse{KV@sphinx@div.sidebar_padding}{#1}% }% % Corner radii keys From 3df4ce0301580caa8d6fc45547558d63af08c4d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 20:29:37 +0200 Subject: [PATCH 30/31] Update CHANGES.rst --- CHANGES.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index 6e7914c89d1..1bef287aeb2 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -30,7 +30,7 @@ Features added output files. * #12704: LaTeX: make :dudir:`contents `, :dudir:`topic`, and :dudir:`sidebar` directives separately customizable for PDF output. - Patch by Jean-François B. + Patch by Jean-François B. and Bénédikt Tran. * #12474: Support type-dependent search result highlighting via CSS. Patch by Tim Hoffmann. * #12743: No longer exit on the first warning when From 279d7613ad6686b2c51651b548789add4aaaa50d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-Fran=C3=A7ois=20B?= <2589111+jfbu@users.noreply.github.com> Date: Mon, 19 Aug 2024 20:36:16 +0200 Subject: [PATCH 31/31] One more versionchanged linewrap in doc/latex.rst --- doc/latex.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/latex.rst b/doc/latex.rst index 9eec00a8ae3..4704301bd57 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -1286,7 +1286,8 @@ forget the underscore separating the prefix from the property names. :dudir:`tip`, * ``0pt``, i.e. straight corners for all other directives. - .. versionchanged:: 7.4.0 :dudir:`topic` and :dudir:`note`\ -like + .. versionchanged:: 7.4.0 + :dudir:`topic` and :dudir:`note`\ -like admonitions acquire (at least one) rounded corners. .. versionchanged:: 8.1.0