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 \@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}}
13 \RequirePackage{textcomp}
14 \RequirePackage{fancybox}
15 \RequirePackage{titlesec}
16 \RequirePackage{tabulary}
17 \RequirePackage{amsmath} % for \text
18 \RequirePackage{makeidx}
19 \RequirePackage{framed}
20 \RequirePackage{ifthen}
21 \RequirePackage{color}
22 % For highlighted code.
23 \RequirePackage{fancyvrb}
25 \RequirePackage{threeparttable}
26 % Handle footnotes in tables.
27 \RequirePackage{footnote}
28 \makesavenoteenv{tabulary}
29 % For floating figures in the text.
30 \RequirePackage{wrapfig}
31 % Separate paragraphs by space by default.
32 \RequirePackage{parskip}
33 % For parsed-literal blocks.
34 \RequirePackage{alltt}
36 % Redefine these colors to your liking in the preamble.
37 \definecolor{TitleColor}{rgb}{0.126,0.263,0.361}
38 \definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486}
39 \definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388}
40 % Redefine these colors to something not white if you want to have colored
41 % background and border for code examples.
42 \definecolor{VerbatimColor}{rgb}{1,1,1}
43 \definecolor{VerbatimBorderColor}{rgb}{1,1,1}
45 % Uncomment these two lines to ignore the paper size and make the page
46 % size more like a typical published manual.
47 %\renewcommand{\paperheight}{9in}
48 %\renewcommand{\paperwidth}{8.5in} % typical squarish manual
49 %\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python''
51 % use pdfoutput for pTeX and dvipdfmx
52 \ifx\kanjiskip\undefined\else
53 \ifx\Gin@driver{dvipdfmx.def}\undefined\else
54 \newcount\pdfoutput\pdfoutput=0
58 % For graphicx, check if we are compiling under latex or pdflatex.
59 \ifx\pdftexversion\undefined
62 \usepackage[pdftex]{graphicx}
65 % for PDF output, use colors and maximal compression
66 \newif\ifsphinxpdfoutput\sphinxpdfoutputfalse
67 \ifx\pdfoutput\undefined\else\ifcase\pdfoutput
68 \let\py@NormalColor\relax
69 \let\py@TitleColor\relax
73 \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}}
74 \def\py@TitleColor{\color{TitleColor}}
78 % XeLaTeX can do colors, too
79 \ifx\XeTeXrevision\undefined\else
80 \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}}
81 \def\py@TitleColor{\color{TitleColor}}
84 % Increase printable page size (copied from fullpage.sty)
86 \advance \topmargin by -\headheight
87 \advance \topmargin by -\headsep
89 % attempt to work a little better for A4 users
90 \textheight \paperheight
91 \advance\textheight by -2in
95 %\evensidemargin -.25in % for ``manual size'' documents
98 \textwidth \paperwidth
99 \advance\textwidth by -2in
102 % Style parameters and macros used by most documents here
105 \hbadness = 5000 % don't print trivial gripes
107 \pagestyle{empty} % start this way
109 % Use this to set the font family for headers and other decor:
110 \newcommand{\py@HeaderFamily}{\sffamily\bfseries}
112 % Redefine the 'normal' header/footer style when using "fancyhdr" package:
113 \@ifundefined{fancyhf}{}{
114 % Use \pagestyle{normal} as the primary pagestyle for text.
115 \fancypagestyle{normal}{
117 \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
118 \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
119 \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
120 \fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}}
121 \renewcommand{\headrulewidth}{0.4pt}
122 \renewcommand{\footrulewidth}{0.4pt}
123 % define chaptermark with \@chappos when \@chappos is available for Japanese
124 \ifx\@chappos\undefined\else
125 \def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}}
128 % Update the plain style so we get the page number & footer line,
129 % but not a chapter or section title. This is to keep the first
130 % page of a chapter and the blank page between chapters `clean.'
131 \fancypagestyle{plain}{
133 \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
134 \renewcommand{\headrulewidth}{0pt}
135 \renewcommand{\footrulewidth}{0.4pt}
139 % Some custom font markup commands.
141 \newcommand{\strong}[1]{{\textbf{#1}}}
142 \newcommand{\code}[1]{\texttt{#1}}
143 \newcommand{\bfcode}[1]{\code{\bfseries#1}}
144 \newcommand{\email}[1]{\textsf{#1}}
146 % Redefine the Verbatim environment to allow border and background colors.
147 % The original environment is still used for verbatims within tables.
148 \let\OriginalVerbatim=\Verbatim
149 \let\endOriginalVerbatim=\endVerbatim
151 % Play with vspace to be able to keep the indentation.
152 \newlength\distancetoright
154 \setlength\distancetoright{\linewidth}%
155 \advance\distancetoright -\@totalleftmargin %
156 \fcolorbox{VerbatimBorderColor}{VerbatimColor}{%
157 \begin{minipage}{\distancetoright}%
162 \def\FrameCommand{\mycolorbox}
164 \renewcommand{\Verbatim}[1][1]{%
165 % list starts new par, but we don't want it to be set apart vertically
168 % The list environement is needed to control perfectly the vertical
171 \setlength\parskip{0pt}%
172 \setlength\itemsep{0ex}%
173 \setlength\topsep{0ex}%
174 \setlength\partopsep{0pt}%
175 \setlength\leftmargin{0pt}%
177 \item\MakeFramed {\FrameRestore}%
179 \OriginalVerbatim[#1]%
181 \renewcommand{\endVerbatim}{%
182 \endOriginalVerbatim%
185 % close group to restore \parskip
190 % \moduleauthor{name}{email}
191 \newcommand{\moduleauthor}[2]{}
193 % \sectionauthor{name}{email}
194 \newcommand{\sectionauthor}[2]{}
196 % Augment the sectioning commands used to get our own font family in place,
197 % and reset some internal data items:
198 \titleformat{\section}{\Large\py@HeaderFamily}%
199 {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor}
200 \titleformat{\subsection}{\large\py@HeaderFamily}%
201 {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
202 \titleformat{\subsubsection}{\py@HeaderFamily}%
203 {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
204 \titleformat{\paragraph}{\small\py@HeaderFamily}%
205 {\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor}
207 % {fulllineitems} is the main environment for object descriptions.
209 \newcommand{\py@itemnewline}[1]{%
210 \@tempdima\linewidth%
211 \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
214 \newenvironment{fulllineitems}{
215 \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
216 \rightmargin 0pt \topsep -\parskip \partopsep \parskip
218 \let\makelabel=\py@itemnewline}
221 % \optional is used for ``[, arg]``, i.e. desc_optional nodes.
222 \newcommand{\optional}[1]{%
223 {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
225 \newlength{\py@argswidth}
226 \newcommand{\py@sigparams}[2]{%
227 \parbox[t]{\py@argswidth}{#1\code{)}#2}}
228 \newcommand{\pysigline}[1]{\item[#1]\nopagebreak}
229 \newcommand{\pysiglinewithargsret}[3]{%
230 \settowidth{\py@argswidth}{#1\code{(}}%
231 \addtolength{\py@argswidth}{-2\py@argswidth}%
232 \addtolength{\py@argswidth}{\linewidth}%
233 \item[#1\code{(}\py@sigparams{#2}{#3}]}
237 \newenvironment{productionlist}{
238 % \def\optional##1{{\Large[}##1{\Large]}}
239 \def\production##1##2{\\\code{##1}&::=&\code{##2}}
240 \def\productioncont##1{\\& &\code{##1}}
243 \setlength{\LTpre}{0pt}
244 \setlength{\LTpost}{0pt}
245 \begin{longtable}[l]{lcl}
250 % Notices / Admonitions
252 \newlength{\py@noticelength}
254 \newcommand{\py@heavybox}{
255 \setlength{\fboxrule}{1pt}
256 \setlength{\fboxsep}{6pt}
257 \setlength{\py@noticelength}{\linewidth}
258 \addtolength{\py@noticelength}{-2\fboxsep}
259 \addtolength{\py@noticelength}{-2\fboxrule}
260 %\setlength{\shadowsize}{3pt}
262 \minipage{\py@noticelength}
264 \newcommand{\py@endheavybox}{
270 \newcommand{\py@lightbox}{{%
271 \setlength\parskip{0pt}\par
272 \noindent\rule[0ex]{\linewidth}{0.5pt}%
273 \par\noindent\vspace{-0.5ex}%
275 \newcommand{\py@endlightbox}{{%
276 \setlength{\parskip}{0pt}%
277 \par\noindent\rule[0.5ex]{\linewidth}{0.5pt}%
281 % Some are quite plain:
282 \newcommand{\py@noticestart@note}{\py@lightbox}
283 \newcommand{\py@noticeend@note}{\py@endlightbox}
284 \newcommand{\py@noticestart@hint}{\py@lightbox}
285 \newcommand{\py@noticeend@hint}{\py@endlightbox}
286 \newcommand{\py@noticestart@important}{\py@lightbox}
287 \newcommand{\py@noticeend@important}{\py@endlightbox}
288 \newcommand{\py@noticestart@tip}{\py@lightbox}
289 \newcommand{\py@noticeend@tip}{\py@endlightbox}
291 % Others gets more visible distinction:
292 \newcommand{\py@noticestart@warning}{\py@heavybox}
293 \newcommand{\py@noticeend@warning}{\py@endheavybox}
294 \newcommand{\py@noticestart@caution}{\py@heavybox}
295 \newcommand{\py@noticeend@caution}{\py@endheavybox}
296 \newcommand{\py@noticestart@attention}{\py@heavybox}
297 \newcommand{\py@noticeend@attention}{\py@endheavybox}
298 \newcommand{\py@noticestart@danger}{\py@heavybox}
299 \newcommand{\py@noticeend@danger}{\py@endheavybox}
300 \newcommand{\py@noticestart@error}{\py@heavybox}
301 \newcommand{\py@noticeend@error}{\py@endheavybox}
303 \newenvironment{notice}[2]{
304 \def\py@noticetype{#1}
305 \csname py@noticestart@#1\endcsname
307 }{\csname py@noticeend@\py@noticetype\endcsname}
309 % Allow the release number to be specified independently of the
310 % \date{}. This allows the date to reflect the document's date and
311 % release to specify the release that is documented.
313 \newcommand{\py@release}{}
314 \newcommand{\version}{}
315 \newcommand{\shortversion}{}
316 \newcommand{\releaseinfo}{}
317 \newcommand{\releasename}{Release}
318 \newcommand{\release}[1]{%
319 \renewcommand{\py@release}{\releasename\space\version}%
320 \renewcommand{\version}{#1}}
321 \newcommand{\setshortversion}[1]{%
322 \renewcommand{\shortversion}{#1}}
323 \newcommand{\setreleaseinfo}[1]{%
324 \renewcommand{\releaseinfo}{#1}}
326 % Allow specification of the author's address separately from the
327 % author's name. This can be used to format them differently, which
330 \newcommand{\py@authoraddress}{}
331 \newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
333 % This sets up the fancy chapter headings that make the documents look
334 % at least a little better than the usual LaTeX output.
336 \@ifundefined{ChTitleVar}{}{
337 \ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
338 \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
339 \ChTitleVar{\raggedleft \textrm{\Huge\py@HeaderFamily}}
340 % This creates chapter heads without the leading \vspace*{}:
341 \def\@makechapterhead#1{%
342 {\parindent \z@ \raggedright \normalfont
343 \ifnum \c@secnumdepth >\m@ne
352 % Redefine description environment so that it is usable inside fulllineitems.
354 \renewcommand{\description}{%
355 \list{}{\labelwidth\z@%
356 \itemindent-\leftmargin%
358 \let\makelabel=\descriptionlabel}}
360 % Definition lists; requested by AMK for HOWTO documents. Probably useful
361 % elsewhere as well, so keep in in the general style support.
363 \newenvironment{definitions}{%
365 \def\term##1{\item[##1]\mbox{}\\*[0mm]}
370 % Tell TeX about pathological hyphenation cases:
371 \hyphenation{Base-HTTP-Re-quest-Hand-ler}
374 % The following is stuff copied from docutils' latex writer.
376 \newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
377 \newenvironment{optionlist}[1]
379 {\setlength{\labelwidth}{#1}
380 \setlength{\rightmargin}{1cm}
381 \setlength{\leftmargin}{\rightmargin}
382 \addtolength{\leftmargin}{\labelwidth}
383 \addtolength{\leftmargin}{\labelsep}
384 \renewcommand{\makelabel}{\optionlistlabel}}
387 \newlength{\lineblockindentation}
388 \setlength{\lineblockindentation}{2.5em}
389 \newenvironment{lineblock}[1]
391 {\setlength{\partopsep}{\parskip}
392 \addtolength{\partopsep}{\baselineskip}
393 \topsep0pt\itemsep0.15\baselineskip\parsep0pt
398 % Redefine includgraphics for avoiding images larger than the screen size
399 % If the size is not specified.
400 \let\py@Oldincludegraphics\includegraphics
403 \newdimen\image@width%
404 \renewcommand\includegraphics[2][\@empty]{%
406 \setbox\image@box=\hbox{\py@Oldincludegraphics{#2}}%
407 \image@width\wd\image@box%
408 \ifdim \image@width>\linewidth%
409 \setbox\image@box=\hbox{\py@Oldincludegraphics[width=\linewidth]{#2}}%
412 \py@Oldincludegraphics{#2}%
415 \py@Oldincludegraphics[#1]{#2}%
419 % to make pdf with correct encoded bookmarks in Japanese
420 % this should precede the hyperref package
421 \ifx\kanjiskip\undefined\else
422 \usepackage{atbegshi}
424 \ifnum 42146=\euc"A4A2
425 \AtBeginShipoutFirst{\special{pdf:tounicode EUC-UCS2}}
427 \AtBeginShipoutFirst{\special{pdf:tounicode 90ms-RKSJ-UCS2}}
430 \AtBeginShipoutFirst{\special{pdf:tounicode UTF8-UCS2}}
434 % Include hyperref last.
435 \RequirePackage[colorlinks,breaklinks,
436 linkcolor=InnerLinkColor,filecolor=OuterLinkColor,
437 menucolor=OuterLinkColor,urlcolor=OuterLinkColor,
438 citecolor=InnerLinkColor]{hyperref}
439 % Fix anchor placement for figures with captions.
440 % (Note: we don't use a package option here; instead, we give an explicit
441 % \capstart for figures that actually have a caption.)
442 \RequirePackage{hypcap}
444 % From docutils.writers.latex2e
445 \providecommand{\DUspan}[2]{%
446 {% group ("span") to limit the scope of styling commands
447 \@for\node@class@name:=#1\do{%
448 \ifcsname docutilsrole\node@class@name\endcsname%
449 \csname docutilsrole\node@class@name\endcsname%
456 \providecommand*{\DUprovidelength}[2]{
457 \ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
460 \DUprovidelength{\DUlineblockindent}{2.5em}
461 \ifthenelse{\isundefined{\DUlineblock}}{
462 \newenvironment{DUlineblock}[1]{%
463 \list{}{\setlength{\partopsep}{\parskip}
464 \addtolength{\partopsep}{\baselineskip}
465 \setlength{\topsep}{0pt}
466 \setlength{\itemsep}{0.15\baselineskip}
467 \setlength{\parsep}{0pt}
468 \setlength{\leftmargin}{#1}}
475 % From footmisc.sty: allows footnotes in titles
476 \let\FN@sf@@footnote\footnote
477 \def\footnote{\ifx\protect\@typeset@protect
478 \expandafter\FN@sf@@footnote
480 \expandafter\FN@sf@gobble@opt
483 \edef\FN@sf@gobble@opt{\noexpand\protect
484 \expandafter\noexpand\csname FN@sf@gobble@opt \endcsname}
485 \expandafter\def\csname FN@sf@gobble@opt \endcsname{%
487 \FN@sf@gobble@twobracket
490 \def\FN@sf@gobble@twobracket[#1]#2{}
492 % adjust the margins for footer,
493 % this works with the jsclasses only (Japanese standard document classes)
494 \ifx\@jsc@uplatextrue\undefined\else
495 \hypersetup{setpagesize=false}
496 \setlength\footskip{2\baselineskip}
497 \addtolength{\textheight}{-2\baselineskip}
500 % fix the double index and bibliography on the table of contents
501 % in jsclasses (Japanese standard document classes)
502 \ifx\@jsc@uplatextrue\undefined\else
503 \renewcommand{\theindex}{
508 \renewcommand{\thebibliography}[1]{
511 \py@OldThebibliography{1}
515 % disable \@chappos in Appendix in pTeX
516 \ifx\kanjiskip\undefined\else
517 \let\py@OldAppendix=\appendix
518 \renewcommand{\appendix}{