/
sphinxlatexadmonitions.sty
239 lines (233 loc) · 10 KB
/
sphinxlatexadmonitions.sty
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
%% NOTICES AND ADMONITIONS
%
% change this info string if making any custom modification
\ProvidesFile{sphinxlatexadmonitions.sty}[2022/07/03 admonitions]
% Provides support for this output mark-up from Sphinx latex writer:
%
% - sphinxadmonition (environment)
% This is a dispatch supporting
%
% - note, hint, important, tip (via sphinxlightbox)
% - warning, caution, attention, danger, error (via sphinxheavybox)
%
% Each sphinx<notice name> environment can be redefined by user.
% The defaults are customizable via various colour and dimension
% settings, cf sphinx docs (latex customization).
%
% Requires:
\RequirePackage{sphinxpackageboxes}
\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
% - \sphinxstrong (for sphinxlightbox and sphinxheavybox)
% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
% Provides: (also in sphinxlatexliterals.sty)
\providecommand*\sphinxvspacefixafterfrenchlists{%
\ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
}
% Some are quite plain
% the spx@notice@bordercolor etc are set in the sphinxadmonition environment
\newenvironment{sphinxlightbox}{%
\par
\noindent{\color{spx@notice@bordercolor}%
\rule{\linewidth}{\spx@notice@border}}\par\nobreak
{\parskip\z@skip\noindent}%
}
{%
% counteract previous possible negative skip (French lists!):
% (we can't cancel that any earlier \vskip introduced a potential pagebreak)
\sphinxvspacefixafterfrenchlists
\nobreak\vbox{\noindent\kern\@totalleftmargin
{\color{spx@notice@bordercolor}%
\rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
{\linewidth}{\spx@notice@border}}\hss}\allowbreak
}% end of sphinxlightbox environment definition
% may be renewenvironment'd by user for complete customization
\newenvironment{sphinxnote}[1]
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
\newenvironment{sphinxhint}[1]
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
\newenvironment{sphinximportant}[1]
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
\newenvironment{sphinxtip}[1]
{\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
% or just use the package options
% these are needed for common handling by notice environment of lightbox
% and heavybox but they are currently not used by lightbox environment
% and there is consequently no corresponding package option
\definecolor{sphinxnoteBgColor}{rgb}{1,1,1}
\definecolor{sphinxhintBgColor}{rgb}{1,1,1}
\definecolor{sphinximportantBgColor}{rgb}{1,1,1}
\definecolor{sphinxtipBgColor}{rgb}{1,1,1}
% Others get more distinction
\def\spx@admonitions@boxes@fcolorbox@setup{%
\spx@boxes@border@top \@nameuse{spx@\spx@noticetype @border@top}%
\spx@boxes@border@right \@nameuse{spx@\spx@noticetype @border@right}%
\spx@boxes@border@bottom\@nameuse{spx@\spx@noticetype @border@bottom}%
\spx@boxes@border@left \@nameuse{spx@\spx@noticetype @border@left}%
\spx@boxes@border \spx@notice@border
%
\spx@boxes@padding@top \@nameuse{spx@\spx@noticetype @padding@top}%
\spx@boxes@padding@right \@nameuse{spx@\spx@noticetype @padding@right}%
\spx@boxes@padding@bottom\@nameuse{spx@\spx@noticetype @padding@bottom}%
\spx@boxes@padding@left \@nameuse{spx@\spx@noticetype @padding@left}%
%
\spx@boxes@radius@topleft \@nameuse{spx@\spx@noticetype @radius@topleft}%
\spx@boxes@radius@topright \@nameuse{spx@\spx@noticetype @radius@topright}%
\spx@boxes@radius@bottomright \@nameuse{spx@\spx@noticetype @radius@bottomright}%
\spx@boxes@radius@bottomleft \@nameuse{spx@\spx@noticetype @radius@bottomleft}%
\relax
\iftrue\@nameuse{ifspx@\spx@noticetype @withshadow}%
\spx@boxes@withshadowtrue
\spx@boxes@shadow@xoffset \@nameuse{spx@\spx@noticetype @box@shadow@xoffset}%
\spx@boxes@shadow@yoffset \@nameuse{spx@\spx@noticetype @box@shadow@yoffset}\relax
\else
\spx@boxes@withshadowfalse
\fi\@nameuse{fi}%
\iftrue\@nameuse{ifspx@\spx@noticetype @insetshadow}%
\spx@boxes@insetshadowtrue
\else
\spx@boxes@insetshadowfalse
\fi\@nameuse{fi}%
\iftrue\@nameuse{ifspx@\spx@noticetype @withshadowcolor}%
\spx@boxes@withshadowcolortrue
\else
\spx@boxes@withshadowcolorfalse
\fi\@nameuse{fi}%
%
\iftrue\@nameuse{ifspx@\spx@noticetype @withbackgroundcolor}%
\spx@boxes@withbackgroundcolortrue
\else
\spx@boxes@withbackgroundcolorfalse
\fi\@nameuse{fi}%
\sphinxcolorlet{spx@boxes@backgroundcolor}{spx@notice@bgcolor}%
%
\iftrue\@nameuse{ifspx@\spx@noticetype @withbordercolor}%
\spx@boxes@withbordercolortrue
\else
\spx@boxes@withbordercolorfalse
\fi\@nameuse{fi}%
\sphinxcolorlet{spx@boxes@bordercolor}{spx@notice@bordercolor}%
%
\iftrue\@nameuse{ifspx@\spx@noticetype @withshadowcolor}%
\spx@boxes@withshadowcolortrue
\else
\spx@boxes@withshadowcolorfalse
\fi\@nameuse{fi}%
\sphinxcolorlet{spx@boxes@shadowcolor}{sphinx\spx@noticetype ShadowColor}%
}
% Code adapted from framed.sty's "snugshade" environment.
% Nesting works (inner frames do not allow page breaks).
\newenvironment{sphinxheavybox}{\par
\spx@admonitions@boxes@fcolorbox@setup
% Those are used by sphinxVerbatim if the \ifspx@inframed boolean is true
\setlength{\FrameRule}{0.5\dimexpr\spx@boxes@border@top+\spx@boxes@border@bottom\relax}%
% Prior to 5.1.0 \FrameSep served to configure the (unique) padding, via
% \fboxsep parameter of \fcolorbox; it was determined as 0.6\baselineskip -
% borderwidth, increasing borderwidth did not change text location
% vertically as borderwidth+padding remained constant. But this limited
% considerably (at most to 4pt or 5pt) the usual borderwidths.
% Now \FrameSep is not used, but is needed still by sphinxVerbatim (see
% prior comment above). We give it some reasonable definition.
\setlength{\FrameSep}{0.5\dimexpr\spx@boxes@padding@top+\spx@boxes@padding@bottom\relax}%
\advance\spx@image@maxheight
-\dimexpr\spx@boxes@border@top+\spx@boxes@border@bottom
+\spx@boxes@padding@top+\spx@boxes@padding@bottom
+\baselineskip\relax % will happen again if nested, needed indeed!
% MEMO: the next comment is before boxing was extended to allow padding and
% multiple border-widths, not to mention shadows...
% configure framed.sty's parameters to obtain same vertical spacing
% as for "light" boxes. We need for this to manually insert parskip glue and
% revert a skip done by framed before the frame.
\ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}%
\vspace{\FrameHeightAdjust}
% copied/adapted from framed.sty's snugshade
% but now using in place of \fcolorbox the Sphinx sophisticated own
\def\FrameCommand##1{\hskip\@totalleftmargin
\ifspx@boxes@withshadow
\ifspx@boxes@insetshadow\else
\ifdim\spx@boxes@shadow@xoffset<\z@\hskip\spx@boxes@shadow@xoffset\relax
\fi
\fi
\fi
\if1% use rounded boxes only if needed and possible
\ifdim\spx@boxes@radius@topleft >\z@0\fi
\ifdim\spx@boxes@radius@topright >\z@0\fi
\ifdim\spx@boxes@radius@bottomright>\z@0\fi
\ifdim\spx@boxes@radius@bottomleft >\z@0\fi
1\spx@boxes@fcolorbox{##1}%
\else
\@ifpackageloaded{pict2e}%
{\ifspx@boxes@insetshadow
\spx@boxes@fcolorbox{##1}%
\else
\spx@boxes@fcolorbox@rounded{##1}%
\fi}%
{\spx@boxes@fcolorbox{##1}}%
\fi
\ifspx@boxes@withshadow
\ifspx@boxes@insetshadow\else
\ifdim\spx@boxes@shadow@xoffset>\z@\hskip-\spx@boxes@shadow@xoffset\relax
\fi
\fi
\fi
\hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
\savenotes
% use a minipage if we are already inside a framed environment
\ifspx@inframed
\noindent\begin{minipage}{\linewidth}
\else
% handle case where notice is first thing in a list item (or is quoted)
\if@inlabel
\noindent\par\vspace{-\baselineskip}
\else
\vspace{\parskip}
\fi
\fi
\MakeFramed {\spx@inframedtrue
\advance\hsize-\width \@totalleftmargin\z@ \linewidth\hsize
% minipage initialization copied from LaTeX source code.
\@pboxswfalse
\let\@listdepth\@mplistdepth \@mplistdepth\z@
\@minipagerestore
\@setminipage }%
\color@begingroup % workaround to an upstream framed.sty bug
}
{%
\par\unskip
\color@endgroup % matches the \color@begingroup
\@minipagefalse
\endMakeFramed
\ifspx@inframed\end{minipage}\fi
% set footnotes at bottom of page
\spewnotes
% arrange for similar spacing below frame as for "light" boxes.
\vskip .4\baselineskip
}% end of sphinxheavybox environment definition
% may be renewenvironment'd by user for complete customization
\newenvironment{sphinxwarning}[1]
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
\newenvironment{sphinxcaution}[1]
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
\newenvironment{sphinxattention}[1]
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
\newenvironment{sphinxdanger}[1]
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
\newenvironment{sphinxerror}[1]
{\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
% or just use package options
% the main dispatch for all types of notices
\newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
% can't use #1 directly in definition of end part
\def\spx@noticetype {#1}%
% set parameters of heavybox/lightbox
\sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
\sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
\spx@notice@border \dimexpr\csname spx@opt@#1border\endcsname\relax
% start specific environment, passing the heading as argument
\begin{sphinx#1}{#2}}
% workaround some LaTeX "feature" of \end command
{\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
\endinput