Skip to content

Commit

Permalink
Renewed choices for admonition icons; suppress space if no icon
Browse files Browse the repository at this point in the history 
And set box-decoration-break to "slice" (not "clone") for all
admonitions.
  • Loading branch information
@jfbu
jfbu committed Jul 5, 2024
1 parent a8a7160 commit 9df853e
Show file tree
Hide file tree
Showing 3 changed files with 94 additions and 83 deletions.
134 changes: 70 additions & 64 deletions sphinx/texinputs/sphinx.sty
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,18 +37,24 @@
}
%% important build warnings use an undefined reference to induce latexmk
%% into complaining (once per warning) at very end of console output
\newcommand\sphinxbuildwarning[1]{%
\ifcsname sphinx_emitted_#1\endcsname
\newcommand\sphinxbuildwarning[2][]{%
\ifcsname sphinx_emitted_#2\endcsname
\else
\global\expandafter\let\csname sphinx_emitted_#1\endcsname\@empty
\global\expandafter\let\csname sphinx_emitted_#2\endcsname\@empty
\AtEndDocument{\hbox{% should the printing of text be made conditional on
% some boolean?
% some boolean? (7.4.0 answers this by adding an
% optional argument and testing it here for emptiness
% but no usage is made of this novelty yet.)
\if\relax\detokenize{#1}\relax
% No [], print a red warning text at very end of document
\bfseries\color{red}%
\@nameuse{sphinx_buildwarning_#1}%
\@nameuse{sphinx_buildwarning_#2}%
\fi
% place an undefined reference deliberately
\let\nfss@text\@gobble % no ??
\ref{!!\@nameuse{sphinx_buildwarning_#1}}%
}}%
\ref{!!\@nameuse{sphinx_buildwarning_#2}}%
}%
}%
\fi
}
\@namedef{sphinx_buildwarning_badtitlesec}{%
Expand All @@ -60,10 +66,6 @@
\@namedef{sphinx_buildwarning_badfootnotes}{%
Footnote rendering may have had problems, due to extra package or
document class; check latex log for instructions}%
\@namedef{sphinx_buildwarning_fontawesome5ismissing}{%
As fontawesome5 LaTeX package is not found, admonition titles
default to not using icons; check div.note\string_title-icon and
similar options for how to configure your own.}

%% OPTION HANDLING
%
Expand Down Expand Up @@ -102,13 +104,13 @@
\def\spx@definecolor{\expandafter\definecolor\spx@definedcolor}
% These internals refactored at 7.4.0:
\newcommand*{\spx@DeclareColorOption}[3][]{%
% #1 = almost always "sphinx" but left empty for a few
% #1 = almost always "sphinx" but left empty for a few for legacy reasons
% #2 = option name, but internal colour name is #1#2 (i.e. with prefix)
% #3 = initial default colour with either \definecolor or \colorlet syntax
% set the initial default
% Set the initial default
\spx@defineorletcolor{#1#2}#3\relax
% set the key handler to accept both \definecolor and \colorlet syntax
% the key name does not have the #1 prefix from the colour name
% Set the key handler to accept both \definecolor and \colorlet syntax
% The key name does not have the #1 prefix from the colour name
\define@key{sphinx}{#2}{\spx@defineorletcolor{#1#2}##1\relax}%
}%

Expand Down Expand Up @@ -214,11 +216,12 @@
\spx@DeclareColorOption{TitleColor}{{rgb}{0.126,0.263,0.361}}
\spx@DeclareColorOption{InnerLinkColor}{{rgb}{0.208,0.374,0.486}}
\spx@DeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}}
% The Verbatim ones are "legacy" only since 5.1.0... call it "new-legacy" ;-)
\spx@DeclareColorOption{VerbatimColor}{{RGB}{242,242,242}}% same as {gray}{0.95}
\spx@DeclareColorOption{VerbatimBorderColor}{{RGB}{32,32,32}}
% All other colours will be internally assigned a "sphinx" prefix

% Table row colors
% Table row colors (since 6.0.0)
% ----------------
\spx@DeclareColorOption[sphinx]{TableRowColorHeader}{{gray}{0.86}}
\spx@DeclareColorOption[sphinx]{TableRowColorOdd}{{gray}{0.92}}
Expand Down Expand Up @@ -332,7 +335,7 @@
% -------------------------------------------------------------
%
% So far the 5.1.0 added possibilities for fancier boxes had been used by
% default only for code-blocks, admonitions kept their old-fashioned
% default only for code-blocks, and admonitions kept their old-fashioned
% legacy styles. At 7.4.0, as a follow-up to the revamped styles of
% admonitions in the HTML sphinx13 theme (PR #12439), it is decided to
% apply similar styling for PDF output. Also the seealso directive
Expand All @@ -343,7 +346,7 @@
%
% Border keys
% At 7.4.0 refactoring to avoid defining legacy \spx@<type>@border
% macros which are used nowhere, only @top, @right, @bottom, @left.
% macros which are (now) used nowhere, only @top, @right, @bottom, @left.
\def\spx@tempa#1{% #1 = macro prefix
\expandafter\spx@tempb
\csname #1border@top\expandafter\endcsname
Expand All @@ -354,7 +357,7 @@
\csname #1border@opentrue\expandafter\endcsname
\csname #1border@openfalse\endcsname
}%
\def\spx@tempb #1#2#3#4#5#6#7#8{% #8 = option prefix
\def\spx@tempb #1#2#3#4#5#6#7#8#9{% #8 = option prefix
\define@key{sphinx}{#8border-top-width}{\def#1{##1}}%
\define@key{sphinx}{#8border-right-width}{\def#2{##1}}%
\define@key{sphinx}{#8border-bottom-width}{\def#3{##1}}%
Expand All @@ -364,21 +367,24 @@
\def#1{##1}\let#2#1\let#3#1\let#4#1%
}%
\newif#5%
% 6.2.0 has added support for box-decoration-break also to admonition
% directives, formerly the option setting was ignored for them.
\define@key{sphinx}{#8box-decoration-break}%
{\begingroup\edef\spx@tempa{##1}\expandafter\endgroup
\ifx\spx@tempa\spxstring@clone#7\else#6\fi}%
\spx@tempc{#8}% option prefix
}
\def\spx@tempc #1#2{% #1 = option prefix, #2 = legacy option name
% 7.4.0 sets the default behaviour to "slice" not only for code-blocks but
% also for admonitions, as the latter now have a background colour each.
#6%
% #8 = option prefix (with underscore), #9 = legacy option name
% keep legacy option names as aliases to new-named options
\expandafter\let\csname KV@sphinx@#2\expandafter\endcsname
\csname KV@sphinx@#1border-width\endcsname
\expandafter\let\csname KV@sphinx@#9\expandafter\endcsname
\csname KV@sphinx@#8border-width\endcsname
% init border-width (fetches next argument)
\csname KV@sphinx@#1border-width\endcsname
\csname KV@sphinx@#8border-width\endcsname
}
% MEMO: from 6.2.0 to 7.4.0 (excluive) \fboxrule was used in the first
% two, and was resolved only at location of use. At 7.4.0, we again
% use 0.4pt rather which is its default.
% use 0.4pt rather and not \fboxrule dimen register.
% macro prefix option prefix legacy option init value
\spx@tempa{spx@pre@} {pre_} {verbatimborder} {0.4pt}
\spx@tempa{spx@topic@} {div.topic_} {shadowrule} {0.4pt}
Expand All @@ -394,10 +400,9 @@
\spx@tempa{spx@error@} {div.error_} {errorborder} {2pt} % mod. at 7.4.0
% this one new at 6.2.0: (we do not create a "legacy name" for it)
\spx@tempa{spx@box@} {box_} {box_border-width}{0.4pt}
% Set default box-decoration-break style for codeblocks to slice
\spx@pre@border@opentrue % new default at 6.0.0: slice, not clone
% 6.2.0 has added support for box-decoration-break=slice to all
% other directives, formerly the option setting was ignored for them.
% Reset default box-decoration-break style to "clone" for \sphinxbox,
% but anyhow this is ignored as \sphinxbox produces unbreakable boxes.
\spx@box@border@openfalse

% Padding keys
% At 7.4.0, \spx@<type>@padding internal macros removed, only @top, @right,
Expand Down Expand Up @@ -466,8 +471,10 @@
}
% The init value for corner radius in code-blocks was \z@ (i.e. 0pt) prior
% to 6.0.0., then 3pt, then \fboxsep at 6.2.0 as padding was also \fboxsep.
% At 7.4.0 the 3pt is used (which is normal value of \fboxsep).
% At 7.4.0 some admonitions use rounded corners as well.
% At 7.4.0:
% - the 3pt is used (which is normal value of \fboxsep).
% - some admonitions use rounded corners as well.
% - topic boxed have only their bottom right corner rounded.
% macro prefix option prefix tl tr br bl
\spx@tempa{spx@pre@} {pre_} {3pt}{3pt}{3pt}{3pt}
\spx@tempa{spx@topic@} {div.topic_} \z@ \z@ {12pt} \z@
Expand Down Expand Up @@ -562,7 +569,6 @@
% This definition was broken due to a typo at 5.1.0 and got fixed at 6.1.2
% MEMO: at 6.2.0 this no longer does \number\dimexpr in an \edef. Reason is to
% keep in sync with div.topic_box-shadow handling of xoffset and yoffset.
% Attention in particular to \ifdim context, we add a \dimexpr to the one here.
\define@key{sphinx}{shadowsize}{%
\def\spx@topic@shadow@xoffset{#1}%
\let\spx@topic@shadow@yoffset\spx@topic@shadow@xoffset
Expand All @@ -586,13 +592,13 @@
% only internally used.
%
% For topic directive, "legacy" (around 2016-2017) had no interface for
% colors, so some internals could be changed with no breakage during 5.x up to
% 6.2.0. For example topic (shadowbox) could be unified with admonitions
% (sphinxheavybox), and the "set-up" macros could all be moved into a single
% colours, so some internals could be changed with no breakage during 5.x up
% to 6.2.0. For example topic (shadowbox) could be unified with admonitions
% (sphinxheavybox), and the "setup" macros could all be moved into a single
% one in the sphinxpackageboxes.sty file, with only one argument holding the
% directive type.
%
% It was then needed only for sphinxlatexliterals.sty to let its
% It was then needed only by sphinxlatexliterals.sty to let its emitted
% \spx@verb@boxes@fcolorbox@setup incorporate some extra adjustment.
%
% 7.4.0 removes usages of booleans relative to usage of a colour for
Expand Down Expand Up @@ -753,21 +759,20 @@
% The support for default icons:
\IfFileExists{fontawesome5.sty}{%
\RequirePackage{fontawesome5}
\@namedef{sphinx-icon-pencil}{\faIcon{pencil-alt}}
\@namedef{sphinx-icon-question}{\faIcon{question-circle}}
\@namedef{sphinx-icon-info}{\faIcon{info-circle}}
\@namedef{sphinx-icon-flame}{\faIcon{fire-alt}}
\@namedef{sphinx-icon-spark}{\faIcon{radiation}}% we did not find a good match
% to sphinx13.css svg spark icon in fontawesome 5 LaTeX package
\@namedef{sphinx-icon-warning}{\faIcon{exclamation-triangle}}
\@namedef{sphinx-icon-failure}{\faIcon{skull-crossbones}}%
% but times-circle would be more alike sphinx13.css --icon-failure
\def\spx@faIcon{\faIcon}
}%
{% no fontawasome5.sty
\sphinxbuildwarning{fontawesome5ismissing}%
\PackageWarningNoLine{sphinx}{fontawesome5 not available!\MessageBreak
Default admonition titles will use no icons.\MessageBreak
Check div.note_title-icon and similar options}
{% no fontawesome5.sty
% After some hesitation no warning is emitted: it is cumbersome to add code
% to emit a warning only if user has not made explicit usage of the title-icon
% keys.
%
% The hacky definition of \spx@faIcon below will still be operative for all
% remaining not set by user title-icon keys. It has the effect to prevent
% the execution of \sphinxtitlerowaftericonspacecmd (see
% \sphinxdotitlerowwithicon in sphinxlatexadmonitions.sty). If user sets a
% title-icon key to some LaTeX code of their own, of course \spx@faIcon is
% not executed and the inserted space will thus be there, as expected.
\let\spx@faIcon\@gobbletwo
}

% Now use the above colours as default settings, following the choices
Expand Down Expand Up @@ -799,19 +804,20 @@
%
% TODO: implement todo (sic)
%
% Icon defaults. These names are copied over from sphinx13.css
% and their actual LaTeX definitions are above and emulate the svg
% icons, if fontawesome5 was found, else they expand to do nothing.
div.note_title-icon=\@nameuse{sphinx-icon-pencil},
div.hint_title-icon=\@nameuse{sphinx-icon-question},
div.tip_title-icon=\@nameuse{sphinx-icon-info},
div.seealso_title-icon=\@nameuse{sphinx-icon-info},
div.important_title-icon=\@nameuse{sphinx-icon-flame},
div.caution_title-icon=\@nameuse{sphinx-icon-spark},
div.warning_title-icon=\@nameuse{sphinx-icon-warning},
div.attention_title-icon=\@nameuse{sphinx-icon-warning},
div.danger_title-icon=\@nameuse{sphinx-icon-spark},
div.error_title-icon=\@nameuse{sphinx-icon-failure},
% Icon defaults.
% Warning: \spx@faIcon is defined to do some trick if fontawesome5
% is absent, it is *not* a public macro to be used in custom user-level
% usage of the title-icon keys below!
div.note_title-icon =\spx@faIcon{info-circle},
div.hint_title-icon =\spx@faIcon{lightbulb},
div.tip_title-icon =\spx@faIcon{lightbulb},
div.seealso_title-icon =\spx@faIcon{share},
div.important_title-icon =\spx@faIcon{pause-circle},
div.caution_title-icon =\spx@faIcon{radiation},
div.warning_title-icon =\spx@faIcon{exclamation-triangle},
div.attention_title-icon =\spx@faIcon{exclamation-triangle},
div.danger_title-icon =\spx@faIcon{radiation},
div.error_title-icon =\spx@faIcon{skull-crossbones},
}

\newif\ifspx@opt@box@addstrut
Expand Down
41 changes: 23 additions & 18 deletions sphinx/texinputs/sphinxlatexadmonitions.sty
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,30 +7,30 @@
%
% - 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.
% At 7.4.0 it too now uses sphinxheavybox, and has the same associated
% sphinxsetup CSS keys as admonitions do.
%
% - sphinxadmonition (environment)
% This is a dispatch which originally configured
% This is a dispatch which formerly configured
%
% - note, hint, important, tip to use sphinxlightbox or optionnaly
% sphinxheavybox since 6.2.0.
% - note, hint, important, tip to use sphinxlightbox (or optionally
% sphinxheavybox since 6.2.0),
% - warning, caution, attention, danger, error to use sphinxheavybox.
%
% At 7.4.0 all admonitions use sphinxheavybox.
% At 7.4.0 all admonitions use sphinxheavybox.
%
% - all environments sphinxnote, sphinxwarning, etc... can be redefined
% as will by user. Thay have one parameter #1 which is the title.
% - All environments sphinxnote, sphinxwarning, etc... can be redefined as
% will by user. Thay have a single parameter #1 which is the title.
%
% - all default sphinxnote, sphinxwarning, etc... use associated
% one-argment macros \sphinxstylenotetitle, \sphinxstylewarningtitle,
% etc which can be redefined, and whose default is to use
% \sphinxdotitlerowwithicon to typeset the title in a coloured header
% row at top of the admonition. (new with 7.4.0)
% - The default sphinxnote, sphinxwarning, etc... use associated
% one-argument macros \sphinxstylenotetitle, \sphinxstylewarningtitle, etc
% which can be redefined. Their default is to use \sphinxdotitlerowwithicon
% to typeset the title in a coloured header row at top of the
% admonition. (new with 7.4.0)
%
% The sphinxlightbox environment is kept only for projects with LaTeX
% code which used it via custom definitions done in preamble or
% via raw latex directive.
% The sphinxlightbox environment is kept for backward compatiblity, for user
% custom code which used it via custom definitions done in preamble or via
% raw latex directive.
%
% Requires:
\RequirePackage{sphinxpackageboxes}
Expand Down Expand Up @@ -301,8 +301,13 @@
\sphinxcolorlet{spx@boxes@backgroundcolor}{sphinx#1TtlBgColor}%
\spx@boxes@fcolorbox{%
\makebox[\linewidth][l]{%
\textcolor{sphinx#1TtlFgColor}{\@nameuse{sphinx#1TtlIcon}}%
\sphinxtitlerowaftericonspacecmd
\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}%
}%
Expand Down
2 changes: 1 addition & 1 deletion sphinx/texinputs/sphinxpackageboxes.sty
View file
Original file line number Diff line number Diff line change
Expand Up @@ -525,7 +525,7 @@
\def\spx@boxes@fcolorbox@insetshadow{%
% BACKGROUND
% draw background and move back to reference point
% 6.4.0 always assumes a background color
% 7.4.0 always assumes a background color
{\color{spx@boxes@backgroundcolor}%
\vrule\@height\ht\spx@tempboxa
\@depth\dp\spx@tempboxa
Expand Down

0 comments on commit 9df853e

Please sign in to comment.