1%% NOTICES AND ADMONITIONS
2%
3% change this info string if making any custom modification
4\ProvidesFile{sphinxlatexadmonitions.sty}[2021/01/27 admonitions]
5
6% Provides support for this output mark-up from Sphinx latex writer:
7%
8% - sphinxadmonition (environment)
9%   This is a dispatch supporting
10%
11%   - note, hint, important, tip                 (via sphinxlightbox)
12%   - warning, caution, attention, danger, error (via sphinxheavybox)
13%
14%   Each sphinx<notice name> environment can be redefined by user.
15%   The defaults are customizable via various colour and dimension
16%   settings, cf sphinx docs (latex customization).
17%
18% Requires:
19\RequirePackage{framed}% used by sphinxheavybox
20%
21% Dependencies (they do not need to be defined at time of loading):
22% - of course the various colour and dimension options handled via sphinx.sty
23% - \sphinxstrong (for sphinxlightbox and sphinxheavybox)
24% - dimension register \spx@image@maxheight from sphinxlatexgraphics.sty
25% - \savenotes/\spewnotes from sphinxpackagefootnote (for sphinxheavybox)
26
27% Provides: (also in sphinxlatexliterals.sty)
28\providecommand*\sphinxvspacefixafterfrenchlists{%
29   \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
30}
31
32% Some are quite plain
33% the spx@notice@bordercolor etc are set in the sphinxadmonition environment
34\newenvironment{sphinxlightbox}{%
35  \par
36  \noindent{\color{spx@notice@bordercolor}%
37            \rule{\linewidth}{\spx@notice@border}}\par\nobreak
38  {\parskip\z@skip\noindent}%
39  }
40  {%
41  % counteract previous possible negative skip (French lists!):
42  % (we can't cancel that any earlier \vskip introduced a potential pagebreak)
43  \sphinxvspacefixafterfrenchlists
44  \nobreak\vbox{\noindent\kern\@totalleftmargin
45      {\color{spx@notice@bordercolor}%
46       \rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
47             {\linewidth}{\spx@notice@border}}\hss}\allowbreak
48  }% end of sphinxlightbox environment definition
49% may be renewenvironment'd by user for complete customization
50\newenvironment{sphinxnote}[1]
51  {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
52\newenvironment{sphinxhint}[1]
53  {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
54\newenvironment{sphinximportant}[1]
55  {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
56\newenvironment{sphinxtip}[1]
57  {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
58% or just use the package options
59% these are needed for common handling by notice environment of lightbox
60% and heavybox but they are  currently not used by lightbox environment
61% and there is consequently no corresponding package option
62\definecolor{sphinxnoteBgColor}{rgb}{1,1,1}
63\definecolor{sphinxhintBgColor}{rgb}{1,1,1}
64\definecolor{sphinximportantBgColor}{rgb}{1,1,1}
65\definecolor{sphinxtipBgColor}{rgb}{1,1,1}
66
67% Others get more distinction
68% Code adapted from framed.sty's "snugshade" environment.
69% Nesting works (inner frames do not allow page breaks).
70\newenvironment{sphinxheavybox}{\par
71   \setlength{\FrameRule}{\spx@notice@border}%
72   \setlength{\FrameSep}{\dimexpr.6\baselineskip-\FrameRule\relax}
73   \advance\spx@image@maxheight
74   -\dimexpr2\FrameRule
75           +2\FrameSep
76           +\baselineskip\relax % will happen again if nested, needed indeed!
77   % configure framed.sty's parameters to obtain same vertical spacing
78   % as for "light" boxes. We need for this to manually insert parskip glue and
79   % revert a skip done by framed before the frame.
80    \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}%
81    \vspace{\FrameHeightAdjust}
82   % copied/adapted from framed.sty's snugshade
83   \def\FrameCommand##1{\hskip\@totalleftmargin
84       \fboxsep\FrameSep \fboxrule\FrameRule
85       \fcolorbox{spx@notice@bordercolor}{spx@notice@bgcolor}{##1}%
86       \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
87   \savenotes
88   % use a minipage if we are already inside a framed environment
89   \ifspx@inframed
90       \noindent\begin{minipage}{\linewidth}
91   \else
92       % handle case where notice is first thing in a list item (or is quoted)
93       \if@inlabel
94        \noindent\par\vspace{-\baselineskip}
95       \else
96        \vspace{\parskip}
97       \fi
98   \fi
99   \MakeFramed {\spx@inframedtrue
100     \advance\hsize-\width \@totalleftmargin\z@ \linewidth\hsize
101     % minipage initialization copied from LaTeX source code.
102     \@pboxswfalse
103     \let\@listdepth\@mplistdepth \@mplistdepth\z@
104     \@minipagerestore
105     \@setminipage }%
106   }
107   {%
108   \par\unskip
109   \@minipagefalse
110   \endMakeFramed
111   \ifspx@inframed\end{minipage}\fi
112   % set footnotes at bottom of page
113   \spewnotes
114   % arrange for similar spacing below frame as for "light" boxes.
115   \vskip .4\baselineskip
116   }% end of sphinxheavybox environment definition
117% may be renewenvironment'd by user for complete customization
118\newenvironment{sphinxwarning}[1]
119  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
120\newenvironment{sphinxcaution}[1]
121  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
122\newenvironment{sphinxattention}[1]
123  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
124\newenvironment{sphinxdanger}[1]
125  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
126\newenvironment{sphinxerror}[1]
127  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
128% or just use package options
129
130% the \colorlet of xcolor (if at all loaded) is overkill for our use case
131\newcommand{\sphinxcolorlet}[2]
132    {\expandafter\let\csname\@backslashchar color@#1\expandafter\endcsname
133                     \csname\@backslashchar color@#2\endcsname }
134
135% the main dispatch for all types of notices
136\newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
137  % can't use #1 directly in definition of end part
138  \def\spx@noticetype {#1}%
139  % set parameters of heavybox/lightbox
140  \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
141  \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
142  \spx@notice@border \dimexpr\csname spx@opt@#1border\endcsname\relax
143  % start specific environment, passing the heading as argument
144  \begin{sphinx#1}{#2}}
145  % workaround some LaTeX "feature" of \end command
146 {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
147
148\endinput
149