| |
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}[2010/01/15 LaTeX package (Sphinx markup)] |
| |
10 |
| |
11 \RequirePackage{textcomp} |
| |
12 \RequirePackage{fancyhdr} |
| |
13 \RequirePackage{fancybox} |
| |
14 \RequirePackage{titlesec} |
| |
15 \RequirePackage{tabulary} |
| |
16 \RequirePackage{amsmath} % for \text |
| |
17 \RequirePackage{makeidx} |
| |
18 \RequirePackage{framed} |
| |
19 \RequirePackage{ifthen} |
| |
20 \RequirePackage{color} |
| |
21 % For highlighted code. |
| |
22 \RequirePackage{fancyvrb} |
| |
23 % For table captions. |
| |
24 \RequirePackage{threeparttable} |
| |
25 % Handle footnotes in tables. |
| |
26 \RequirePackage{footnote} |
| |
27 \makesavenoteenv{tabulary} |
| |
28 % For floating figures in the text. |
| |
29 \RequirePackage{wrapfig} |
| |
30 % Separate paragraphs by space by default. |
| |
31 \RequirePackage{parskip} |
| |
32 |
| |
33 % Redefine these colors to your liking in the preamble. |
| |
34 \definecolor{TitleColor}{rgb}{0.126,0.263,0.361} |
| |
35 \definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486} |
| |
36 \definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388} |
| |
37 % Redefine these colors to something not white if you want to have colored |
| |
38 % background and border for code examples. |
| |
39 \definecolor{VerbatimColor}{rgb}{1,1,1} |
| |
40 \definecolor{VerbatimBorderColor}{rgb}{1,1,1} |
| |
41 |
| |
42 % Uncomment these two lines to ignore the paper size and make the page |
| |
43 % size more like a typical published manual. |
| |
44 %\renewcommand{\paperheight}{9in} |
| |
45 %\renewcommand{\paperwidth}{8.5in} % typical squarish manual |
| |
46 %\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python'' |
| |
47 |
| |
48 % For graphicx, check if we are compiling under latex or pdflatex. |
| |
49 \ifx\pdftexversion\undefined |
| |
50 \usepackage{graphicx} |
| |
51 \else |
| |
52 \usepackage[pdftex]{graphicx} |
| |
53 \fi |
| |
54 |
| |
55 % for PDF output, use colors and maximal compression |
| |
56 \newif\ifsphinxpdfoutput\sphinxpdfoutputfalse |
| |
57 \ifx\pdfoutput\undefined\else\ifcase\pdfoutput |
| |
58 \let\py@NormalColor\relax |
| |
59 \let\py@TitleColor\relax |
| |
60 \else |
| |
61 \sphinxpdfoutputtrue |
| |
62 \input{pdfcolor} |
| |
63 \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} |
| |
64 \def\py@TitleColor{\color{TitleColor}} |
| |
65 \pdfcompresslevel=9 |
| |
66 \fi\fi |
| |
67 |
| |
68 % XeLaTeX can do colors, too |
| |
69 \ifx\XeTeXrevision\undefined\else |
| |
70 \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}} |
| |
71 \def\py@TitleColor{\color{TitleColor}} |
| |
72 \fi |
| |
73 |
| |
74 % Increase printable page size (copied from fullpage.sty) |
| |
75 \topmargin 0pt |
| |
76 \advance \topmargin by -\headheight |
| |
77 \advance \topmargin by -\headsep |
| |
78 |
| |
79 % attempt to work a little better for A4 users |
| |
80 \textheight \paperheight |
| |
81 \advance\textheight by -2in |
| |
82 |
| |
83 \oddsidemargin 0pt |
| |
84 \evensidemargin 0pt |
| |
85 %\evensidemargin -.25in % for ``manual size'' documents |
| |
86 \marginparwidth 0.5in |
| |
87 |
| |
88 \textwidth \paperwidth |
| |
89 \advance\textwidth by -2in |
| |
90 |
| |
91 |
| |
92 % Style parameters and macros used by most documents here |
| |
93 \raggedbottom |
| |
94 \sloppy |
| |
95 \hbadness = 5000 % don't print trivial gripes |
| |
96 |
| |
97 \pagestyle{empty} % start this way; change for |
| |
98 \pagenumbering{roman} % ToC & chapters |
| |
99 |
| |
100 % Use this to set the font family for headers and other decor: |
| |
101 \newcommand{\py@HeaderFamily}{\sffamily\bfseries} |
| |
102 |
| |
103 % Redefine the 'normal' header/footer style when using "fancyhdr" package: |
| |
104 \@ifundefined{fancyhf}{}{ |
| |
105 % Use \pagestyle{normal} as the primary pagestyle for text. |
| |
106 \fancypagestyle{normal}{ |
| |
107 \fancyhf{} |
| |
108 \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} |
| |
109 \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}} |
| |
110 \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}} |
| |
111 \fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}} |
| |
112 \renewcommand{\headrulewidth}{0.4pt} |
| |
113 \renewcommand{\footrulewidth}{0.4pt} |
| |
114 } |
| |
115 % Update the plain style so we get the page number & footer line, |
| |
116 % but not a chapter or section title. This is to keep the first |
| |
117 % page of a chapter and the blank page between chapters `clean.' |
| |
118 \fancypagestyle{plain}{ |
| |
119 \fancyhf{} |
| |
120 \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}} |
| |
121 \renewcommand{\headrulewidth}{0pt} |
| |
122 \renewcommand{\footrulewidth}{0.4pt} |
| |
123 } |
| |
124 } |
| |
125 |
| |
126 % Some custom font markup commands. |
| |
127 % |
| |
128 \newcommand{\strong}[1]{{\bf #1}} |
| |
129 \newcommand{\code}[1]{\texttt{#1}} |
| |
130 \newcommand{\bfcode}[1]{\code{\bfseries#1}} |
| |
131 \newcommand{\email}[1]{\textsf{#1}} |
| |
132 |
| |
133 % Redefine the Verbatim environment to allow border and background colors. |
| |
134 % The original environment is still used for verbatims within tables. |
| |
135 \let\OriginalVerbatim=\Verbatim |
| |
136 \let\endOriginalVerbatim=\endVerbatim |
| |
137 |
| |
138 % Play with vspace to be able to keep the indentation. |
| |
139 \newlength\distancetoright |
| |
140 \def\mycolorbox#1{% |
| |
141 \setlength\distancetoright{\linewidth}% |
| |
142 \advance\distancetoright -\@totalleftmargin % |
| |
143 \fcolorbox{VerbatimBorderColor}{VerbatimColor}{% |
| |
144 \begin{minipage}{\distancetoright}% |
| |
145 #1 |
| |
146 \end{minipage}% |
| |
147 }% |
| |
148 } |
| |
149 \def\FrameCommand{\mycolorbox} |
| |
150 |
| |
151 \renewcommand{\Verbatim}[1][1]{% |
| |
152 % list starts new par, but we don't want it to be set apart vertically |
| |
153 \bgroup\parskip=0pt% |
| |
154 \smallskip% |
| |
155 % The list environement is needed to control perfectly the vertical |
| |
156 % space. |
| |
157 \list{}{% |
| |
158 \setlength\parskip{0pt}% |
| |
159 \setlength\itemsep{0ex}% |
| |
160 \setlength\topsep{0ex}% |
| |
161 \setlength\partopsep{0pt}% |
| |
162 \setlength\leftmargin{0pt}% |
| |
163 }% |
| |
164 \item\MakeFramed {\FrameRestore}% |
| |
165 \small% |
| |
166 \OriginalVerbatim[#1]% |
| |
167 } |
| |
168 \renewcommand{\endVerbatim}{% |
| |
169 \endOriginalVerbatim% |
| |
170 \endMakeFramed% |
| |
171 \endlist% |
| |
172 % close group to restore \parskip |
| |
173 \egroup% |
| |
174 } |
| |
175 |
| |
176 |
| |
177 % \moduleauthor{name}{email} |
| |
178 \newcommand{\moduleauthor}[2]{} |
| |
179 |
| |
180 % \sectionauthor{name}{email} |
| |
181 \newcommand{\sectionauthor}[2]{} |
| |
182 |
| |
183 % Augment the sectioning commands used to get our own font family in place, |
| |
184 % and reset some internal data items: |
| |
185 \titleformat{\section}{\Large\py@HeaderFamily}% |
| |
186 {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor} |
| |
187 \titleformat{\subsection}{\large\py@HeaderFamily}% |
| |
188 {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} |
| |
189 \titleformat{\subsubsection}{\py@HeaderFamily}% |
| |
190 {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} |
| |
191 \titleformat{\paragraph}{\small\py@HeaderFamily}% |
| |
192 {\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor} |
| |
193 |
| |
194 % {fulllineitems} is the main environment for object descriptions. |
| |
195 % |
| |
196 \newcommand{\py@itemnewline}[1]{% |
| |
197 \@tempdima\linewidth% |
| |
198 \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}% |
| |
199 } |
| |
200 |
| |
201 \newenvironment{fulllineitems}{ |
| |
202 \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt |
| |
203 \rightmargin 0pt \topsep -\parskip \partopsep \parskip |
| |
204 \itemsep -\parsep |
| |
205 \let\makelabel=\py@itemnewline} |
| |
206 }{\end{list}} |
| |
207 |
| |
208 % \optional is used for ``[, arg]``, i.e. desc_optional nodes. |
| |
209 \newcommand{\optional}[1]{% |
| |
210 {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}} |
| |
211 |
| |
212 \newlength{\py@argswidth} |
| |
213 \newcommand{\py@sigparams}[2]{% |
| |
214 \parbox[t]{\py@argswidth}{#1\code{)}#2}} |
| |
215 \newcommand{\pysigline}[1]{\item[#1]\nopagebreak} |
| |
216 \newcommand{\pysiglinewithargsret}[3]{% |
| |
217 \settowidth{\py@argswidth}{#1\code{(}}% |
| |
218 \addtolength{\py@argswidth}{-2\py@argswidth}% |
| |
219 \addtolength{\py@argswidth}{\linewidth}% |
| |
220 \item[#1\code{(}\py@sigparams{#2}{#3}]} |
| |
221 |
| |
222 % Production lists |
| |
223 % |
| |
224 \newenvironment{productionlist}{ |
| |
225 % \def\optional##1{{\Large[}##1{\Large]}} |
| |
226 \def\production##1##2{\\\code{##1}&::=&\code{##2}} |
| |
227 \def\productioncont##1{\\& &\code{##1}} |
| |
228 \parindent=2em |
| |
229 \indent |
| |
230 \begin{tabular}{lcl} |
| |
231 }{% |
| |
232 \end{tabular} |
| |
233 } |
| |
234 |
| |
235 % Notices / Admonitions |
| |
236 % |
| |
237 \newlength{\py@noticelength} |
| |
238 |
| |
239 \newcommand{\py@heavybox}{ |
| |
240 \setlength{\fboxrule}{1pt} |
| |
241 \setlength{\fboxsep}{6pt} |
| |
242 \setlength{\py@noticelength}{\linewidth} |
| |
243 \addtolength{\py@noticelength}{-2\fboxsep} |
| |
244 \addtolength{\py@noticelength}{-2\fboxrule} |
| |
245 %\setlength{\shadowsize}{3pt} |
| |
246 \Sbox |
| |
247 \minipage{\py@noticelength} |
| |
248 } |
| |
249 \newcommand{\py@endheavybox}{ |
| |
250 \endminipage |
| |
251 \endSbox |
| |
252 \fbox{\TheSbox} |
| |
253 } |
| |
254 |
| |
255 \newcommand{\py@lightbox}{{% |
| |
256 \setlength\parskip{0pt}\par |
| |
257 \rule[0ex]{\linewidth}{0.5pt}% |
| |
258 \par\vspace{-0.5ex}% |
| |
259 }} |
| |
260 \newcommand{\py@endlightbox}{{% |
| |
261 \setlength{\parskip}{0pt}% |
| |
262 \par\rule[0.5ex]{\linewidth}{0.5pt}% |
| |
263 \par\vspace{-0.5ex}% |
| |
264 }} |
| |
265 |
| |
266 % Some are quite plain: |
| |
267 \newcommand{\py@noticestart@note}{\py@lightbox} |
| |
268 \newcommand{\py@noticeend@note}{\py@endlightbox} |
| |
269 \newcommand{\py@noticestart@hint}{\py@lightbox} |
| |
270 \newcommand{\py@noticeend@hint}{\py@endlightbox} |
| |
271 \newcommand{\py@noticestart@important}{\py@lightbox} |
| |
272 \newcommand{\py@noticeend@important}{\py@endlightbox} |
| |
273 \newcommand{\py@noticestart@tip}{\py@lightbox} |
| |
274 \newcommand{\py@noticeend@tip}{\py@endlightbox} |
| |
275 |
| |
276 % Others gets more visible distinction: |
| |
277 \newcommand{\py@noticestart@warning}{\py@heavybox} |
| |
278 \newcommand{\py@noticeend@warning}{\py@endheavybox} |
| |
279 \newcommand{\py@noticestart@caution}{\py@heavybox} |
| |
280 \newcommand{\py@noticeend@caution}{\py@endheavybox} |
| |
281 \newcommand{\py@noticestart@attention}{\py@heavybox} |
| |
282 \newcommand{\py@noticeend@attention}{\py@endheavybox} |
| |
283 \newcommand{\py@noticestart@danger}{\py@heavybox} |
| |
284 \newcommand{\py@noticeend@danger}{\py@endheavybox} |
| |
285 \newcommand{\py@noticestart@error}{\py@heavybox} |
| |
286 \newcommand{\py@noticeend@error}{\py@endheavybox} |
| |
287 |
| |
288 \newenvironment{notice}[2]{ |
| |
289 \def\py@noticetype{#1} |
| |
290 \csname py@noticestart@#1\endcsname |
| |
291 \strong{#2} |
| |
292 }{\csname py@noticeend@\py@noticetype\endcsname} |
| |
293 |
| |
294 % Allow the release number to be specified independently of the |
| |
295 % \date{}. This allows the date to reflect the document's date and |
| |
296 % release to specify the release that is documented. |
| |
297 % |
| |
298 \newcommand{\py@release}{} |
| |
299 \newcommand{\version}{} |
| |
300 \newcommand{\shortversion}{} |
| |
301 \newcommand{\releaseinfo}{} |
| |
302 \newcommand{\releasename}{Release} |
| |
303 \newcommand{\release}[1]{% |
| |
304 \renewcommand{\py@release}{\releasename\space\version}% |
| |
305 \renewcommand{\version}{#1}} |
| |
306 \newcommand{\setshortversion}[1]{% |
| |
307 \renewcommand{\shortversion}{#1}} |
| |
308 \newcommand{\setreleaseinfo}[1]{% |
| |
309 \renewcommand{\releaseinfo}{#1}} |
| |
310 |
| |
311 % Allow specification of the author's address separately from the |
| |
312 % author's name. This can be used to format them differently, which |
| |
313 % is a good thing. |
| |
314 % |
| |
315 \newcommand{\py@authoraddress}{} |
| |
316 \newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}} |
| |
317 |
| |
318 % This sets up the fancy chapter headings that make the documents look |
| |
319 % at least a little better than the usual LaTeX output. |
| |
320 % |
| |
321 \@ifundefined{ChTitleVar}{}{ |
| |
322 \ChNameVar{\raggedleft\normalsize\py@HeaderFamily} |
| |
323 \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily} |
| |
324 \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily} |
| |
325 % This creates chapter heads without the leading \vspace*{}: |
| |
326 \def\@makechapterhead#1{% |
| |
327 {\parindent \z@ \raggedright \normalfont |
| |
328 \ifnum \c@secnumdepth >\m@ne |
| |
329 \DOCH |
| |
330 \fi |
| |
331 \interlinepenalty\@M |
| |
332 \DOTI{#1} |
| |
333 } |
| |
334 } |
| |
335 } |
| |
336 |
| |
337 % Redefine description environment so that it is usable inside fulllineitems. |
| |
338 % |
| |
339 \renewcommand{\description}{% |
| |
340 \list{}{\labelwidth\z@% |
| |
341 \itemindent-\leftmargin% |
| |
342 \labelsep5pt% |
| |
343 \let\makelabel=\descriptionlabel}} |
| |
344 |
| |
345 % Definition lists; requested by AMK for HOWTO documents. Probably useful |
| |
346 % elsewhere as well, so keep in in the general style support. |
| |
347 % |
| |
348 \newenvironment{definitions}{% |
| |
349 \begin{description}% |
| |
350 \def\term##1{\item[##1]\mbox{}\\*[0mm]} |
| |
351 }{% |
| |
352 \end{description}% |
| |
353 } |
| |
354 |
| |
355 % Tell TeX about pathological hyphenation cases: |
| |
356 \hyphenation{Base-HTTP-Re-quest-Hand-ler} |
| |
357 |
| |
358 |
| |
359 % The following is stuff copied from docutils' latex writer. |
| |
360 % |
| |
361 \newcommand{\optionlistlabel}[1]{\bf #1 \hfill} |
| |
362 \newenvironment{optionlist}[1] |
| |
363 {\begin{list}{} |
| |
364 {\setlength{\labelwidth}{#1} |
| |
365 \setlength{\rightmargin}{1cm} |
| |
366 \setlength{\leftmargin}{\rightmargin} |
| |
367 \addtolength{\leftmargin}{\labelwidth} |
| |
368 \addtolength{\leftmargin}{\labelsep} |
| |
369 \renewcommand{\makelabel}{\optionlistlabel}} |
| |
370 }{\end{list}} |
| |
371 |
| |
372 \newlength{\lineblockindentation} |
| |
373 \setlength{\lineblockindentation}{2.5em} |
| |
374 \newenvironment{lineblock}[1] |
| |
375 {\begin{list}{} |
| |
376 {\setlength{\partopsep}{\parskip} |
| |
377 \addtolength{\partopsep}{\baselineskip} |
| |
378 \topsep0pt\itemsep0.15\baselineskip\parsep0pt |
| |
379 \leftmargin#1} |
| |
380 \raggedright} |
| |
381 {\end{list}} |
| |
382 |
| |
383 % Redefine includgraphics for avoiding images larger than the screen size |
| |
384 % If the size is not specified. |
| |
385 \let\py@Oldincludegraphics\includegraphics |
| |
386 |
| |
387 \newbox\image@box% |
| |
388 \newdimen\image@width% |
| |
389 \renewcommand\includegraphics[2][\@empty]{% |
| |
390 \ifx#1\@empty% |
| |
391 \setbox\image@box=\hbox{\py@Oldincludegraphics{#2}}% |
| |
392 \image@width\wd\image@box% |
| |
393 \ifdim \image@width>\linewidth% |
| |
394 \setbox\image@box=\hbox{\py@Oldincludegraphics[width=\linewidth]{#2}}% |
| |
395 \box\image@box% |
| |
396 \else% |
| |
397 \py@Oldincludegraphics{#2}% |
| |
398 \fi% |
| |
399 \else% |
| |
400 \py@Oldincludegraphics[#1]{#2}% |
| |
401 \fi% |
| |
402 } |
| |
403 |
| |
404 |
| |
405 % Fix the index and bibliography environments to add an entry to the Table of |
| |
406 % Contents; this is much nicer than just having to jump to the end of the book |
| |
407 % and flip around, especially with multiple indexes. |
| |
408 % |
| |
409 \let\py@OldTheindex=\theindex |
| |
410 \renewcommand{\theindex}{ |
| |
411 \cleardoublepage |
| |
412 \phantomsection |
| |
413 \py@OldTheindex |
| |
414 \addcontentsline{toc}{chapter}{\indexname} |
| |
415 } |
| |
416 |
| |
417 \let\py@OldThebibliography=\thebibliography |
| |
418 \renewcommand{\thebibliography}[1]{ |
| |
419 \cleardoublepage |
| |
420 \phantomsection |
| |
421 \py@OldThebibliography{1} |
| |
422 \addcontentsline{toc}{chapter}{\bibname} |
| |
423 } |
| |
424 |
| |
425 % Include hyperref last. |
| |
426 \RequirePackage[colorlinks,breaklinks, |
| |
427 linkcolor=InnerLinkColor,filecolor=OuterLinkColor, |
| |
428 menucolor=OuterLinkColor,urlcolor=OuterLinkColor, |
| |
429 citecolor=InnerLinkColor]{hyperref} |
| |
430 % Fix anchor placement for figures with captions. |
| |
431 % (Note: we don't use a package option here; instead, we give an explicit |
| |
432 % \capstart for figures that actually have a caption.) |
| |
433 \RequirePackage{hypcap} |
| |
434 |
| |
435 % From docutils.writers.latex2e |
| |
436 \providecommand{\DUspan}[2]{% |
| |
437 {% group ("span") to limit the scope of styling commands |
| |
438 \@for\node@class@name:=#1\do{% |
| |
439 \ifcsname docutilsrole\node@class@name\endcsname% |
| |
440 \csname docutilsrole\node@class@name\endcsname% |
| |
441 \fi% |
| |
442 }% |
| |
443 {#2}% node content |
| |
444 }% close "span" |
| |
445 } |
| |
446 |
| |
447 \providecommand*{\DUprovidelength}[2]{ |
| |
448 \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{} |
| |
449 } |
| |
450 |
| |
451 \DUprovidelength{\DUlineblockindent}{2.5em} |
| |
452 \ifthenelse{\isundefined{\DUlineblock}}{ |
| |
453 \newenvironment{DUlineblock}[1]{% |
| |
454 \list{}{\setlength{\partopsep}{\parskip} |
| |
455 \addtolength{\partopsep}{\baselineskip} |
| |
456 \setlength{\topsep}{0pt} |
| |
457 \setlength{\itemsep}{0.15\baselineskip} |
| |
458 \setlength{\parsep}{0pt} |
| |
459 \setlength{\leftmargin}{#1}} |
| |
460 \raggedright |
| |
461 } |
| |
462 {\endlist} |
| |
463 }{} |
| |
464 |
| |
465 |
| |
466 % From footmisc.sty: allows footnotes in titles |
| |
467 \let\FN@sf@@footnote\footnote |
| |
468 \def\footnote{\ifx\protect\@typeset@protect |
| |
469 \expandafter\FN@sf@@footnote |
| |
470 \else |
| |
471 \expandafter\FN@sf@gobble@opt |
| |
472 \fi |
| |
473 } |
| |
474 \edef\FN@sf@gobble@opt{\noexpand\protect |
| |
475 \expandafter\noexpand\csname FN@sf@gobble@opt \endcsname} |
| |
476 \expandafter\def\csname FN@sf@gobble@opt \endcsname{% |
| |
477 \@ifnextchar[%] |
| |
478 \FN@sf@gobble@twobracket |
| |
479 \@gobble |
| |
480 } |
| |
481 \def\FN@sf@gobble@twobracket[#1]#2{} |