source: flex_extract.git/documentation/Sphinx/build/latex/sphinx.sty @ f66f990

ctbtodev
Last change on this file since f66f990 was f66f990, checked in by Anne Philipp <anne.philipp@…>, 5 years ago

deleted jobscripts for tracking and updated Sphinx doc

  • Property mode set to 100644
File size: 74.4 KB
Line 
1%
2% sphinx.sty
3%
4% Adapted from the old python.sty, mostly written by Fred Drake,
5% by Georg Brandl.
6%
7
8\NeedsTeXFormat{LaTeX2e}[1995/12/01]
9\ProvidesPackage{sphinx}[2019/01/12 v1.8.4 LaTeX package (Sphinx markup)]
10
11% provides \ltx@ifundefined
12% (many packages load ltxcmds: graphicx does for pdftex and lualatex but
13% not xelatex, and anyhow kvoptions does, but it may be needed in future to
14% use \sphinxdeprecationwarning earlier, and it needs \ltx@ifundefined)
15\RequirePackage{ltxcmds}
16
17%% for deprecation warnings
18\newcommand\sphinxdeprecationwarning[4]{% #1 the deprecated macro or name,
19% #2 = when deprecated, #3 = when removed, #4 = additional info
20  \edef\spx@tempa{\detokenize{#1}}%
21  \ltx@ifundefined{sphinx_depr_\spx@tempa}{%
22     \global\expandafter\let\csname sphinx_depr_\spx@tempa\endcsname\spx@tempa
23     \expandafter\AtEndDocument\expandafter{\expandafter\let\expandafter
24         \sphinxdeprecatedmacro\csname sphinx_depr_\spx@tempa\endcsname
25         \PackageWarningNoLine{sphinx}{^^J**** SPHINX DEPRECATION WARNING:^^J
26         \sphinxdeprecatedmacro^^J
27         \@spaces- is deprecated at Sphinx #2^^J
28         \@spaces- and removed at Sphinx #3.^^J
29         #4^^J****}}%
30  }{% warning already emitted (at end of latex log), don't repeat
31  }}
32
33
34%% PACKAGES
35%
36% we delay handling of options to after having loaded packages, because
37% of the need to use \definecolor.
38\RequirePackage{graphicx}
39\@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}}
40% for \text macro and \iffirstchoice@ conditional even if amsmath not loaded
41\RequirePackage{amstext}
42\RequirePackage{textcomp}% "warn" option issued from template
43\RequirePackage{titlesec}
44\@ifpackagelater{titlesec}{2016/03/15}%
45 {\@ifpackagelater{titlesec}{2016/03/21}%
46  {}%
47  {\newif\ifsphinx@ttlpatch@ok
48   \IfFileExists{etoolbox.sty}{%
49     \RequirePackage{etoolbox}%
50     \patchcmd{\ttlh@hang}{\parindent\z@}{\parindent\z@\leavevmode}%
51                                {\sphinx@ttlpatch@oktrue}{}%
52     \ifsphinx@ttlpatch@ok
53     \patchcmd{\ttlh@hang}{\noindent}{}{}{\sphinx@ttlpatch@okfalse}%
54     \fi
55   }{}%
56   \ifsphinx@ttlpatch@ok
57     \typeout{^^J Package Sphinx Info: ^^J
58              **** titlesec 2.10.1 successfully patched for bugfix ****^^J}%
59   \else
60     \AtEndDocument{\PackageWarningNoLine{sphinx}{^^J%
61******** titlesec 2.10.1 has a bug, (section numbers disappear) ......|^^J%
62******** and Sphinx could not patch it, perhaps because your local ...|^^J%
63******** copy is already fixed without a changed release date. .......|^^J%
64******** If not, you must update titlesec! ...........................|}}%
65   \fi
66  }%
67 }{}
68\RequirePackage{tabulary}
69% tabulary has a bug with its re-definition of \multicolumn in its first pass
70% which is not \long. But now Sphinx does not use LaTeX's \multicolumn but its
71% own macro. Hence we don't even need to patch tabulary. See sphinxmulticell.sty
72% X or S (Sphinx) may have meanings if some table package is loaded hence
73% \X was chosen to avoid possibility of conflict
74\newcolumntype{\X}[2]{p{\dimexpr
75      (\linewidth-\arrayrulewidth)*#1/#2-\tw@\tabcolsep-\arrayrulewidth\relax}}
76\newcolumntype{\Y}[1]{p{\dimexpr
77      #1\dimexpr\linewidth-\arrayrulewidth\relax-\tw@\tabcolsep-\arrayrulewidth\relax}}
78% using here T (for Tabulary) feels less of a problem than the X could be
79\newcolumntype{T}{J}%
80% For tables allowing pagebreaks
81\RequirePackage{longtable}
82% User interface to set-up whitespace before and after tables:
83\newcommand*\sphinxtablepre {0pt}%
84\newcommand*\sphinxtablepost{\medskipamount}%
85% Space from caption baseline to top of table or frame of literal-block
86\newcommand*\sphinxbelowcaptionspace{.5\sphinxbaselineskip}%
87% as one can not use \baselineskip from inside longtable (it is zero there)
88% we need \sphinxbaselineskip, which defaults to \baselineskip
89\def\sphinxbaselineskip{\baselineskip}%
90% The following is to ensure that, whether tabular(y) or longtable:
91% - if a caption is on top of table:
92%   a) the space between its last baseline and the top rule of table is
93%      exactly \sphinxbelowcaptionspace
94%   b) the space from last baseline of previous text to first baseline of
95%      caption is exactly \parskip+\baselineskip+ height of a strut.
96%   c) the caption text will wrap at width \LTcapwidth (4in)
97% - make sure this works also if "caption" package is loaded by user
98%   (with its width or margin option taking place of \LTcapwidth role)
99% TODO: obtain same for caption of literal block: a) & c) DONE, b) TO BE DONE
100%
101% To modify space below such top caption, adjust \sphinxbelowcaptionspace
102% To add or remove space above such top caption, adjust \sphinxtablepre:
103%   notice that \abovecaptionskip, \belowcaptionskip, \LTpre are **ignored**
104% A. Table with longtable
105\def\sphinxatlongtablestart
106   {\par
107    \vskip\parskip
108    \vskip\dimexpr\sphinxtablepre\relax % adjust vertical position
109    \vbox{}% get correct baseline from above
110    \LTpre\z@skip\LTpost\z@skip % set to zero longtable's own skips
111    \edef\sphinxbaselineskip{\dimexpr\the\dimexpr\baselineskip\relax\relax}%
112   }%
113% Compatibility with caption package
114\def\sphinxthelongtablecaptionisattop{%
115    \spx@ifcaptionpackage{\noalign{\vskip-\belowcaptionskip}}{}%
116}%
117% Achieves exactly \sphinxbelowcaptionspace below longtable caption
118\def\sphinxlongtablecapskipadjust
119   {\dimexpr-\dp\strutbox
120            -\spx@ifcaptionpackage{\abovecaptionskip}{\sphinxbaselineskip}%
121            +\sphinxbelowcaptionspace\relax}%
122\def\sphinxatlongtableend{\prevdepth\z@\vskip\sphinxtablepost\relax}%
123% B. Table with tabular or tabulary
124\def\sphinxattablestart{\par\vskip\dimexpr\sphinxtablepre\relax}%
125\let\sphinxattableend\sphinxatlongtableend
126% This is used by tabular and tabulary templates
127\newcommand*\sphinxcapstartof[1]{%
128   \vskip\parskip
129   \vbox{}% force baselineskip for good positioning by capstart of hyperanchor
130   % hyperref puts the anchor 6pt above this baseline; in case of caption
131   % this baseline will be \ht\strutbox above first baseline of caption
132   \def\@captype{#1}%
133   \capstart
134% move back vertically, as tabular (or its caption) will compensate
135   \vskip-\baselineskip\vskip-\parskip
136}%
137\def\sphinxthecaptionisattop{% locate it after \sphinxcapstartof
138    \spx@ifcaptionpackage
139      {\caption@setposition{t}%
140       \vskip\baselineskip\vskip\parskip % undo those from \sphinxcapstartof
141       \vskip-\belowcaptionskip          % anticipate caption package skip
142       % caption package uses a \vbox, not a \vtop, so "single line" case
143       % gives different result from "multi-line" without this:
144       \nointerlineskip
145      }%
146      {}%
147}%
148\def\sphinxthecaptionisatbottom{% (not finalized; for template usage)
149    \spx@ifcaptionpackage{\caption@setposition{b}}{}%
150}%
151% The aim of \sphinxcaption is to apply to tabular(y) the maximal width
152% of caption as done by longtable
153\def\sphinxtablecapwidth{\LTcapwidth}%
154\newcommand\sphinxcaption{\@dblarg\spx@caption}%
155\long\def\spx@caption[#1]#2{%
156   \noindent\hb@xt@\linewidth{\hss
157      \vtop{\@tempdima\dimexpr\sphinxtablecapwidth\relax
158% don't exceed linewidth for the caption width
159            \ifdim\@tempdima>\linewidth\hsize\linewidth\else\hsize\@tempdima\fi
160% longtable ignores \abovecaptionskip/\belowcaptionskip, so do the same here
161            \abovecaptionskip\sphinxabovecaptionskip % \z@skip
162            \belowcaptionskip\sphinxbelowcaptionskip % \z@skip
163            \caption[{#1}]%
164               {\strut\ignorespaces#2\ifhmode\unskip\@finalstrut\strutbox\fi}%
165           }\hss}%
166   \par\prevdepth\dp\strutbox
167}%
168\def\sphinxabovecaptionskip{\z@skip}% Do not use! Flagged for removal
169\def\sphinxbelowcaptionskip{\z@skip}% Do not use! Flagged for removal
170% This wrapper of \abovecaptionskip is used in sphinxVerbatim for top
171% caption, and with another value in sphinxVerbatimintable
172% TODO: To unify space above caption of a code-block with the one above
173%       caption of a table/longtable, \abovecaptionskip must not be used
174%       This auxiliary will get renamed and receive a different meaning
175%       in future.
176\def\spx@abovecaptionskip{\abovecaptionskip}%
177% Achieve \sphinxbelowcaptionspace below a caption located above a tabular
178% or a tabulary
179\newcommand\sphinxaftertopcaption
180{%
181   \spx@ifcaptionpackage
182     {\par\prevdepth\dp\strutbox\nobreak\vskip-\abovecaptionskip}{\nobreak}%
183   \vskip\dimexpr\sphinxbelowcaptionspace\relax
184   \vskip-\baselineskip\vskip-\parskip
185}%
186% varwidth is crucial for our handling of general contents in merged cells
187\RequirePackage{varwidth}
188% but addition of a compatibility patch with hyperref is needed
189% (tested with varwidth v 0.92  Mar 2009)
190\AtBeginDocument {%
191    \let\@@vwid@Hy@raisedlink\Hy@raisedlink
192    \long\def\@vwid@Hy@raisedlink#1{\@vwid@wrap{\@@vwid@Hy@raisedlink{#1}}}%
193    \edef\@vwid@setup{%
194      \let\noexpand\Hy@raisedlink\noexpand\@vwid@Hy@raisedlink % HYPERREF !
195      \unexpanded\expandafter{\@vwid@setup}}%
196}%
197% Homemade package to handle merged cells
198\RequirePackage{sphinxmulticell}
199\RequirePackage{makeidx}
200% For framing code-blocks and warning type notices, and shadowing topics
201\RequirePackage{framed}
202% The xcolor package draws better fcolorboxes around verbatim code
203\IfFileExists{xcolor.sty}{
204    \RequirePackage{xcolor}
205}{
206    \RequirePackage{color}
207}
208% For highlighted code.
209\RequirePackage{fancyvrb}
210\define@key{FV}{hllines}{\def\sphinx@verbatim@checkifhl##1{\in@{, ##1,}{#1}}}
211% sphinxVerbatim must be usable by third party without requiring hllines set-up
212\def\sphinxresetverbatimhllines{\def\sphinx@verbatim@checkifhl##1{\in@false}}
213\sphinxresetverbatimhllines
214% For hyperlinked footnotes in tables; also for gathering footnotes from
215% topic and warning blocks. Also to allow code-blocks in footnotes.
216\RequirePackage{footnotehyper-sphinx}
217% For the H specifier. Do not \restylefloat{figure}, it breaks Sphinx code
218% for allowing figures in tables.
219\RequirePackage{float}
220% For floating figures in the text. Better to load after float.
221\RequirePackage{wrapfig}
222% Separate paragraphs by space by default.
223\IfFileExists{parskip-2001-04-09.sty}% since September 2018 TeXLive update
224% new parskip.sty, but let it rollback to old one.
225% hopefully TeX installation not broken and LaTeX kernel not too old
226   {\RequirePackage{parskip}[=v1]}
227% standard one from 1989. Admittedly \section of article/book gives possibly
228% anomalous spacing, but we can't require September 2018 release for some time.
229   {\RequirePackage{parskip}}
230% For parsed-literal blocks.
231\RequirePackage{alltt}
232% Display "real" single quotes in literal blocks.
233\RequirePackage{upquote}
234% control caption around literal-block
235\RequirePackage{capt-of}
236\RequirePackage{needspace}
237% LaTeX 2018-04-01 and later provides \@removefromreset
238\ltx@ifundefined{@removefromreset}
239    {\RequirePackage{remreset}}
240    {}% avoid warning
241% to make pdf with correct encoded bookmarks in Japanese
242% this should precede the hyperref package
243\ifx\kanjiskip\@undefined
244% for non-Japanese: make sure bookmarks are ok also with lualatex
245  \PassOptionsToPackage{pdfencoding=unicode}{hyperref}
246\else
247  \RequirePackage{atbegshi}
248  \ifx\ucs\@undefined
249    \ifnum 42146=\euc"A4A2
250      \AtBeginShipoutFirst{\special{pdf:tounicode EUC-UCS2}}
251    \else
252      \AtBeginShipoutFirst{\special{pdf:tounicode 90ms-RKSJ-UCS2}}
253    \fi
254  \else
255    \AtBeginShipoutFirst{\special{pdf:tounicode UTF8-UCS2}}
256  \fi
257\fi
258
259\ifx\@jsc@uplatextrue\@undefined\else
260  \PassOptionsToPackage{setpagesize=false}{hyperref}
261\fi
262
263% These options can be overriden inside  'hyperref' key
264% or by later use of \hypersetup.
265\PassOptionsToPackage{colorlinks,breaklinks,%
266 linkcolor=InnerLinkColor,filecolor=OuterLinkColor,%
267 menucolor=OuterLinkColor,urlcolor=OuterLinkColor,%
268 citecolor=InnerLinkColor}{hyperref}
269
270% stylesheet for highlighting with pygments
271\RequirePackage{sphinxhighlight}
272% fix baseline increase from Pygments latex formatter in case of error tokens
273% and keep \fboxsep's scope local via added braces
274\def\PYG@tok@err{%
275    \def\PYG@bc##1{{\setlength{\fboxsep}{-\fboxrule}%
276                    \fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}%
277}
278\def\PYG@tok@cs{%
279    \def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}%
280    \def\PYG@bc##1{{\setlength{\fboxsep}{0pt}%
281                    \colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}%
282}%
283
284
285%% OPTIONS
286%
287% Handle options via "kvoptions" (later loaded by hyperref anyhow)
288\RequirePackage{kvoptions}
289\SetupKeyvalOptions{prefix=spx@opt@} % use \spx@opt@ prefix
290
291% Sphinx legacy text layout: 1in margins on all four sides
292\ifx\@jsc@uplatextrue\@undefined
293\DeclareStringOption[1in]{hmargin}
294\DeclareStringOption[1in]{vmargin}
295\DeclareStringOption[.5in]{marginpar}
296\else
297% Japanese standard document classes handle \mag in a special way
298\DeclareStringOption[\inv@mag in]{hmargin}
299\DeclareStringOption[\inv@mag in]{vmargin}
300\DeclareStringOption[.5\dimexpr\inv@mag in\relax]{marginpar}
301\fi
302
303\DeclareStringOption[0]{maxlistdepth}% \newcommand*\spx@opt@maxlistdepth{0}
304\DeclareStringOption[-1]{numfigreset}
305\DeclareBoolOption[false]{nonumfigreset}
306\DeclareBoolOption[false]{mathnumfig}
307% \DeclareBoolOption[false]{usespart}% not used
308% dimensions, we declare the \dimen registers here.
309\newdimen\sphinxverbatimsep
310\newdimen\sphinxverbatimborder
311\newdimen\sphinxshadowsep
312\newdimen\sphinxshadowsize
313\newdimen\sphinxshadowrule
314% \DeclareStringOption is not convenient for the handling of these dimensions
315% because we want to assign the values to the corresponding registers. Even if
316% we added the code to the key handler it would be too late for the initial
317% set-up and we would need to do initial assignments explicitely. We end up
318% using \define@key directly.
319% verbatim
320\sphinxverbatimsep=\fboxsep
321  \define@key{sphinx}{verbatimsep}{\sphinxverbatimsep\dimexpr #1\relax}
322\sphinxverbatimborder=\fboxrule
323  \define@key{sphinx}{verbatimborder}{\sphinxverbatimborder\dimexpr #1\relax}
324% topic boxes
325\sphinxshadowsep =5pt
326  \define@key{sphinx}{shadowsep}{\sphinxshadowsep\dimexpr #1\relax}
327\sphinxshadowsize=4pt
328  \define@key{sphinx}{shadowsize}{\sphinxshadowsize\dimexpr #1\relax}
329\sphinxshadowrule=\fboxrule
330  \define@key{sphinx}{shadowrule}{\sphinxshadowrule\dimexpr #1\relax}
331% verbatim
332\DeclareBoolOption[true]{verbatimwithframe}
333\DeclareBoolOption[true]{verbatimwrapslines}
334\DeclareBoolOption[true]{verbatimhintsturnover}
335\DeclareBoolOption[true]{inlineliteralwraps}
336\DeclareStringOption[t]{literalblockcappos}
337\DeclareStringOption[r]{verbatimcontinuedalign}
338\DeclareStringOption[r]{verbatimcontinuesalign}
339% parsed literal
340\DeclareBoolOption[true]{parsedliteralwraps}
341% \textvisiblespace for compatibility with fontspec+XeTeX/LuaTeX
342\DeclareStringOption[\textcolor{red}{\textvisiblespace}]{verbatimvisiblespace}
343\DeclareStringOption % must use braces to hide the brackets
344  [{\makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\m@th\hookrightarrow$}}}]%
345  {verbatimcontinued}
346% notices/admonitions
347% the dimensions for notices/admonitions are kept as macros and assigned to
348% \spx@notice@border at time of use, hence \DeclareStringOption is ok for this
349\newdimen\spx@notice@border
350\DeclareStringOption[0.5pt]{noteborder}
351\DeclareStringOption[0.5pt]{hintborder}
352\DeclareStringOption[0.5pt]{importantborder}
353\DeclareStringOption[0.5pt]{tipborder}
354\DeclareStringOption[1pt]{warningborder}
355\DeclareStringOption[1pt]{cautionborder}
356\DeclareStringOption[1pt]{attentionborder}
357\DeclareStringOption[1pt]{dangerborder}
358\DeclareStringOption[1pt]{errorborder}
359% footnotes
360\DeclareStringOption[\mbox{ }]{AtStartFootnote}
361% we need a public macro name for direct use in latex file
362\newcommand*{\sphinxAtStartFootnote}{\spx@opt@AtStartFootnote}
363% no such need for this one, as it is used inside other macros
364\DeclareStringOption[\leavevmode\unskip]{BeforeFootnote}
365% some font styling.
366\DeclareStringOption[\sffamily\bfseries]{HeaderFamily}
367% colours
368% same problems as for dimensions: we want the key handler to use \definecolor.
369% first, some colours with no prefix, for backwards compatibility
370\newcommand*{\sphinxDeclareColorOption}[2]{%
371   \definecolor{#1}#2%
372   \define@key{sphinx}{#1}{\definecolor{#1}##1}%
373}%
374\sphinxDeclareColorOption{TitleColor}{{rgb}{0.126,0.263,0.361}}
375\sphinxDeclareColorOption{InnerLinkColor}{{rgb}{0.208,0.374,0.486}}
376\sphinxDeclareColorOption{OuterLinkColor}{{rgb}{0.216,0.439,0.388}}
377\sphinxDeclareColorOption{VerbatimColor}{{rgb}{1,1,1}}
378\sphinxDeclareColorOption{VerbatimBorderColor}{{rgb}{0,0,0}}
379% now the colours defined with "sphinx" prefix in their names
380\newcommand*{\sphinxDeclareSphinxColorOption}[2]{%
381   % set the initial default
382   \definecolor{sphinx#1}#2%
383   % set the key handler. The "value" ##1 must be acceptable by \definecolor.
384   \define@key{sphinx}{#1}{\definecolor{sphinx#1}##1}%
385}%
386% Default color chosen to be as in minted.sty LaTeX package!
387\sphinxDeclareSphinxColorOption{VerbatimHighlightColor}{{rgb}{0.878,1,1}}
388% admonition boxes, "light" style
389\sphinxDeclareSphinxColorOption{noteBorderColor}{{rgb}{0,0,0}}
390\sphinxDeclareSphinxColorOption{hintBorderColor}{{rgb}{0,0,0}}
391\sphinxDeclareSphinxColorOption{importantBorderColor}{{rgb}{0,0,0}}
392\sphinxDeclareSphinxColorOption{tipBorderColor}{{rgb}{0,0,0}}
393% admonition boxes, "heavy" style
394\sphinxDeclareSphinxColorOption{warningBorderColor}{{rgb}{0,0,0}}
395\sphinxDeclareSphinxColorOption{cautionBorderColor}{{rgb}{0,0,0}}
396\sphinxDeclareSphinxColorOption{attentionBorderColor}{{rgb}{0,0,0}}
397\sphinxDeclareSphinxColorOption{dangerBorderColor}{{rgb}{0,0,0}}
398\sphinxDeclareSphinxColorOption{errorBorderColor}{{rgb}{0,0,0}}
399\sphinxDeclareSphinxColorOption{warningBgColor}{{rgb}{1,1,1}}
400\sphinxDeclareSphinxColorOption{cautionBgColor}{{rgb}{1,1,1}}
401\sphinxDeclareSphinxColorOption{attentionBgColor}{{rgb}{1,1,1}}
402\sphinxDeclareSphinxColorOption{dangerBgColor}{{rgb}{1,1,1}}
403\sphinxDeclareSphinxColorOption{errorBgColor}{{rgb}{1,1,1}}
404
405\DeclareDefaultOption{\@unknownoptionerror}
406\ProcessKeyvalOptions*
407% don't allow use of maxlistdepth via \sphinxsetup.
408\DisableKeyvalOption{sphinx}{maxlistdepth}
409\DisableKeyvalOption{sphinx}{numfigreset}
410\DisableKeyvalOption{sphinx}{nonumfigreset}
411\DisableKeyvalOption{sphinx}{mathnumfig}
412% user interface: options can be changed midway in a document!
413\newcommand\sphinxsetup[1]{\setkeys{sphinx}{#1}}
414
415
416%% MAXLISTDEPTH
417%
418% remove LaTeX's cap on nesting depth if 'maxlistdepth' key used.
419% This is a hack, which works with the standard classes: it assumes \@toodeep
420% is always used in "true" branches: "\if ... \@toodeep \else .. \fi."
421
422% will force use the "false" branch (if there is one)
423\def\spx@toodeep@hack{\fi\iffalse}
424
425% do nothing if 'maxlistdepth' key not used or if package enumitem loaded.
426\ifnum\spx@opt@maxlistdepth=\z@\expandafter\@gobbletwo\fi
427\AtBeginDocument{%
428\@ifpackageloaded{enumitem}{\remove@to@nnil}{}%
429  \let\spx@toodeepORI\@toodeep
430  \def\@toodeep{%
431    \ifnum\@listdepth<\spx@opt@maxlistdepth\relax
432      \expandafter\spx@toodeep@hack
433    \else
434      \expandafter\spx@toodeepORI
435    \fi}%
436% define all missing \@list... macros
437  \count@\@ne
438  \loop
439     \ltx@ifundefined{@list\romannumeral\the\count@}
440       {\iffalse}{\iftrue\advance\count@\@ne}%
441  \repeat
442  \loop
443     \ifnum\count@>\spx@opt@maxlistdepth\relax\else
444       \expandafter\let
445         \csname @list\romannumeral\the\count@\expandafter\endcsname
446         \csname @list\romannumeral\the\numexpr\count@-\@ne\endcsname
447       % workaround 2.6--3.2d babel-french issue (fixed in 3.2e; no change needed)
448       \ltx@ifundefined{leftmargin\romannumeral\the\count@}
449       {\expandafter\let
450         \csname leftmargin\romannumeral\the\count@\expandafter\endcsname
451         \csname leftmargin\romannumeral\the\numexpr\count@-\@ne\endcsname}{}%
452     \advance\count@\@ne
453  \repeat
454% define all missing enum... counters and \labelenum... macros and \p@enum..
455  \count@\@ne
456  \loop
457     \ltx@ifundefined{c@enum\romannumeral\the\count@}
458       {\iffalse}{\iftrue\advance\count@\@ne}%
459  \repeat
460  \loop
461     \ifnum\count@>\spx@opt@maxlistdepth\relax\else
462       \newcounter{enum\romannumeral\the\count@}%
463       \expandafter\def
464         \csname labelenum\romannumeral\the\count@\expandafter\endcsname
465         \expandafter
466         {\csname theenum\romannumeral\the\numexpr\count@\endcsname.}%
467       \expandafter\def
468         \csname p@enum\romannumeral\the\count@\expandafter\endcsname
469         \expandafter
470         {\csname p@enum\romannumeral\the\numexpr\count@-\@ne\expandafter
471          \endcsname\csname theenum\romannumeral\the\numexpr\count@-\@ne\endcsname.}%
472     \advance\count@\@ne
473  \repeat
474% define all missing labelitem... macros
475  \count@\@ne
476  \loop
477     \ltx@ifundefined{labelitem\romannumeral\the\count@}
478     {\iffalse}{\iftrue\advance\count@\@ne}%
479  \repeat
480  \loop
481     \ifnum\count@>\spx@opt@maxlistdepth\relax\else
482       \expandafter\let
483         \csname labelitem\romannumeral\the\count@\expandafter\endcsname
484         \csname labelitem\romannumeral\the\numexpr\count@-\@ne\endcsname
485     \advance\count@\@ne
486  \repeat
487  \PackageInfo{sphinx}{maximal list depth extended to \spx@opt@maxlistdepth}%
488\@gobble\@nnil
489}
490
491
492%% INDEX, BIBLIOGRAPHY, APPENDIX, TABLE OF CONTENTS
493%
494% fix the double index and bibliography on the table of contents
495% in jsclasses (Japanese standard document classes)
496\ifx\@jsc@uplatextrue\@undefined\else
497  \renewenvironment{sphinxtheindex}
498    {\cleardoublepage\phantomsection
499     \begin{theindex}}
500    {\end{theindex}}
501
502  \renewenvironment{sphinxthebibliography}[1]
503    {\cleardoublepage% \phantomsection % not needed here since TeXLive 2010's hyperref
504     \begin{thebibliography}{#1}}
505    {\end{thebibliography}}
506\fi
507
508% disable \@chappos in Appendix in pTeX
509\ifx\kanjiskip\@undefined\else
510  \let\py@OldAppendix=\appendix
511  \renewcommand{\appendix}{
512    \py@OldAppendix
513    \gdef\@chappos{}
514  }
515\fi
516
517% make commands known to non-Sphinx document classes
518\providecommand*{\sphinxtableofcontents}{\tableofcontents}
519\ltx@ifundefined{sphinxthebibliography}
520 {\newenvironment
521  {sphinxthebibliography}{\begin{thebibliography}}{\end{thebibliography}}%
522 }
523 {}% else clause of \ltx@ifundefined
524\ltx@ifundefined{sphinxtheindex}
525 {\newenvironment{sphinxtheindex}{\begin{theindex}}{\end{theindex}}}%
526 {}% else clause of \ltx@ifundefined
527
528% for usage with xindy: this string gets internationalized in preamble
529\newcommand*{\sphinxnonalphabeticalgroupname}{}
530% redefined in preamble, headings for makeindex produced index
531\newcommand*{\sphinxsymbolsname}{}
532\newcommand*{\sphinxnumbersname}{}
533
534%% COLOR (general)
535%
536% FIXME: \normalcolor should probably be used in place of \py@NormalColor
537% elsewhere, and \py@NormalColor should never be defined. \normalcolor
538% switches to the colour from last \color call in preamble.
539\def\py@NormalColor{\color{black}}
540% FIXME: it is probably better to use \color{TitleColor}, as TitleColor
541% can be customized from 'sphinxsetup', and drop usage of \py@TitleColor
542\def\py@TitleColor{\color{TitleColor}}
543% FIXME: this line should be dropped, as "9" is default anyhow.
544\ifdefined\pdfcompresslevel\pdfcompresslevel = 9 \fi
545
546
547%% PAGE STYLING
548%
549% Style parameters and macros used by most documents here
550\raggedbottom
551\sloppy
552\hbadness = 5000                % don't print trivial gripes
553
554% Use \pagestyle{normal} as the primary pagestyle for text.
555% Redefine the 'normal' header/footer style when using "fancyhdr" package:
556\@ifpackageloaded{fancyhdr}{%
557  \ltx@ifundefined{c@chapter}
558  {% no \chapter, "howto" (non-Japanese) docclass
559   \fancypagestyle{plain}{
560    \fancyhf{}
561    \fancyfoot[C]{{\py@HeaderFamily\thepage}}
562    \renewcommand{\headrulewidth}{0pt}
563    \renewcommand{\footrulewidth}{0pt}
564   }
565   % Same as 'plain', this way we can use it in template
566   % FIXME: shouldn't this have a running header with Name and Release like 'manual'?
567   \fancypagestyle{normal}{
568    \fancyhf{}
569    \fancyfoot[C]{{\py@HeaderFamily\thepage}}
570    \renewcommand{\headrulewidth}{0pt}
571    \renewcommand{\footrulewidth}{0pt}
572   }
573  }%
574  {% classes with \chapter command
575   \fancypagestyle{normal}{
576    \fancyhf{}
577   % FIXME: this presupposes "twoside".
578   % If "oneside" class option, there are warnings in LaTeX log.
579    \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
580    \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
581    \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
582    \fancyhead[LE,RO]{{\py@HeaderFamily \@title\sphinxheadercomma\py@release}}
583    \renewcommand{\headrulewidth}{0.4pt}
584    \renewcommand{\footrulewidth}{0.4pt}
585    % define chaptermark with \@chappos when \@chappos is available for Japanese
586    \ltx@ifundefined{@chappos}{}
587      {\def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}}}
588    }
589  % Update the plain style so we get the page number & footer line,
590  % but not a chapter or section title.  This is to keep the first
591  % page of a chapter `clean.'
592   \fancypagestyle{plain}{
593    \fancyhf{}
594    \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
595    \renewcommand{\headrulewidth}{0pt}
596    \renewcommand{\footrulewidth}{0.4pt}
597    }
598   }
599  }
600  {% no fancyhdr: memoir class
601   % Provide default for 'normal' style simply as an alias of 'plain' style
602   % This way we can use \pagestyle{normal} in LaTeX template
603   \def\ps@normal{\ps@plain}
604   % Users of memoir class are invited to redefine 'normal' style in preamble
605  }
606
607% geometry
608\ifx\kanjiskip\@undefined
609  \PassOptionsToPackage{%
610     hmargin={\unexpanded{\spx@opt@hmargin}},%
611     vmargin={\unexpanded{\spx@opt@vmargin}},%
612     marginpar=\unexpanded{\spx@opt@marginpar}}
613  {geometry}
614\else
615 % set text width for Japanese documents to be integer multiple of 1zw
616 % and text height to be integer multiple of \baselineskip
617 % the execution is delayed to \sphinxsetup then geometry.sty
618 \normalsize\normalfont
619 \newcommand*\sphinxtextwidthja[1]{%
620    \if@twocolumn\tw@\fi
621    \dimexpr
622       \numexpr\dimexpr\paperwidth-\tw@\dimexpr#1\relax\relax/
623               \dimexpr\if@twocolumn\tw@\else\@ne\fi zw\relax
624    zw\relax}%
625 \newcommand*\sphinxmarginparwidthja[1]{%
626    \dimexpr\numexpr\dimexpr#1\relax/\dimexpr1zw\relax zw\relax}%
627 \newcommand*\sphinxtextlinesja[1]{%
628    \numexpr\@ne+\dimexpr\paperheight-\topskip-\tw@\dimexpr#1\relax\relax/
629                 \baselineskip\relax}%
630 \ifx\@jsc@uplatextrue\@undefined\else
631 % the way we found in order for the papersize special written by
632 % geometry in the dvi file to be correct in case of jsbook class
633   \ifnum\mag=\@m\else % do nothing special if nomag class option or 10pt
634     \PassOptionsToPackage{truedimen}{geometry}%
635   \fi
636 \fi
637 \PassOptionsToPackage{%
638    hmarginratio={1:1},%
639    textwidth=\unexpanded{\sphinxtextwidthja{\spx@opt@hmargin}},%
640    vmarginratio={1:1},%
641    lines=\unexpanded{\sphinxtextlinesja{\spx@opt@vmargin}},%
642    marginpar=\unexpanded{\sphinxmarginparwidthja{\spx@opt@marginpar}},%
643    footskip=2\baselineskip,%
644  }{geometry}%
645 \AtBeginDocument
646 {% update a dimension used by the jsclasses
647  \ifx\@jsc@uplatextrue\@undefined\else\fullwidth\textwidth\fi
648  % for some reason, jreport normalizes all dimensions with \@settopoint
649  \@ifclassloaded{jreport}
650    {\@settopoint\textwidth\@settopoint\textheight\@settopoint\marginparwidth}
651    {}% <-- "false" clause of \@ifclassloaded
652  }%
653\fi
654
655% fix fncychap's bug which uses prematurely the \textwidth value
656\@ifpackagewith{fncychap}{Bjornstrup}
657 {\AtBeginDocument{\mylen\textwidth\advance\mylen-2\myhi}}%
658 {}% <-- "false" clause of \@ifpackagewith
659
660
661%% TITLES
662%
663% Since Sphinx 1.5, users should use HeaderFamily key to 'sphinxsetup' rather
664% than defining their own \py@HeaderFamily command (which is still possible).
665% Memo: \py@HeaderFamily is also used by \maketitle as defined in
666% sphinxmanual.cls/sphinxhowto.cls
667\newcommand{\py@HeaderFamily}{\spx@opt@HeaderFamily}
668
669% This sets up the fancy chapter headings that make the documents look
670% at least a little better than the usual LaTeX output.
671\@ifpackagewith{fncychap}{Bjarne}{
672  \ChNameVar {\raggedleft\normalsize \py@HeaderFamily}
673  \ChNumVar  {\raggedleft\Large      \py@HeaderFamily}
674  \ChTitleVar{\raggedleft\Large      \py@HeaderFamily}
675  % This creates (numbered) chapter heads without the leading \vspace*{}:
676  \def\@makechapterhead#1{%
677    {\parindent \z@ \raggedright \normalfont
678      \ifnum \c@secnumdepth >\m@ne
679        \if@mainmatter
680          \DOCH
681        \fi
682      \fi
683      \interlinepenalty\@M
684      \if@mainmatter
685        \DOTI{#1}%
686      \else%
687        \DOTIS{#1}%
688      \fi
689    }}
690}{}% <-- "false" clause of \@ifpackagewith
691
692% Augment the sectioning commands used to get our own font family in place,
693% and reset some internal data items (\titleformat from titlesec package)
694\titleformat{\section}{\Large\py@HeaderFamily}%
695            {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor}
696\titleformat{\subsection}{\large\py@HeaderFamily}%
697            {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
698\titleformat{\subsubsection}{\py@HeaderFamily}%
699            {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
700% By default paragraphs (and subsubsections) will not be numbered because
701% sphinxmanual.cls and sphinxhowto.cls set secnumdepth to 2
702\titleformat{\paragraph}{\py@HeaderFamily}%
703            {\py@TitleColor\theparagraph}{0.5em}{\py@TitleColor}{\py@NormalColor}
704\titleformat{\subparagraph}{\py@HeaderFamily}%
705            {\py@TitleColor\thesubparagraph}{0.5em}{\py@TitleColor}{\py@NormalColor}
706
707
708%% GRAPHICS
709%
710% \sphinxincludegraphics defined to resize images larger than the line width,
711% except if height or width option present.
712%
713% If scale is present, rescale before fitting to line width. (since 1.5)
714\newbox\spx@image@box
715\newcommand*{\sphinxincludegraphics}[2][]{%
716  \in@{height}{#1}\ifin@\else\in@{width}{#1}\fi
717  \ifin@ % height or width present
718    \includegraphics[#1]{#2}%
719  \else % no height nor width (but #1 may be "scale=...")
720    \setbox\spx@image@box\hbox{\includegraphics[#1,draft]{#2}}%
721    \ifdim \wd\spx@image@box>\linewidth
722      \setbox\spx@image@box\box\voidb@x % clear memory
723      \includegraphics[#1,width=\linewidth]{#2}%
724    \else
725      \setbox\spx@image@box\box\voidb@x % clear memory
726      \includegraphics[#1]{#2}%
727    \fi
728  \fi
729}
730% \sphinxsafeincludegraphics resizes images larger than the line width,
731% or taller than about the text height (whether or not height/width options
732% were used). This is requested to avoid a crash with \MakeFramed as used by
733% sphinxShadowBox (topic/contents) and sphinxheavybox (admonitions), and also
734% by sphinxVerbatim (but a priori no image inclusion there).
735\newdimen\spx@image@maxheight
736% default maximal setting will get reduced by sphinxShadowBox/sphinxheavybox
737\AtBeginDocument{\spx@image@maxheight\textheight}
738\newcommand*{\sphinxsafeincludegraphics}[2][]{%
739    \gdef\spx@includegraphics@options{#1}%
740    \setbox\spx@image@box\hbox{\includegraphics[#1,draft]{#2}}%
741    \in@false
742    \ifdim \wd\spx@image@box>\linewidth
743      \g@addto@macro\spx@includegraphics@options{,width=\linewidth}%
744      \in@true
745    \fi
746    % no rotation, no need to worry about depth
747    \ifdim \ht\spx@image@box>\spx@image@maxheight
748      \g@addto@macro\spx@includegraphics@options{,height=\spx@image@maxheight}%
749      \in@true
750    \fi
751    \ifin@
752      \g@addto@macro\spx@includegraphics@options{,keepaspectratio}%
753    \fi
754    \setbox\spx@image@box\box\voidb@x % clear memory
755    \expandafter\includegraphics\expandafter[\spx@includegraphics@options]{#2}%
756}%
757
758
759%% FIGURE IN TABLE
760%
761\newenvironment{sphinxfigure-in-table}[1][\linewidth]{%
762  \def\@captype{figure}%
763  \sphinxsetvskipsforfigintablecaption
764  \begin{minipage}{#1}%
765}{\end{minipage}}
766% store the original \caption macro for usage with figures inside longtable
767% and tabulary cells. Make sure we get the final \caption in presence of
768% caption package, whether the latter was loaded before or after sphinx.
769\AtBeginDocument{%
770    \let\spx@originalcaption\caption
771    \@ifpackageloaded{caption}
772      {\let\spx@ifcaptionpackage\@firstoftwo
773       \caption@AtBeginDocument*{\let\spx@originalcaption\caption}%
774% in presence of caption package, drop our own \sphinxcaption whose aim was to
775% ensure same width of caption to all kinds of tables (tabular(y), longtable),
776% because caption package has its own width (or margin) option
777       \def\sphinxcaption{\caption}%
778      }%
779      {\let\spx@ifcaptionpackage\@secondoftwo}%
780}
781% tabulary expands twice contents, we need to prevent double counter stepping
782\newcommand*\sphinxfigcaption
783  {\ifx\equation$%$% this is trick to identify tabulary first pass
784       \firstchoice@false\else\firstchoice@true\fi
785   \spx@originalcaption }
786\newcommand*\sphinxsetvskipsforfigintablecaption
787  {\abovecaptionskip\smallskipamount
788   \belowcaptionskip\smallskipamount}
789
790
791%% CITATIONS
792%
793\protected\def\sphinxcite{\cite}
794
795%% FOOTNOTES
796%
797% Support large numbered footnotes in minipage
798% But now obsolete due to systematic use of \savenotes/\spewnotes
799% when minipages are in use in the various macro definitions next.
800\def\thempfootnote{\arabic{mpfootnote}}
801
802
803%% NUMBERING OF FIGURES, TABLES, AND LITERAL BLOCKS
804\ltx@ifundefined{c@chapter}
805   {\newcounter{literalblock}}%
806   {\newcounter{literalblock}[chapter]%
807    \def\theliteralblock{\ifnum\c@chapter>\z@\arabic{chapter}.\fi
808                         \arabic{literalblock}}%
809    }%
810\ifspx@opt@nonumfigreset
811    \ltx@ifundefined{c@chapter}{}{%
812      \@removefromreset{figure}{chapter}%
813      \@removefromreset{table}{chapter}%
814      \@removefromreset{literalblock}{chapter}%
815      \ifspx@opt@mathnumfig
816        \@removefromreset{equation}{chapter}%
817      \fi
818    }%
819    \def\thefigure{\arabic{figure}}%
820    \def\thetable {\arabic{table}}%
821    \def\theliteralblock{\arabic{literalblock}}%
822    \ifspx@opt@mathnumfig
823      \def\theequation{\arabic{equation}}%
824    \fi
825\else
826\let\spx@preAthefigure\@empty
827\let\spx@preBthefigure\@empty
828% \ifspx@opt@usespart  % <-- LaTeX writer could pass such a 'usespart' boolean
829%                      %     as sphinx.sty package option
830% If document uses \part, (triggered in Sphinx by latex_toplevel_sectioning)
831% LaTeX core per default does not reset chapter or section
832% counters at each part.
833% But if we modify this, we need to redefine \thechapter, \thesection to
834% include the part number and this will cause problems in table of contents
835% because of too wide numbering. Simplest is to do nothing.
836% \fi
837\ifnum\spx@opt@numfigreset>0
838    \ltx@ifundefined{c@chapter}
839      {}
840      {\g@addto@macro\spx@preAthefigure{\ifnum\c@chapter>\z@\arabic{chapter}.}%
841       \g@addto@macro\spx@preBthefigure{\fi}}%
842\fi
843\ifnum\spx@opt@numfigreset>1
844    \@addtoreset{figure}{section}%
845    \@addtoreset{table}{section}%
846    \@addtoreset{literalblock}{section}%
847    \ifspx@opt@mathnumfig
848      \@addtoreset{equation}{section}%
849    \fi
850    \g@addto@macro\spx@preAthefigure{\ifnum\c@section>\z@\arabic{section}.}%
851    \g@addto@macro\spx@preBthefigure{\fi}%
852\fi
853\ifnum\spx@opt@numfigreset>2
854    \@addtoreset{figure}{subsection}%
855    \@addtoreset{table}{subsection}%
856    \@addtoreset{literalblock}{subsection}%
857    \ifspx@opt@mathnumfig
858      \@addtoreset{equation}{subsection}%
859    \fi
860    \g@addto@macro\spx@preAthefigure{\ifnum\c@subsection>\z@\arabic{subsection}.}%
861    \g@addto@macro\spx@preBthefigure{\fi}%
862\fi
863\ifnum\spx@opt@numfigreset>3
864    \@addtoreset{figure}{subsubsection}%
865    \@addtoreset{table}{subsubsection}%
866    \@addtoreset{literalblock}{subsubsection}%
867    \ifspx@opt@mathnumfig
868      \@addtoreset{equation}{subsubsection}%
869    \fi
870    \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubsection>\z@\arabic{subsubsection}.}%
871    \g@addto@macro\spx@preBthefigure{\fi}%
872\fi
873\ifnum\spx@opt@numfigreset>4
874    \@addtoreset{figure}{paragraph}%
875    \@addtoreset{table}{paragraph}%
876    \@addtoreset{literalblock}{paragraph}%
877    \ifspx@opt@mathnumfig
878      \@addtoreset{equation}{paragraph}%
879    \fi
880    \g@addto@macro\spx@preAthefigure{\ifnum\c@subparagraph>\z@\arabic{subparagraph}.}%
881    \g@addto@macro\spx@preBthefigure{\fi}%
882\fi
883\ifnum\spx@opt@numfigreset>5
884    \@addtoreset{figure}{subparagraph}%
885    \@addtoreset{table}{subparagraph}%
886    \@addtoreset{literalblock}{subparagraph}%
887    \ifspx@opt@mathnumfig
888      \@addtoreset{equation}{subparagraph}%
889    \fi
890    \g@addto@macro\spx@preAthefigure{\ifnum\c@subsubparagraph>\z@\arabic{subsubparagraph}.}%
891    \g@addto@macro\spx@preBthefigure{\fi}%
892\fi
893\expandafter\g@addto@macro
894\expandafter\spx@preAthefigure\expandafter{\spx@preBthefigure}%
895\let\thefigure\spx@preAthefigure
896\let\thetable\spx@preAthefigure
897\let\theliteralblock\spx@preAthefigure
898\g@addto@macro\thefigure{\arabic{figure}}%
899\g@addto@macro\thetable{\arabic{table}}%
900\g@addto@macro\theliteralblock{\arabic{literalblock}}%
901  \ifspx@opt@mathnumfig
902    \let\theequation\spx@preAthefigure
903    \g@addto@macro\theequation{\arabic{equation}}%
904  \fi
905\fi
906
907
908%% LITERAL BLOCKS
909%
910% Based on use of "fancyvrb.sty"'s Verbatim.
911% - with framing allowing page breaks ("framed.sty")
912% - with breaking of long lines (exploits Pygments mark-up),
913% - with possibly of a top caption, non-separable by pagebreak.
914% - and usable inside tables or footnotes ("footnotehyper-sphinx").
915
916% For extensions which use \OriginalVerbatim and compatibility with Sphinx <
917% 1.5, we define and use these when (unmodified) Verbatim will be needed. But
918% Sphinx >= 1.5 does not modify the \Verbatim macro anymore.
919\let\OriginalVerbatim   \Verbatim
920\let\endOriginalVerbatim\endVerbatim
921
922% for captions of literal blocks
923% at start of caption title
924\newcommand*{\fnum@literalblock}{\literalblockname\nobreakspace\theliteralblock}
925% this will be overwritten in document preamble by Babel translation
926\newcommand*{\literalblockname}{Listing }
927% file extension needed for \caption's good functioning, the file is created
928% only if a \listof{literalblock}{foo} command is encountered, which is
929% analogous to \listoffigures, but for the code listings (foo = chosen title.)
930\newcommand*{\ext@literalblock}{lol}
931
932\newif\ifspx@inframed % flag set if we are already in a framed environment
933% if forced use of minipage encapsulation is needed (e.g. table cells)
934\newif\ifsphinxverbatimwithminipage   \sphinxverbatimwithminipagefalse
935
936% Framing macro for use with framed.sty's \FrameCommand
937%  - it obeys current indentation,
938%  - frame is \fboxsep separated from the contents,
939%  - the contents use the full available text width,
940%  - #1 = color of frame, #2 = color of background,
941%  - #3 = above frame, #4 = below frame, #5 = within frame,
942%  - #3 and #4 must be already typeset boxes; they must issue \normalcolor
943%    or similar, else, they are under scope of color #1
944\long\def\spx@fcolorbox #1#2#3#4#5{%
945  \hskip\@totalleftmargin
946  \hskip-\fboxsep\hskip-\fboxrule
947  % use of \color@b@x here is compatible with both xcolor.sty and color.sty
948  \color@b@x {\color{#1}\spx@CustomFBox{#3}{#4}}{\color{#2}}{#5}%
949  \hskip-\fboxsep\hskip-\fboxrule
950  \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth
951}%
952% #1 = for material above frame, such as a caption or a "continued" hint
953% #2 = for material below frame, such as a caption or "continues on next page"
954% #3 = actual contents, which will be typeset with a background color
955\long\def\spx@CustomFBox#1#2#3{%
956  \begingroup
957  \setbox\@tempboxa\hbox{{#3}}% inner braces to avoid color leaks
958  \vbox{#1% above frame
959            % draw frame border _latest_ to avoid pdf viewer issue
960            \kern\fboxrule
961            \hbox{\kern\fboxrule
962                  \copy\@tempboxa
963                  \kern-\wd\@tempboxa\kern-\fboxrule
964                  \vrule\@width\fboxrule
965                  \kern\wd\@tempboxa
966                  \vrule\@width\fboxrule}%
967            \kern-\dimexpr\ht\@tempboxa+\dp\@tempboxa+\fboxrule\relax
968            \hrule\@height\fboxrule
969            \kern\dimexpr\ht\@tempboxa+\dp\@tempboxa\relax
970            \hrule\@height\fboxrule
971        #2% below frame
972       }%
973  \endgroup
974}%
975\def\spx@fcolorbox@put@c#1{% hide width from framed.sty measuring
976    \moveright\dimexpr\fboxrule+.5\wd\@tempboxa\hb@xt@\z@{\hss#1\hss}%
977}%
978\def\spx@fcolorbox@put@r#1{% right align with contents, width hidden
979    \moveright\dimexpr\fboxrule+\wd\@tempboxa-\fboxsep\hb@xt@\z@{\hss#1}%
980}%
981\def\spx@fcolorbox@put@l#1{% left align with contents, width hidden
982    \moveright\dimexpr\fboxrule+\fboxsep\hb@xt@\z@{#1\hss}%
983}%
984%
985\def\sphinxVerbatim@Continued
986   {\csname spx@fcolorbox@put@\spx@opt@verbatimcontinuedalign\endcsname
987    {\normalcolor\sphinxstylecodecontinued\literalblockcontinuedname}}%
988\def\sphinxVerbatim@Continues
989   {\csname spx@fcolorbox@put@\spx@opt@verbatimcontinuesalign\endcsname
990    {\normalcolor\sphinxstylecodecontinues\literalblockcontinuesname}}%
991\def\sphinxVerbatim@Title
992   {\spx@fcolorbox@put@c{\unhcopy\sphinxVerbatim@TitleBox}}%
993\let\sphinxVerbatim@Before\@empty
994\let\sphinxVerbatim@After\@empty
995% Defaults are redefined in document preamble according to language
996\newcommand*\literalblockcontinuedname{continued from previous page}%
997\newcommand*\literalblockcontinuesname{continues on next page}%
998%
999\def\spx@verbatimfcolorbox{\spx@fcolorbox{VerbatimBorderColor}{VerbatimColor}}%
1000\def\sphinxVerbatim@FrameCommand
1001   {\spx@verbatimfcolorbox\sphinxVerbatim@Before\sphinxVerbatim@After}%
1002\def\sphinxVerbatim@FirstFrameCommand
1003   {\spx@verbatimfcolorbox\sphinxVerbatim@Before\sphinxVerbatim@Continues}%
1004\def\sphinxVerbatim@MidFrameCommand
1005   {\spx@verbatimfcolorbox\sphinxVerbatim@Continued\sphinxVerbatim@Continues}%
1006\def\sphinxVerbatim@LastFrameCommand
1007   {\spx@verbatimfcolorbox\sphinxVerbatim@Continued\sphinxVerbatim@After}%
1008
1009% For linebreaks inside Verbatim environment from package fancyvrb.
1010\newbox\sphinxcontinuationbox
1011\newbox\sphinxvisiblespacebox
1012\newcommand*\sphinxafterbreak {\copy\sphinxcontinuationbox}
1013
1014% Take advantage of the already applied Pygments mark-up to insert
1015% potential linebreaks for TeX processing.
1016%        {, <, #, %, $, ' and ": go to next line.
1017%        _, }, ^, &, >, - and ~: stay at end of broken line.
1018% Use of \textquotesingle for straight quote.
1019% FIXME: convert this to package options ?
1020\newcommand*\sphinxbreaksbeforelist {%
1021    \do\PYGZob\{\do\PYGZlt\<\do\PYGZsh\#\do\PYGZpc\%% {, <, #, %,
1022    \do\PYGZdl\$\do\PYGZdq\"% $, "
1023    \def\PYGZsq
1024     {\discretionary{}{\sphinxafterbreak\textquotesingle}{\textquotesingle}}% '
1025}
1026\newcommand*\sphinxbreaksafterlist {%
1027    \do\PYGZus\_\do\PYGZcb\}\do\PYGZca\^\do\PYGZam\&% _, }, ^, &,
1028    \do\PYGZgt\>\do\PYGZhy\-\do\PYGZti\~% >, -, ~
1029}
1030\newcommand*\sphinxbreaksatspecials {%
1031  \def\do##1##2%
1032     {\def##1{\discretionary{}{\sphinxafterbreak\char`##2}{\char`##2}}}%
1033  \sphinxbreaksbeforelist
1034  \def\do##1##2%
1035     {\def##1{\discretionary{\char`##2}{\sphinxafterbreak}{\char`##2}}}%
1036  \sphinxbreaksafterlist
1037}
1038
1039\def\sphinx@verbatim@nolig@list {\do \`}%
1040% Some characters . , ; ? ! / are not pygmentized.
1041% This macro makes them "active" and they will insert potential linebreaks.
1042% Not compatible with math mode (cf \sphinxunactivateextras).
1043\newcommand*\sphinxbreaksbeforeactivelist {}% none
1044\newcommand*\sphinxbreaksafteractivelist  {\do\.\do\,\do\;\do\?\do\!\do\/}
1045\newcommand*\sphinxbreaksviaactive {%
1046   \def\do##1{\lccode`\~`##1%
1047    \lowercase{\def~}{\discretionary{}{\sphinxafterbreak\char`##1}{\char`##1}}%
1048    \catcode`##1\active}%
1049   \sphinxbreaksbeforeactivelist
1050   \def\do##1{\lccode`\~`##1%
1051    \lowercase{\def~}{\discretionary{\char`##1}{\sphinxafterbreak}{\char`##1}}%
1052    \catcode`##1\active}%
1053   \sphinxbreaksafteractivelist
1054   \lccode`\~`\~
1055}
1056
1057% If the linebreak is at a space, the latter will be displayed as visible
1058% space at end of first line, and a continuation symbol starts next line.
1059\def\spx@verbatim@space {%
1060     \nobreak\hskip\z@skip
1061     \discretionary{\copy\sphinxvisiblespacebox}{\sphinxafterbreak}
1062                   {\kern\fontdimen2\font}%
1063}%
1064
1065% if the available space on page is less than \literalblockneedspace, insert pagebreak
1066\newcommand{\sphinxliteralblockneedspace}{5\baselineskip}
1067\newcommand{\sphinxliteralblockwithoutcaptionneedspace}{1.5\baselineskip}
1068% The title (caption) is specified from outside as macro \sphinxVerbatimTitle.
1069% \sphinxVerbatimTitle is reset to empty after each use of Verbatim.
1070\newcommand*\sphinxVerbatimTitle {}
1071% This box to typeset the caption before framed.sty multiple passes for framing.
1072\newbox\sphinxVerbatim@TitleBox
1073% This is a workaround to a "feature" of French lists, when literal block
1074% follows immediately; usable generally (does only \par then), a priori...
1075\newcommand*\sphinxvspacefixafterfrenchlists{%
1076   \ifvmode\ifdim\lastskip<\z@ \vskip\parskip\fi\else\par\fi
1077}
1078% Holder macro for labels of literal blocks. Set-up by LaTeX writer.
1079\newcommand*\sphinxLiteralBlockLabel {}
1080\newcommand*\sphinxSetupCaptionForVerbatim [1]
1081{%
1082    \sphinxvspacefixafterfrenchlists
1083    \needspace{\sphinxliteralblockneedspace}%
1084% insert a \label via \sphinxLiteralBlockLabel
1085% reset to normal the color for the literal block caption
1086    \def\sphinxVerbatimTitle
1087       {\py@NormalColor\sphinxcaption{\sphinxLiteralBlockLabel #1}}%
1088}
1089\newcommand*\sphinxSetupCodeBlockInFootnote {%
1090  \fvset{fontsize=\footnotesize}\let\caption\sphinxfigcaption
1091  \sphinxverbatimwithminipagetrue % reduces vertical spaces
1092  % we counteract (this is in a group) the \@normalsize from \caption
1093  \let\normalsize\footnotesize\let\@parboxrestore\relax
1094  \def\spx@abovecaptionskip{\sphinxverbatimsmallskipamount}%
1095}
1096% needed to create wrapper environments of fancyvrb's Verbatim
1097\newcommand*{\sphinxVerbatimEnvironment}{\gdef\FV@EnvironName{sphinxVerbatim}}
1098\newcommand*{\sphinxverbatimsmallskipamount}{\smallskipamount}
1099% serves to implement line highlighting and line wrapping
1100\newcommand\sphinxFancyVerbFormatLine[1]{%
1101  \expandafter\sphinx@verbatim@checkifhl\expandafter{\the\FV@CodeLineNo}%
1102  \ifin@
1103     \sphinxVerbatimHighlightLine{#1}%
1104  \else
1105     \sphinxVerbatimFormatLine{#1}%
1106  \fi
1107}%
1108\newcommand\sphinxVerbatimHighlightLine[1]{%
1109  \edef\sphinxrestorefboxsep{\fboxsep\the\fboxsep\relax}%
1110  \fboxsep0pt\relax % cf LaTeX bug graphics/4524
1111  \colorbox{sphinxVerbatimHighlightColor}%
1112           {\sphinxrestorefboxsep\sphinxVerbatimFormatLine{#1}}%
1113  % no need to restore \fboxsep here, as this ends up in a \hbox from fancyvrb
1114}%
1115% \sphinxVerbatimFormatLine will be set locally to one of those two:
1116\newcommand\sphinxVerbatimFormatLineWrap[1]{%
1117    \hsize\linewidth
1118    \vtop{\raggedright\hyphenpenalty\z@\exhyphenpenalty\z@
1119          \doublehyphendemerits\z@\finalhyphendemerits\z@
1120          \strut #1\strut}%
1121}%
1122\newcommand\sphinxVerbatimFormatLineNoWrap[1]{\hb@xt@\linewidth{\strut #1\hss}}%
1123\g@addto@macro\FV@SetupFont{%
1124    \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
1125    \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
1126}%
1127\newenvironment{sphinxVerbatim}{%
1128  % first, let's check if there is a caption
1129  \ifx\sphinxVerbatimTitle\empty
1130      \sphinxvspacefixafterfrenchlists
1131      \parskip\z@skip
1132      \vskip\sphinxverbatimsmallskipamount
1133      % there was no caption. Check if nevertheless a label was set.
1134      \ifx\sphinxLiteralBlockLabel\empty\else
1135      % we require some space to be sure hyperlink target from \phantomsection
1136      % will not be separated from upcoming verbatim by a page break
1137          \needspace{\sphinxliteralblockwithoutcaptionneedspace}%
1138          \phantomsection\sphinxLiteralBlockLabel
1139      \fi
1140  \else
1141     \parskip\z@skip
1142     \if t\spx@opt@literalblockcappos
1143       \vskip\spx@abovecaptionskip
1144       \def\sphinxVerbatim@Before
1145           {\sphinxVerbatim@Title\nointerlineskip
1146            \kern\dimexpr-\dp\strutbox+\sphinxbelowcaptionspace
1147                 % if no frame (code-blocks inside table cells), remove
1148                 % the "verbatimsep" whitespace from the top (better visually)
1149                 \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi
1150                 % caption package adds \abovecaptionskip vspace, remove it
1151                 \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax}%
1152     \else
1153       \vskip\sphinxverbatimsmallskipamount
1154       \def\sphinxVerbatim@After
1155          {\nointerlineskip\kern\dimexpr\dp\strutbox
1156            \ifspx@opt@verbatimwithframe\else-\sphinxverbatimsep\fi
1157            \spx@ifcaptionpackage{-\abovecaptionskip}{}\relax
1158           \sphinxVerbatim@Title}%
1159     \fi
1160     \def\@captype{literalblock}%
1161     \capstart
1162     % \sphinxVerbatimTitle must reset color
1163     \setbox\sphinxVerbatim@TitleBox
1164            \hbox{\begin{minipage}{\linewidth}%
1165     % caption package may detect wrongly if top or bottom, so we help it
1166                    \spx@ifcaptionpackage
1167                      {\caption@setposition{\spx@opt@literalblockcappos}}{}%
1168                    \sphinxVerbatimTitle
1169                  \end{minipage}}%
1170  \fi
1171  \global\let\sphinxLiteralBlockLabel\empty
1172  \global\let\sphinxVerbatimTitle\empty
1173  \fboxsep\sphinxverbatimsep \fboxrule\sphinxverbatimborder
1174  \ifspx@opt@verbatimwithframe\else\fboxrule\z@\fi
1175  \let\FrameCommand     \sphinxVerbatim@FrameCommand
1176  \let\FirstFrameCommand\sphinxVerbatim@FirstFrameCommand
1177  \let\MidFrameCommand  \sphinxVerbatim@MidFrameCommand
1178  \let\LastFrameCommand \sphinxVerbatim@LastFrameCommand
1179  \ifspx@opt@verbatimhintsturnover\else
1180      \let\sphinxVerbatim@Continued\@empty
1181      \let\sphinxVerbatim@Continues\@empty
1182  \fi
1183  \ifspx@opt@verbatimwrapslines
1184  % fancyvrb's Verbatim puts each input line in (unbreakable) horizontal boxes.
1185  % This customization wraps each line from the input in a \vtop, thus
1186  % allowing it to wrap and display on two or more lines in the latex output.
1187  %     - The codeline counter will be increased only once.
1188  %     - The wrapped material will not break across pages, it is impossible
1189  %       to achieve this without extensive rewrite of fancyvrb.
1190  %     - The (not used in sphinx) obeytabs option to Verbatim is
1191  %       broken by this change (showtabs and tabspace work).
1192    \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineWrap
1193    \let\FV@Space\spx@verbatim@space
1194  % Allow breaks at special characters using \PYG... macros.
1195    \sphinxbreaksatspecials
1196  % Breaks at punctuation characters . , ; ? ! and / (needs catcode activation)
1197    \fvset{codes*=\sphinxbreaksviaactive}%
1198  \else % end of conditional code for wrapping long code lines
1199    \let\sphinxVerbatimFormatLine\sphinxVerbatimFormatLineNoWrap
1200  \fi
1201  \let\FancyVerbFormatLine\sphinxFancyVerbFormatLine
1202  % workaround to fancyvrb's check of \@currenvir
1203  \let\VerbatimEnvironment\sphinxVerbatimEnvironment
1204  % workaround to fancyvrb's check of current list depth
1205  \def\@toodeep {\advance\@listdepth\@ne}%
1206  % The list environment is needed to control perfectly the vertical space.
1207  % Note: \OuterFrameSep used by framed.sty is later set to \topsep hence 0pt.
1208  % - if caption: distance from last text baseline to caption baseline is
1209  %   A+(B-F)+\ht\strutbox, A = \abovecaptionskip (default 10pt), B =
1210  %   \baselineskip, F is the framed.sty \FrameHeightAdjust macro, default 6pt.
1211  %   Formula valid for F < 10pt.
1212  % - distance of baseline of caption to top of frame is like for tables:
1213  %   \sphinxbelowcaptionspace (=0.5\baselineskip)
1214  % - if no caption: distance of last text baseline to code frame is S+(B-F),
1215  %   with S = \sphinxverbatimtopskip (=\smallskip)
1216  % - and distance from bottom of frame to next text baseline is
1217  %   \baselineskip+\parskip.
1218  % The \trivlist is used to avoid possible "too deeply nested" error.
1219  \itemsep   \z@skip
1220  \topsep    \z@skip
1221  \partopsep \z@skip
1222  % trivlist will set \parsep to \parskip = zero
1223  % \leftmargin will be set to zero by trivlist
1224  \rightmargin\z@
1225  \parindent  \z@% becomes \itemindent. Default zero, but perhaps overwritten.
1226  \trivlist\item\relax
1227     \ifsphinxverbatimwithminipage\spx@inframedtrue\fi
1228     % use a minipage if we are already inside a framed environment
1229     \ifspx@inframed\noindent\begin{minipage}{\linewidth}\fi
1230     \MakeFramed {% adapted over from framed.sty's snugshade environment
1231        \advance\hsize-\width\@totalleftmargin\z@\linewidth\hsize\@setminipage
1232        }%
1233     % For grid placement from \strut's in \FancyVerbFormatLine
1234     \lineskip\z@skip
1235     % active comma should not be overwritten by \@noligs
1236     \ifspx@opt@verbatimwrapslines
1237       \let\verbatim@nolig@list \sphinx@verbatim@nolig@list
1238     \fi
1239     % will fetch its optional arguments if any
1240     \OriginalVerbatim
1241}
1242{%
1243  \endOriginalVerbatim
1244  \par\unskip\@minipagefalse\endMakeFramed % from framed.sty snugshade
1245  \ifspx@inframed\end{minipage}\fi
1246  \endtrivlist
1247}
1248\newenvironment {sphinxVerbatimNoFrame}
1249  {\spx@opt@verbatimwithframefalse
1250   % needed for fancyvrb as literal code will end in \end{sphinxVerbatimNoFrame}
1251   \def\sphinxVerbatimEnvironment{\gdef\FV@EnvironName{sphinxVerbatimNoFrame}}%
1252   \begin{sphinxVerbatim}}
1253  {\end{sphinxVerbatim}}
1254\newenvironment {sphinxVerbatimintable}
1255  {% don't use a frame if in a table cell
1256   \spx@opt@verbatimwithframefalse
1257   \sphinxverbatimwithminipagetrue
1258   % the literal block caption uses \sphinxcaption which is wrapper of \caption,
1259   % but \caption must be modified because longtable redefines it to work only
1260   % for the own table caption, and tabulary has multiple passes
1261   \let\caption\sphinxfigcaption
1262   % reduce above caption skip
1263   \def\spx@abovecaptionskip{\sphinxverbatimsmallskipamount}%
1264   \def\sphinxVerbatimEnvironment{\gdef\FV@EnvironName{sphinxVerbatimintable}}%
1265   \begin{sphinxVerbatim}}
1266  {\end{sphinxVerbatim}}
1267
1268
1269%% PARSED LITERALS
1270% allow long lines to wrap like they do in code-blocks
1271
1272% this should be kept in sync with definitions in sphinx.util.texescape
1273\newcommand*\sphinxbreaksattexescapedchars{%
1274  \def\do##1##2% put potential break point before character
1275     {\def##1{\discretionary{}{\sphinxafterbreak\char`##2}{\char`##2}}}%
1276  \do\{\{\do\textless\<\do\#\#\do\%\%\do\$\$% {, <, #, %, $
1277  \def\do##1##2% put potential break point after character
1278     {\def##1{\discretionary{\char`##2}{\sphinxafterbreak}{\char`##2}}}%
1279  \do\_\_\do\}\}\do\textasciicircum\^\do\&\&% _, }, ^, &,
1280  \do\textgreater\>\do\textasciitilde\~% >, ~
1281}
1282\newcommand*\sphinxbreaksviaactiveinparsedliteral{%
1283  \sphinxbreaksviaactive % by default handles . , ; ? ! /
1284  \do\-% we need also the hyphen character (ends up "as is" in parsed-literal)
1285  \lccode`\~`\~ %
1286  % update \dospecials as it is used by \url
1287  % but deactivation will already have been done hence this is unneeded:
1288  %  \expandafter\def\expandafter\dospecials\expandafter{\dospecials
1289  %   \sphinxbreaksbeforeactivelist\sphinxbreaksafteractivelist\do\-}%
1290}
1291\newcommand*\sphinxbreaksatspaceinparsedliteral{%
1292  \lccode`~32 \lowercase{\let~}\spx@verbatim@space\lccode`\~`\~
1293}
1294\newcommand*{\sphinxunactivateextras}{\let\do\@makeother
1295      \sphinxbreaksbeforeactivelist\sphinxbreaksafteractivelist\do\-}%
1296% the \catcode13=5\relax (deactivate end of input lines) is left to callers
1297\newcommand*{\sphinxunactivateextrasandspace}{\catcode32=10\relax
1298      \sphinxunactivateextras}%
1299% now for the modified alltt environment
1300\newenvironment{sphinxalltt}
1301{% at start of next line to workaround Emacs/AUCTeX issue with this file
1302\begin{alltt}%
1303 \ifspx@opt@parsedliteralwraps
1304   \sbox\sphinxcontinuationbox {\spx@opt@verbatimcontinued}%
1305   \sbox\sphinxvisiblespacebox {\spx@opt@verbatimvisiblespace}%
1306   \sphinxbreaksattexescapedchars
1307   \sphinxbreaksviaactiveinparsedliteral
1308   \sphinxbreaksatspaceinparsedliteral
1309% alltt takes care of the ' as derivative ("prime") in math mode
1310   \everymath\expandafter{\the\everymath\sphinxunactivateextrasandspace
1311             \catcode`\<=12\catcode`\>=12\catcode`\^=7\catcode`\_=8 }%
1312% not sure if displayed math (align,...) can end up in parsed-literal, anyway
1313   \everydisplay\expandafter{\the\everydisplay
1314             \catcode13=5 \sphinxunactivateextrasandspace
1315             \catcode`\<=12\catcode`\>=12\catcode`\^=7\catcode`\_=8 }%
1316 \fi }
1317{\end{alltt}}
1318
1319% Protect \href's first argument in contexts such as sphinxalltt (or
1320% \sphinxcode). Sphinx uses \#, \%, \& ... always inside \sphinxhref.
1321\protected\def\sphinxhref#1#2{{%
1322    \sphinxunactivateextrasandspace % never do \scantokens with active space!
1323    \endlinechar\m@ne\everyeof{{#2}}% keep catcode regime for #2
1324    \scantokens{\href{#1}}% normalise it for #1 during \href expansion
1325}}
1326% Same for \url. And also \nolinkurl for coherence.
1327\protected\def\sphinxurl#1{{%
1328    \sphinxunactivateextrasandspace\everyeof{}% (<- precaution for \scantokens)
1329    \endlinechar\m@ne\scantokens{\url{#1}}%
1330}}
1331\protected\def\sphinxnolinkurl#1{{%
1332    \sphinxunactivateextrasandspace\everyeof{}%
1333    \endlinechar\m@ne\scantokens{\nolinkurl{#1}}%
1334}}
1335
1336
1337%% TOPIC AND CONTENTS BOXES
1338%
1339% Again based on use of "framed.sty", this allows breakable framed boxes.
1340\long\def\spx@ShadowFBox#1{%
1341  \leavevmode\begingroup
1342  % first we frame the box #1
1343  \setbox\@tempboxa
1344   \hbox{\vrule\@width\sphinxshadowrule
1345         \vbox{\hrule\@height\sphinxshadowrule
1346               \kern\sphinxshadowsep
1347               \hbox{\kern\sphinxshadowsep #1\kern\sphinxshadowsep}%
1348               \kern\sphinxshadowsep
1349               \hrule\@height\sphinxshadowrule}%
1350         \vrule\@width\sphinxshadowrule}%
1351  % Now we add the shadow, like \shadowbox from fancybox.sty would do
1352  \dimen@\dimexpr.5\sphinxshadowrule+\sphinxshadowsize\relax
1353  \hbox{\vbox{\offinterlineskip
1354              \hbox{\copy\@tempboxa\kern-.5\sphinxshadowrule
1355                    % add shadow on right side
1356                    \lower\sphinxshadowsize
1357                          \hbox{\vrule\@height\ht\@tempboxa \@width\dimen@}%
1358                    }%
1359              \kern-\dimen@ % shift back vertically to bottom of frame
1360              % and add shadow at bottom
1361              \moveright\sphinxshadowsize
1362                    \vbox{\hrule\@width\wd\@tempboxa \@height\dimen@}%
1363              }%
1364        % move left by the size of right shadow so shadow adds no width
1365        \kern-\sphinxshadowsize
1366       }%
1367  \endgroup
1368}
1369
1370% use framed.sty to allow page breaks in frame+shadow
1371% works well inside Lists and Quote-like environments
1372% produced by ``topic'' directive (or local contents)
1373% could nest if LaTeX writer authorized it
1374\newenvironment{sphinxShadowBox}
1375  {\def\FrameCommand {\spx@ShadowFBox }%
1376   \advance\spx@image@maxheight
1377   -\dimexpr2\sphinxshadowrule
1378           +2\sphinxshadowsep
1379           +\sphinxshadowsize
1380           +\baselineskip\relax
1381   \let\sphinxincludegraphics\sphinxsafeincludegraphics
1382   % configure framed.sty not to add extra vertical spacing
1383   \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}%
1384   % the \trivlist will add the vertical spacing on top and bottom which is
1385   % typical of center environment as used in Sphinx <= 1.4.1
1386   % the \noindent has the effet of an extra blank line on top, to
1387   % imitate closely the layout from Sphinx <= 1.4.1; the \FrameHeightAdjust
1388   % will put top part of frame on this baseline.
1389   \def\FrameHeightAdjust {\baselineskip}%
1390   % use package footnote to handle footnotes
1391   \savenotes
1392   \trivlist\item\noindent
1393    % use a minipage if we are already inside a framed environment
1394    \ifspx@inframed\begin{minipage}{\linewidth}\fi
1395    \MakeFramed {\spx@inframedtrue
1396    % framed.sty puts into "\width" the added width (=2shadowsep+2shadowrule)
1397    % adjust \hsize to what the contents must use
1398    \advance\hsize-\width
1399    % adjust LaTeX parameters to behave properly in indented/quoted contexts
1400    \FrameRestore
1401    % typeset the contents as in a minipage (Sphinx <= 1.4.1 used a minipage and
1402    % itemize/enumerate are therein typeset more tightly, we want to keep
1403    % that). We copy-paste from LaTeX source code but don't do a real minipage.
1404    \@pboxswfalse
1405    \let\@listdepth\@mplistdepth \@mplistdepth\z@
1406    \@minipagerestore
1407    \@setminipage
1408    }%
1409  }%
1410  {% insert the "endminipage" code
1411    \par\unskip
1412    \@minipagefalse
1413   \endMakeFramed
1414     \ifspx@inframed\end{minipage}\fi
1415   \endtrivlist
1416   % output the stored footnotes
1417   \spewnotes
1418  }
1419
1420
1421%% NOTICES AND ADMONITIONS
1422%
1423% Some are quite plain
1424% the spx@notice@bordercolor etc are set in the sphinxadmonition environment
1425\newenvironment{sphinxlightbox}{%
1426  \par\allowbreak
1427  \noindent{\color{spx@notice@bordercolor}%
1428            \rule{\linewidth}{\spx@notice@border}}\par\nobreak
1429  {\parskip\z@skip\noindent}%
1430  }
1431  {%
1432  % counteract previous possible negative skip (French lists!):
1433  % (we can't cancel that any earlier \vskip introduced a potential pagebreak)
1434  \sphinxvspacefixafterfrenchlists
1435  \nobreak\vbox{\noindent\kern\@totalleftmargin
1436      {\color{spx@notice@bordercolor}%
1437       \rule[\dimexpr.4\baselineskip-\spx@notice@border\relax]
1438             {\linewidth}{\spx@notice@border}}\hss}\allowbreak
1439  }% end of sphinxlightbox environment definition
1440% may be renewenvironment'd by user for complete customization
1441\newenvironment{sphinxnote}[1]
1442  {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
1443\newenvironment{sphinxhint}[1]
1444  {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
1445\newenvironment{sphinximportant}[1]
1446  {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
1447\newenvironment{sphinxtip}[1]
1448  {\begin{sphinxlightbox}\sphinxstrong{#1} }{\end{sphinxlightbox}}
1449% or just use the package options
1450% these are needed for common handling by notice environment of lightbox
1451% and heavybox but they are  currently not used by lightbox environment
1452% and there is consequently no corresponding package option
1453\definecolor{sphinxnoteBgColor}{rgb}{1,1,1}
1454\definecolor{sphinxhintBgColor}{rgb}{1,1,1}
1455\definecolor{sphinximportantBgColor}{rgb}{1,1,1}
1456\definecolor{sphinxtipBgColor}{rgb}{1,1,1}
1457
1458% Others get more distinction
1459% Code adapted from framed.sty's "snugshade" environment.
1460% Nesting works (inner frames do not allow page breaks).
1461\newenvironment{sphinxheavybox}{\par
1462   \setlength{\FrameRule}{\spx@notice@border}%
1463   \setlength{\FrameSep}{\dimexpr.6\baselineskip-\FrameRule\relax}
1464   \advance\spx@image@maxheight
1465   -\dimexpr2\FrameRule
1466           +2\FrameSep
1467           +\baselineskip\relax % will happen again if nested, needed indeed!
1468   \let\sphinxincludegraphics\sphinxsafeincludegraphics
1469   % configure framed.sty's parameters to obtain same vertical spacing
1470   % as for "light" boxes. We need for this to manually insert parskip glue and
1471   % revert a skip done by framed before the frame.
1472    \ltx@ifundefined{OuterFrameSep}{}{\OuterFrameSep\z@skip}%
1473    \vspace{\FrameHeightAdjust}
1474   % copied/adapted from framed.sty's snugshade
1475   \def\FrameCommand##1{\hskip\@totalleftmargin
1476       \fboxsep\FrameSep \fboxrule\FrameRule
1477       \fcolorbox{spx@notice@bordercolor}{spx@notice@bgcolor}{##1}%
1478       \hskip-\linewidth \hskip-\@totalleftmargin \hskip\columnwidth}%
1479   \savenotes
1480   % use a minipage if we are already inside a framed environment
1481   \ifspx@inframed
1482       \noindent\begin{minipage}{\linewidth}
1483   \else
1484       % handle case where notice is first thing in a list item (or is quoted)
1485       \if@inlabel
1486        \noindent\par\vspace{-\baselineskip}
1487       \else
1488        \vspace{\parskip}
1489       \fi
1490   \fi
1491   \MakeFramed {\spx@inframedtrue
1492     \advance\hsize-\width \@totalleftmargin\z@ \linewidth\hsize
1493     % minipage initialization copied from LaTeX source code.
1494     \@pboxswfalse
1495     \let\@listdepth\@mplistdepth \@mplistdepth\z@
1496     \@minipagerestore
1497     \@setminipage }%
1498   }
1499   {%
1500   \par\unskip
1501   \@minipagefalse
1502   \endMakeFramed
1503   \ifspx@inframed\end{minipage}\fi
1504   % set footnotes at bottom of page
1505   \spewnotes
1506   % arrange for similar spacing below frame as for "light" boxes.
1507   \vskip .4\baselineskip
1508   }% end of sphinxheavybox environment definition
1509% may be renewenvironment'd by user for complete customization
1510\newenvironment{sphinxwarning}[1]
1511  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
1512\newenvironment{sphinxcaution}[1]
1513  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
1514\newenvironment{sphinxattention}[1]
1515  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
1516\newenvironment{sphinxdanger}[1]
1517  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
1518\newenvironment{sphinxerror}[1]
1519  {\begin{sphinxheavybox}\sphinxstrong{#1} }{\end{sphinxheavybox}}
1520% or just use package options
1521
1522% the \colorlet of xcolor (if at all loaded) is overkill for our use case
1523\newcommand{\sphinxcolorlet}[2]
1524    {\expandafter\let\csname\@backslashchar color@#1\expandafter\endcsname
1525                     \csname\@backslashchar color@#2\endcsname }
1526
1527% the main dispatch for all types of notices
1528\newenvironment{sphinxadmonition}[2]{% #1=type, #2=heading
1529  % can't use #1 directly in definition of end part
1530  \def\spx@noticetype {#1}%
1531  % set parameters of heavybox/lightbox
1532  \sphinxcolorlet{spx@notice@bordercolor}{sphinx#1BorderColor}%
1533  \sphinxcolorlet{spx@notice@bgcolor}{sphinx#1BgColor}%
1534  \spx@notice@border \dimexpr\csname spx@opt@#1border\endcsname\relax
1535  % start specific environment, passing the heading as argument
1536  \begin{sphinx#1}{#2}}
1537  % workaround some LaTeX "feature" of \end command
1538 {\edef\spx@temp{\noexpand\end{sphinx\spx@noticetype}}\spx@temp}
1539
1540
1541%% PYTHON DOCS MACROS AND ENVIRONMENTS
1542%  (some macros here used by \maketitle in sphinxmanual.cls and sphinxhowto.cls)
1543
1544% \moduleauthor{name}{email}
1545\newcommand{\moduleauthor}[2]{}
1546
1547% \sectionauthor{name}{email}
1548\newcommand{\sectionauthor}[2]{}
1549
1550% Allow the release number to be specified independently of the
1551% \date{}.  This allows the date to reflect the document's date and
1552% release to specify the release that is documented.
1553%
1554\newcommand{\py@release}{\releasename\space\version}
1555\newcommand{\version}{}% part of \py@release, used by title page and headers
1556% \releaseinfo is used on titlepage (sphinxmanual.cls, sphinxhowto.cls)
1557\newcommand{\releaseinfo}{}
1558\newcommand{\setreleaseinfo}[1]{\renewcommand{\releaseinfo}{#1}}
1559% this is inserted via template and #1=release config variable
1560\newcommand{\release}[1]{\renewcommand{\version}{#1}}
1561% this is defined by template to 'releasename' latex_elements key
1562\newcommand{\releasename}{}
1563% Fix issue in case release and releasename deliberately left blank
1564\newcommand{\sphinxheadercomma}{, }% used in fancyhdr header definition
1565\newcommand{\sphinxifemptyorblank}[1]{%
1566% test after one expansion of macro #1 if contents is empty or spaces
1567     \if&\expandafter\@firstofone\detokenize\expandafter{#1}&%
1568     \expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi}%
1569\AtBeginDocument {%
1570   \sphinxifemptyorblank{\releasename}
1571     {\sphinxifemptyorblank{\version}{\let\sphinxheadercomma\empty}{}}
1572     {}%
1573}%
1574
1575% Allow specification of the author's address separately from the
1576% author's name.  This can be used to format them differently, which
1577% is a good thing.
1578%
1579\newcommand{\py@authoraddress}{}
1580\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
1581
1582% {fulllineitems} is the main environment for object descriptions.
1583%
1584\newcommand{\py@itemnewline}[1]{%
1585  \kern\labelsep
1586  \@tempdima\linewidth
1587  \advance\@tempdima \labelwidth\makebox[\@tempdima][l]{#1}%
1588  \kern-\labelsep
1589}
1590
1591\newenvironment{fulllineitems}{%
1592  \begin{list}{}{\labelwidth \leftmargin
1593                 \rightmargin \z@ \topsep -\parskip \partopsep \parskip
1594                 \itemsep -\parsep
1595                 \let\makelabel=\py@itemnewline}%
1596}{\end{list}}
1597
1598% Signatures, possibly multi-line
1599%
1600\newlength{\py@argswidth}
1601\newcommand{\py@sigparams}[2]{%
1602  \parbox[t]{\py@argswidth}{#1\sphinxcode{)}#2}}
1603\newcommand{\pysigline}[1]{\item[{#1}]}
1604\newcommand{\pysiglinewithargsret}[3]{%
1605  \settowidth{\py@argswidth}{#1\sphinxcode{(}}%
1606  \addtolength{\py@argswidth}{-2\py@argswidth}%
1607  \addtolength{\py@argswidth}{\linewidth}%
1608  \item[{#1\sphinxcode{(}\py@sigparams{#2}{#3}}]}
1609\newcommand{\pysigstartmultiline}{%
1610 \def\pysigstartmultiline{\vskip\smallskipamount\parskip\z@skip\itemsep\z@skip}%
1611 \edef\pysigstopmultiline
1612     {\noexpand\leavevmode\parskip\the\parskip\relax\itemsep\the\itemsep\relax}%
1613 \parskip\z@skip\itemsep\z@skip
1614}
1615
1616% Production lists
1617%
1618\newenvironment{productionlist}{%
1619%  \def\sphinxoptional##1{{\Large[}##1{\Large]}}
1620  \def\production##1##2{\\\sphinxcode{\sphinxupquote{##1}}&::=&\sphinxcode{\sphinxupquote{##2}}}%
1621  \def\productioncont##1{\\& &\sphinxcode{\sphinxupquote{##1}}}%
1622  \parindent=2em
1623  \indent
1624  \setlength{\LTpre}{0pt}%
1625  \setlength{\LTpost}{0pt}%
1626  \begin{longtable}[l]{lcl}
1627}{%
1628  \end{longtable}
1629}
1630
1631% Definition lists; requested by AMK for HOWTO documents.  Probably useful
1632% elsewhere as well, so keep in in the general style support.
1633%
1634\newenvironment{definitions}{%
1635  \begin{description}%
1636  \def\term##1{\item[{##1}]\mbox{}\\*[0mm]}%
1637}{%
1638  \end{description}%
1639}
1640
1641%% FROM DOCTUTILS LATEX WRITER
1642%
1643% The following is stuff copied from docutils' latex writer.
1644%
1645\newcommand{\optionlistlabel}[1]{\normalfont\bfseries #1 \hfill}% \bf deprecated
1646\newenvironment{optionlist}[1]
1647{\begin{list}{}
1648  {\setlength{\labelwidth}{#1}
1649   \setlength{\rightmargin}{1cm}
1650   \setlength{\leftmargin}{\rightmargin}
1651   \addtolength{\leftmargin}{\labelwidth}
1652   \addtolength{\leftmargin}{\labelsep}
1653   \renewcommand{\makelabel}{\optionlistlabel}}
1654}{\end{list}}
1655
1656\newlength{\lineblockindentation}
1657\setlength{\lineblockindentation}{2.5em}
1658\newenvironment{lineblock}[1]
1659{\begin{list}{}
1660  {\setlength{\partopsep}{\parskip}
1661   \addtolength{\partopsep}{\baselineskip}
1662   \topsep0pt\itemsep0.15\baselineskip\parsep0pt
1663   \leftmargin#1\relax}
1664 \raggedright}
1665{\end{list}}
1666
1667% From docutils.writers.latex2e
1668% inline markup (custom roles)
1669% \DUrole{#1}{#2} tries \DUrole#1{#2}
1670\providecommand*{\DUrole}[2]{%
1671  \ifcsname DUrole\detokenize{#1}\endcsname
1672    \csname DUrole\detokenize{#1}\endcsname{#2}%
1673  \else% backwards compatibility: try \docutilsrole#1{#2}
1674    \ifcsname docutilsrole\detokenize{#1}\endcsname
1675      \csname docutilsrole\detokenize{#1}\endcsname{#2}%
1676    \else
1677      #2%
1678    \fi
1679  \fi
1680}
1681
1682\providecommand*{\DUprovidelength}[2]{%
1683  \ifdefined#1\else\newlength{#1}\setlength{#1}{#2}\fi
1684}
1685
1686\DUprovidelength{\DUlineblockindent}{2.5em}
1687\ifdefined\DUlineblock\else
1688  \newenvironment{DUlineblock}[1]{%
1689    \list{}{\setlength{\partopsep}{\parskip}
1690            \addtolength{\partopsep}{\baselineskip}
1691            \setlength{\topsep}{0pt}
1692            \setlength{\itemsep}{0.15\baselineskip}
1693            \setlength{\parsep}{0pt}
1694            \setlength{\leftmargin}{#1}}
1695    \raggedright
1696  }
1697  {\endlist}
1698\fi
1699
1700%% TEXT STYLING
1701%
1702% to obtain straight quotes we execute \@noligs as patched by upquote, and
1703% \scantokens is needed in cases where it would be too late for the macro to
1704% first set catcodes and then fetch its argument. We also make the contents
1705% breakable at non-escaped . , ; ? ! / using \sphinxbreaksviaactive.
1706% the macro must be protected if it ends up used in moving arguments,
1707% in 'alltt' \@noligs is done already, and the \scantokens must be avoided.
1708\protected\def\sphinxupquote#1{{\def\@tempa{alltt}%
1709  \ifx\@tempa\@currenvir\else
1710   \ifspx@opt@inlineliteralwraps
1711      \sphinxbreaksviaactive\let\sphinxafterbreak\empty
1712      % do not overwrite the comma set-up
1713      \let\verbatim@nolig@list\sphinx@literal@nolig@list
1714   \fi
1715   % fix a space-gobbling issue due to LaTeX's original \do@noligs
1716   \let\do@noligs\sphinx@do@noligs
1717   \@noligs\endlinechar\m@ne\everyeof{}% (<- in case inside \sphinxhref)
1718   \expandafter\scantokens
1719  \fi {{#1}}}}% extra brace pair to fix end-space gobbling issue...
1720\def\sphinx@do@noligs #1{\catcode`#1\active\begingroup\lccode`\~`#1\relax
1721    \lowercase{\endgroup\def~{\leavevmode\kern\z@\char`#1 }}}
1722\def\sphinx@literal@nolig@list {\do\`\do\<\do\>\do\'\do\-}%
1723
1724% Some custom font markup commands.
1725\protected\def\sphinxstrong#1{\textbf{#1}}
1726\protected\def\sphinxcode#1{\texttt{#1}}
1727\protected\def\sphinxbfcode#1{\textbf{\sphinxcode{#1}}}
1728\protected\def\sphinxemail#1{\textsf{#1}}
1729\protected\def\sphinxtablecontinued#1{\textsf{#1}}
1730\protected\def\sphinxtitleref#1{\emph{#1}}
1731\protected\def\sphinxmenuselection#1{\emph{#1}}
1732\protected\def\sphinxguilabel#1{\emph{#1}}
1733\protected\def\sphinxaccelerator#1{\underline{#1}}
1734\protected\def\sphinxcrossref#1{\emph{#1}}
1735\protected\def\sphinxtermref#1{\emph{#1}}
1736% \optional is used for ``[, arg]``, i.e. desc_optional nodes.
1737\long\protected\def\sphinxoptional#1{%
1738  {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
1739
1740% additional customizable styling
1741\def\sphinxstyleindexentry   #1{\texttt{#1}}
1742\def\sphinxstyleindexextra   #1{ (\emph{#1})}
1743\def\sphinxstyleindexpageref #1{, \pageref{#1}}
1744\def\sphinxstyleindexpagemain#1{\textbf{#1}}
1745\protected\def\spxentry#1{#1}% will get \let to \sphinxstyleindexentry in index
1746\protected\def\spxextra#1{#1}% will get \let to \sphinxstyleindexextra in index
1747\def\sphinxstyleindexlettergroup #1%
1748    {{\Large\sffamily#1}\nopagebreak\vspace{1mm}}
1749\def\sphinxstyleindexlettergroupDefault #1%
1750    {{\Large\sffamily\sphinxnonalphabeticalgroupname}\nopagebreak\vspace{1mm}}
1751\protected\def\sphinxstyletopictitle   #1{\textbf{#1}\par\medskip}
1752\let\sphinxstylesidebartitle\sphinxstyletopictitle
1753\protected\def\sphinxstyleothertitle   #1{\textbf{#1}}
1754\protected\def\sphinxstylesidebarsubtitle #1{~\\\textbf{#1} \smallskip}
1755% \text.. commands do not allow multiple paragraphs
1756\protected\def\sphinxstyletheadfamily    {\sffamily}
1757\protected\def\sphinxstyleemphasis     #1{\emph{#1}}
1758\protected\def\sphinxstyleliteralemphasis#1{\emph{\sphinxcode{#1}}}
1759\protected\def\sphinxstylestrong       #1{\textbf{#1}}
1760\protected\def\sphinxstyleliteralstrong#1{\sphinxbfcode{#1}}
1761\protected\def\sphinxstyleabbreviation #1{\textsc{#1}}
1762\protected\def\sphinxstyleliteralintitle#1{\sphinxcode{#1}}
1763\newcommand*\sphinxstylecodecontinued[1]{\footnotesize(#1)}%
1764\newcommand*\sphinxstylecodecontinues[1]{\footnotesize(#1)}%
1765% figure legend comes after caption and may contain arbitrary body elements
1766\newenvironment{sphinxlegend}{\par\small}{\par}
1767% reduce hyperref "Token not allowed in a PDF string" warnings on PDF builds
1768\AtBeginDocument{\pdfstringdefDisableCommands{%
1769% all "protected" macros possibly ending up in section titles should be here
1770    \let\sphinxstyleemphasis        \@firstofone
1771    \let\sphinxstyleliteralemphasis \@firstofone
1772    \let\sphinxstylestrong          \@firstofone
1773    \let\sphinxstyleliteralstrong   \@firstofone
1774    \let\sphinxstyleabbreviation    \@firstofone
1775    \let\sphinxstyleliteralintitle  \@firstofone
1776    \let\sphinxupquote  \@firstofone
1777    \let\sphinxstrong   \@firstofone
1778    \let\sphinxcode     \@firstofone
1779    \let\sphinxbfcode   \@firstofone
1780    \let\sphinxemail    \@firstofone
1781    \let\sphinxcrossref \@firstofone
1782    \let\sphinxtermref  \@firstofone
1783}}
1784
1785% For curly braces inside \index macro
1786\def\sphinxleftcurlybrace{\{}
1787\def\sphinxrightcurlybrace{\}}
1788
1789% Declare Unicode characters used by linux tree command to pdflatex utf8/utf8x
1790\def\spx@bd#1#2{%
1791  \leavevmode
1792  \begingroup
1793  \ifx\spx@bd@height   \@undefined\def\spx@bd@height{\baselineskip}\fi
1794  \ifx\spx@bd@width    \@undefined\setbox0\hbox{0}\def\spx@bd@width{\wd0 }\fi
1795  \ifx\spx@bd@thickness\@undefined\def\spx@bd@thickness{.6\p@}\fi
1796  \ifx\spx@bd@lower    \@undefined\def\spx@bd@lower{\dp\strutbox}\fi
1797  \lower\spx@bd@lower#1{#2}%
1798  \endgroup
1799}%
1800\@namedef{sphinx@u2500}% BOX DRAWINGS LIGHT HORIZONTAL
1801  {\spx@bd{\vbox to\spx@bd@height}
1802          {\vss\hrule\@height\spx@bd@thickness
1803                     \@width\spx@bd@width\vss}}%
1804\@namedef{sphinx@u2502}% BOX DRAWINGS LIGHT VERTICAL
1805  {\spx@bd{\hb@xt@\spx@bd@width}
1806          {\hss\vrule\@height\spx@bd@height
1807                     \@width \spx@bd@thickness\hss}}%
1808\@namedef{sphinx@u2514}% BOX DRAWINGS LIGHT UP AND RIGHT
1809  {\spx@bd{\hb@xt@\spx@bd@width}
1810          {\hss\raise.5\spx@bd@height
1811           \hb@xt@\z@{\hss\vrule\@height.5\spx@bd@height
1812                                \@width \spx@bd@thickness\hss}%
1813           \vbox to\spx@bd@height{\vss\hrule\@height\spx@bd@thickness
1814                                            \@width.5\spx@bd@width\vss}}}%
1815\@namedef{sphinx@u251C}% BOX DRAWINGS LIGHT VERTICAL AND RIGHT
1816  {\spx@bd{\hb@xt@\spx@bd@width}
1817          {\hss
1818           \hb@xt@\z@{\hss\vrule\@height\spx@bd@height
1819                                \@width \spx@bd@thickness\hss}%
1820           \vbox to\spx@bd@height{\vss\hrule\@height\spx@bd@thickness
1821                                            \@width.5\spx@bd@width\vss}}}%
1822\protected\def\sphinxunichar#1{\@nameuse{sphinx@u#1}}%
1823
1824% Tell TeX about pathological hyphenation cases:
1825\hyphenation{Base-HTTP-Re-quest-Hand-ler}
1826\endinput
Note: See TracBrowser for help on using the repository browser.
hosted by ZAMG