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{} |
|