Skip to content

Commit

Permalink
Let titlerow macro auto-detect if using or not icon
Browse files Browse the repository at this point in the history
  • Loading branch information
@jfbu
jfbu committed Jul 29, 2024
1 parent e903f38 commit d6c0614
Show file tree
Hide file tree
Showing 4 changed files with 155 additions and 151 deletions.
50 changes: 25 additions & 25 deletions sphinx/texinputs/sphinx.sty
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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_}
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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}
Expand Down
102 changes: 97 additions & 5 deletions sphinx/texinputs/sphinxlatexadmonitions.sty
View file
Original file line number Diff line number Diff line change
@@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -45,8 +43,7 @@
% so \sphinxstrong{#1}<space> 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
Expand Down Expand Up @@ -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{<type>}
% 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
41 changes: 29 additions & 12 deletions sphinx/texinputs/sphinxlatexshadowbox.sty
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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):
%
Expand Down Expand Up @@ -55,17 +56,6 @@
% also requires later knowing a few more things: sphinx<type>TextColor and
% spx@<type>@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.
Expand Down Expand Up @@ -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
Loading

0 comments on commit d6c0614

Please sign in to comment.