Skip to content

Commit

Permalink
LaTeX: make contents, topic, and sidebar separately customizable
Browse files Browse the repository at this point in the history 
And give them some nice defaults to start with.
  • Loading branch information
@jfbu
jfbu committed Jul 28, 2024
1 parent 0cb3c07 commit e903f38
Show file tree
Hide file tree
Showing 5 changed files with 259 additions and 118 deletions.
97 changes: 85 additions & 12 deletions sphinx/texinputs/sphinx.sty
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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}
%
Expand Down Expand Up @@ -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@[email protected]_border-left-width}{2pt}
\@nameuse{KV@[email protected]_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@[email protected]_border-width}{#1}%
\@nameuse{KV@[email protected]_border-width}{#1}%
\@nameuse{KV@[email protected]_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}
Expand Down Expand Up @@ -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}
Expand All @@ -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@[email protected]_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@[email protected]_padding}{#1}%
\@nameuse{KV@[email protected]_padding}{#1}%
\@nameuse{KV@[email protected]_padding}{#1}%
}%

% Corner radii keys
%
Expand Down Expand Up @@ -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@
Expand Down Expand Up @@ -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@}
Expand Down Expand Up @@ -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_}
Expand All @@ -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
}%

Expand Down Expand Up @@ -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@}
Expand Down Expand Up @@ -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}
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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}
Expand Down
91 changes: 6 additions & 85 deletions sphinx/texinputs/sphinxlatexadmonitions.sty
View file
Original file line number Diff line number Diff line change
@@ -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:
%
Expand All @@ -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
Expand All @@ -43,7 +45,8 @@
% so \sphinxstrong{#1}<space> 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
Expand Down Expand Up @@ -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{<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{%
\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
Loading

0 comments on commit e903f38

Please sign in to comment.