4
% Adapted from the old python.sty, mostly written by Fred Drake,
8
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
9
\ProvidesPackage{sphinx}[2010/01/15 LaTeX package (Sphinx markup)]
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}
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}
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}
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''
48
% For graphicx, check if we are compiling under latex or pdflatex.
49
\ifx\pdftexversion\undefined
52
\usepackage[pdftex]{graphicx}
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
63
\def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}}
64
\def\py@TitleColor{\color{TitleColor}}
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}}
74
% Increase printable page size (copied from fullpage.sty)
76
\advance \topmargin by -\headheight
77
\advance \topmargin by -\headsep
79
% attempt to work a little better for A4 users
80
\textheight \paperheight
81
\advance\textheight by -2in
85
%\evensidemargin -.25in % for ``manual size'' documents
88
\textwidth \paperwidth
89
\advance\textwidth by -2in
92
% Style parameters and macros used by most documents here
95
\hbadness = 5000 % don't print trivial gripes
97
\pagestyle{empty} % start this way; change for
98
\pagenumbering{roman} % ToC & chapters
100
% Use this to set the font family for headers and other decor:
101
\newcommand{\py@HeaderFamily}{\sffamily\bfseries}
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}{
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}
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}{
120
\fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
121
\renewcommand{\headrulewidth}{0pt}
122
\renewcommand{\footrulewidth}{0.4pt}
126
% Some custom font markup commands.
128
\newcommand{\strong}[1]{{\bf #1}}
129
\newcommand{\code}[1]{\texttt{#1}}
130
\newcommand{\bfcode}[1]{\code{\bfseries#1}}
131
\newcommand{\samp}[1]{`\code{#1}'}
132
\newcommand{\email}[1]{\textsf{#1}}
134
% Redefine the Verbatim environment to allow border and background colors.
135
% The original environment is still used for verbatims within tables.
136
\let\OriginalVerbatim=\Verbatim
137
\let\endOriginalVerbatim=\endVerbatim
139
% Play with vspace to be able to keep the indentation.
140
\newlength\distancetoright
142
\setlength\distancetoright{\linewidth}%
143
\advance\distancetoright -\@totalleftmargin %
144
\fcolorbox{VerbatimBorderColor}{VerbatimColor}{%
145
\begin{minipage}{\distancetoright}%
150
\def\FrameCommand{\mycolorbox}
152
\renewcommand{\Verbatim}[1][1]{%
153
% list starts new par, but we don't want it to be set apart vertically
156
% The list environement is needed to control perfectly the vertical
159
\setlength\parskip{0pt}%
160
\setlength\itemsep{0ex}%
161
\setlength\topsep{0ex}%
162
\setlength\partopsep{0pt}%
163
\setlength\leftmargin{0pt}%
165
\item\MakeFramed {\FrameRestore}%
167
\OriginalVerbatim[#1]%
169
\renewcommand{\endVerbatim}{%
170
\endOriginalVerbatim%
173
% close group to restore \parskip
178
% \moduleauthor{name}{email}
179
\newcommand{\moduleauthor}[2]{}
181
% \sectionauthor{name}{email}
182
\newcommand{\sectionauthor}[2]{}
184
% Augment the sectioning commands used to get our own font family in place,
185
% and reset some internal data items:
186
\titleformat{\section}{\Large\py@HeaderFamily}%
187
{\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor}
188
\titleformat{\subsection}{\large\py@HeaderFamily}%
189
{\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
190
\titleformat{\subsubsection}{\py@HeaderFamily}%
191
{\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
192
\titleformat{\paragraph}{\small\py@HeaderFamily}%
193
{\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor}
195
% {fulllineitems} is the main environment for object descriptions.
197
\newcommand{\py@itemnewline}[1]{%
198
\@tempdima\linewidth%
199
\advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
202
\newenvironment{fulllineitems}{
203
\begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
204
\rightmargin 0pt \topsep -\parskip \partopsep \parskip
206
\let\makelabel=\py@itemnewline}
209
% \optional is used for ``[, arg]``, i.e. desc_optional nodes.
210
\newcommand{\optional}[1]{%
211
{\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
213
\newlength{\py@argswidth}
214
\newcommand{\py@sigparams}[2]{%
215
\parbox[t]{\py@argswidth}{#1\code{)}#2}}
216
\newcommand{\pysigline}[1]{\item[#1]\nopagebreak}
217
\newcommand{\pysiglinewithargsret}[3]{%
218
\settowidth{\py@argswidth}{#1\code{(}}%
219
\addtolength{\py@argswidth}{-2\py@argswidth}%
220
\addtolength{\py@argswidth}{\linewidth}%
221
\item[#1\code{(}\py@sigparams{#2}{#3}]}
225
\newenvironment{productionlist}{
226
% \def\optional##1{{\Large[}##1{\Large]}}
227
\def\production##1##2{\\\code{##1}&::=&\code{##2}}
228
\def\productioncont##1{\\& &\code{##1}}
236
% Notices / Admonitions
238
\newlength{\py@noticelength}
240
\newcommand{\py@heavybox}{
241
\setlength{\fboxrule}{1pt}
242
\setlength{\fboxsep}{6pt}
243
\setlength{\py@noticelength}{\linewidth}
244
\addtolength{\py@noticelength}{-2\fboxsep}
245
\addtolength{\py@noticelength}{-2\fboxrule}
246
%\setlength{\shadowsize}{3pt}
248
\minipage{\py@noticelength}
250
\newcommand{\py@endheavybox}{
256
\newcommand{\py@lightbox}{{%
257
\setlength\parskip{0pt}\par
258
\rule[0ex]{\linewidth}{0.5pt}%
261
\newcommand{\py@endlightbox}{{%
262
\setlength{\parskip}{0pt}%
263
\par\rule[0.5ex]{\linewidth}{0.5pt}%
267
% Some are quite plain:
268
\newcommand{\py@noticestart@note}{\py@lightbox}
269
\newcommand{\py@noticeend@note}{\py@endlightbox}
270
\newcommand{\py@noticestart@hint}{\py@lightbox}
271
\newcommand{\py@noticeend@hint}{\py@endlightbox}
272
\newcommand{\py@noticestart@important}{\py@lightbox}
273
\newcommand{\py@noticeend@important}{\py@endlightbox}
274
\newcommand{\py@noticestart@tip}{\py@lightbox}
275
\newcommand{\py@noticeend@tip}{\py@endlightbox}
277
% Others gets more visible distinction:
278
\newcommand{\py@noticestart@warning}{\py@heavybox}
279
\newcommand{\py@noticeend@warning}{\py@endheavybox}
280
\newcommand{\py@noticestart@caution}{\py@heavybox}
281
\newcommand{\py@noticeend@caution}{\py@endheavybox}
282
\newcommand{\py@noticestart@attention}{\py@heavybox}
283
\newcommand{\py@noticeend@attention}{\py@endheavybox}
284
\newcommand{\py@noticestart@danger}{\py@heavybox}
285
\newcommand{\py@noticeend@danger}{\py@endheavybox}
286
\newcommand{\py@noticestart@error}{\py@heavybox}
287
\newcommand{\py@noticeend@error}{\py@endheavybox}
289
\newenvironment{notice}[2]{
290
\def\py@noticetype{#1}
291
\csname py@noticestart@#1\endcsname
293
}{\csname py@noticeend@\py@noticetype\endcsname}
295
% Allow the release number to be specified independently of the
296
% \date{}. This allows the date to reflect the document's date and
297
% release to specify the release that is documented.
299
\newcommand{\py@release}{}
300
\newcommand{\version}{}
301
\newcommand{\shortversion}{}
302
\newcommand{\releaseinfo}{}
303
\newcommand{\releasename}{Release}
304
\newcommand{\release}[1]{%
305
\renewcommand{\py@release}{\releasename\space\version}%
306
\renewcommand{\version}{#1}}
307
\newcommand{\setshortversion}[1]{%
308
\renewcommand{\shortversion}{#1}}
309
\newcommand{\setreleaseinfo}[1]{%
310
\renewcommand{\releaseinfo}{#1}}
312
% Allow specification of the author's address separately from the
313
% author's name. This can be used to format them differently, which
316
\newcommand{\py@authoraddress}{}
317
\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
319
% This sets up the fancy chapter headings that make the documents look
320
% at least a little better than the usual LaTeX output.
322
\@ifundefined{ChTitleVar}{}{
323
\ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
324
\ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
325
\ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily}
326
% This creates chapter heads without the leading \vspace*{}:
327
\def\@makechapterhead#1{%
328
{\parindent \z@ \raggedright \normalfont
329
\ifnum \c@secnumdepth >\m@ne
338
% Redefine description environment so that it is usable inside fulllineitems.
340
\renewcommand{\description}{%
341
\list{}{\labelwidth\z@%
342
\itemindent-\leftmargin%
344
\let\makelabel=\descriptionlabel}}
346
% Definition lists; requested by AMK for HOWTO documents. Probably useful
347
% elsewhere as well, so keep in in the general style support.
349
\newenvironment{definitions}{%
351
\def\term##1{\item[##1]\mbox{}\\*[0mm]}
356
% Tell TeX about pathological hyphenation cases:
357
\hyphenation{Base-HTTP-Re-quest-Hand-ler}
360
% The following is stuff copied from docutils' latex writer.
362
\newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
363
\newenvironment{optionlist}[1]
365
{\setlength{\labelwidth}{#1}
366
\setlength{\rightmargin}{1cm}
367
\setlength{\leftmargin}{\rightmargin}
368
\addtolength{\leftmargin}{\labelwidth}
369
\addtolength{\leftmargin}{\labelsep}
370
\renewcommand{\makelabel}{\optionlistlabel}}
373
\newlength{\lineblockindentation}
374
\setlength{\lineblockindentation}{2.5em}
375
\newenvironment{lineblock}[1]
377
{\setlength{\partopsep}{\parskip}
378
\addtolength{\partopsep}{\baselineskip}
379
\topsep0pt\itemsep0.15\baselineskip\parsep0pt
384
% Redefine includgraphics for avoiding images larger than the screen size
385
% If the size is not specified.
386
\let\py@Oldincludegraphics\includegraphics
389
\newdimen\image@width%
390
\renewcommand\includegraphics[2][\@empty]{%
392
\setbox\image@box=\hbox{\py@Oldincludegraphics{#2}}%
393
\image@width\wd\image@box%
394
\ifdim \image@width>\linewidth%
395
\setbox\image@box=\hbox{\py@Oldincludegraphics[width=\linewidth]{#2}}%
398
\py@Oldincludegraphics{#2}%
401
\py@Oldincludegraphics[#1]{#2}%
406
% Fix the index and bibliography environments to add an entry to the Table of
407
% Contents; this is much nicer than just having to jump to the end of the book
408
% and flip around, especially with multiple indexes.
410
\let\py@OldTheindex=\theindex
411
\renewcommand{\theindex}{
415
\addcontentsline{toc}{chapter}{\indexname}
418
\let\py@OldThebibliography=\thebibliography
419
\renewcommand{\thebibliography}[1]{
422
\py@OldThebibliography{1}
423
\addcontentsline{toc}{chapter}{\bibname}
426
% Include hyperref last.
427
\RequirePackage[colorlinks,breaklinks,
428
linkcolor=InnerLinkColor,filecolor=OuterLinkColor,
429
menucolor=OuterLinkColor,urlcolor=OuterLinkColor,
430
citecolor=InnerLinkColor]{hyperref}
431
% Fix anchor placement for figures with captions.
432
% (Note: we don't use a package option here; instead, we give an explicit
433
% \capstart for figures that actually have a caption.)
434
\RequirePackage{hypcap}
436
% From docutils.writers.latex2e
437
\providecommand{\DUspan}[2]{%
438
{% group ("span") to limit the scope of styling commands
439
\@for\node@class@name:=#1\do{%
440
\ifcsname docutilsrole\node@class@name\endcsname%
441
\csname docutilsrole\node@class@name\endcsname%
448
\providecommand*{\DUprovidelength}[2]{
449
\ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
452
\DUprovidelength{\DUlineblockindent}{2.5em}
453
\ifthenelse{\isundefined{\DUlineblock}}{
454
\newenvironment{DUlineblock}[1]{%
455
\list{}{\setlength{\partopsep}{\parskip}
456
\addtolength{\partopsep}{\baselineskip}
457
\setlength{\topsep}{0pt}
458
\setlength{\itemsep}{0.15\baselineskip}
459
\setlength{\parsep}{0pt}
460
\setlength{\leftmargin}{#1}}