hacks/sphinx.sty

   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}[2008/05/01 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{color}
  20 % For highlighted code.
  21 \RequirePackage{fancyvrb}
  22 % For table captions.
  23 \RequirePackage{threeparttable}
  24 % Handle footnotes in tables.
  25 \RequirePackage{footnote}
  26 \makesavenoteenv{tabulary}
  27 % For floating figures in the text.
  28 \RequirePackage{wrapfig}
  29 % Separate paragraphs by space by default.
  30 \RequirePackage{parskip}
  31
  32 % Redefine these colors to your liking in the preamble.
  33 \definecolor{TitleColor}{rgb}{0.126,0.263,0.361}
  34 \definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486}
  35 \definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388}
  36 % Redefine these colors to something not white if you want to have colored
  37 % background and border for code examples.
  38 \definecolor{VerbatimColor}{rgb}{1,1,1}
  39 \definecolor{VerbatimBorderColor}{rgb}{1,1,1}
  40
  41 % Uncomment these two lines to ignore the paper size and make the page
  42 % size more like a typical published manual.
  43 %\renewcommand{\paperheight}{9in}
  44 %\renewcommand{\paperwidth}{8.5in}   % typical squarish manual
  45 %\renewcommand{\paperwidth}{7in}     % O'Reilly ``Programmming Python''
  46
  47 % For graphicx, check if we are compiling under latex or pdflatex.
  48 \ifx\pdftexversion\undefined
  49   \usepackage{graphicx}
  50 \else
  51   \usepackage[pdftex]{graphicx}
  52 \fi
  53
  54 % for PDF output, use colors and maximal compression
  55 \newif\ifsphinxpdfoutput\sphinxpdfoutputfalse
  56 \ifx\pdfoutput\undefined\else\ifcase\pdfoutput
  57   \let\py@NormalColor\relax
  58   \let\py@TitleColor\relax
  59 \else
  60   \sphinxpdfoutputtrue
  61   \input{pdfcolor}
  62   \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}}
  63   \def\py@TitleColor{\color{TitleColor}}
  64   \pdfcompresslevel=9
  65 \fi\fi
  66
  67 % XeLaTeX can do colors, too
  68 \ifx\XeTeXrevision\undefined\else
  69   \def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}}
  70   \def\py@TitleColor{\color{TitleColor}}
  71 \fi
  72
  73 % Increase printable page size (copied from fullpage.sty)
  74 \topmargin 0pt
  75 \advance \topmargin by -\headheight
  76 \advance \topmargin by -\headsep
  77
  78 % attempt to work a little better for A4 users
  79 \textheight \paperheight
  80 \advance\textheight by -2in
  81
  82 \oddsidemargin 0pt
  83 \evensidemargin 0pt
  84 %\evensidemargin -.25in  % for ``manual size'' documents
  85 \marginparwidth 0.5in
  86
  87 \textwidth \paperwidth
  88 \advance\textwidth by -2in
  89
  90
  91 % Style parameters and macros used by most documents here
  92 \raggedbottom
  93 \sloppy
  94 \hbadness = 5000                % don't print trivial gripes
  95
  96 \pagestyle{empty}               % start this way; change for
  97 \pagenumbering{roman}           % ToC & chapters
  98
  99 % Use this to set the font family for headers and other decor:
 100 \newcommand{\py@HeaderFamily}{\sffamily\bfseries}
 101
 102 % Redefine the 'normal' header/footer style when using "fancyhdr" package:
 103 \@ifundefined{fancyhf}{}{
 104   % Use \pagestyle{normal} as the primary pagestyle for text.
 105   \fancypagestyle{normal}{
 106     \fancyhf{}
 107     \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
 108     \fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
 109     \fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
 110     \fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}}
 111     \renewcommand{\headrulewidth}{0.4pt}
 112     \renewcommand{\footrulewidth}{0.4pt}
 113   }
 114   % Update the plain style so we get the page number & footer line,
 115   % but not a chapter or section title.  This is to keep the first
 116   % page of a chapter and the blank page between chapters `clean.'
 117   \fancypagestyle{plain}{
 118     \fancyhf{}
 119     \fancyfoot[LE,RO]{{\py@HeaderFamily\thepage}}
 120     \renewcommand{\headrulewidth}{0pt}
 121     \renewcommand{\footrulewidth}{0.4pt}
 122   }
 123 }
 124
 125 % Some custom font markup commands.
 126 %
 127 \newcommand{\strong}[1]{{\bf #1}}
 128 \newcommand{\code}[1]{\texttt{#1}}
 129 \newcommand{\bfcode}[1]{\code{\bfseries#1}}
 130 \newcommand{\samp}[1]{`\code{#1}'}
 131 \newcommand{\email}[1]{\textsf{#1}}
 132
 133 \newcommand{\py@modulebadkey}{{--just-some-junk--}}
 134
 135 % Redefine the Verbatim environment to allow border and background colors.
 136 % The original environment is still used for verbatims within tables.
 137 \let\OriginalVerbatim=\Verbatim
 138 \let\endOriginalVerbatim=\endVerbatim
 139
 140 % Play with vspace to be able to keep the indentation.
 141 \newlength\distancetoright
 142 \newlength\leftsidespace
 143 \def\mycolorbox#1{%
 144   \setlength\leftsidespace{\@totalleftmargin}%
 145   \setlength\distancetoright{\textwidth}%
 146   \advance\distancetoright -\@totalleftmargin %
 147   \noindent\hspace*{\@totalleftmargin}%
 148   \fcolorbox{VerbatimBorderColor}{VerbatimColor}{%
 149   \begin{minipage}{\distancetoright}%
 150     \smallskip%
 151     \noindent\hspace*{-\leftsidespace}%
 152     #1
 153   \end{minipage}%
 154   }%
 155 }
 156 \def\FrameCommand{\mycolorbox}
 157
 158 \renewcommand{\Verbatim}[1][1]{%
 159   % The list environement is needed to control perfectly the vertical
 160   % space.
 161   \list{}{%
 162   \setlength\parskip{0pt}%
 163   \setlength\itemsep{0ex}%
 164   \setlength\topsep{0ex}%
 165   \setlength\partopsep{0pt}%
 166   \setlength\leftmargin{0pt}%
 167   }%
 168   \item\MakeFramed {\FrameRestore}%
 169      \small%
 170     \OriginalVerbatim[#1]%
 171 }
 172 \renewcommand{\endVerbatim}{%
 173     \endOriginalVerbatim%
 174   \endMakeFramed%
 175   \endlist%
 176 }
 177
 178
 179 % Index-entry generation support.
 180 %
 181
 182 % Command to generate two index entries (using subentries)
 183 \newcommand{\indexii}[2]{\index{#1!#2}\index{#2!#1}}
 184
 185 % And three entries (using only one level of subentries)
 186 \newcommand{\indexiii}[3]{\index{#1!#2 #3}\index{#2!#3, #1}\index{#3!#1 #2}}
 187
 188 % And four (again, using only one level of subentries)
 189 \newcommand{\indexiv}[4]{
 190 \index{#1!#2 #3 #4}
 191 \index{#2!#3 #4, #1}
 192 \index{#3!#4, #1 #2}
 193 \index{#4!#1 #2 #3}
 194 }
 195
 196 % support for the module index
 197 \newif\ifpy@UseModuleIndex
 198 \py@UseModuleIndexfalse
 199
 200 \newcommand{\makemodindex}{
 201   \newwrite\modindexfile
 202   \openout\modindexfile=mod\jobname.idx
 203   \py@UseModuleIndextrue
 204 }
 205
 206 \newcommand{\printmodindex}{
 207   \@input@{mod\jobname.ind}
 208 }
 209
 210 % Add the defining entry for a module
 211 \newcommand{\py@modindex}[2]{%
 212   \renewcommand{\py@thismodule}{#1}
 213   \ifpy@UseModuleIndex%
 214     \@ifundefined{py@modplat@\py@thismodulekey}{
 215       \write\modindexfile{\protect\indexentry{#1@{\texttt{#1}}|hyperpage}{\thepage}}%
 216     }{\write\modindexfile{\protect\indexentry{#1@{\texttt{#1 }%
 217         \emph{(\platformof{\py@thismodulekey})}}|hyperpage}{\thepage}}%
 218     }
 219   \fi%
 220 }
 221
 222 % "Current" keys
 223 \newcommand{\py@thisclass}{}
 224 \newcommand{\py@thismodule}{}
 225 \newcommand{\py@thismodulekey}{}
 226 \newcommand{\py@thismoduletype}{}
 227 \newcommand{\py@emptymodule}{}
 228
 229 % \declaremodule[key]{type}{name}
 230 \newcommand{\declaremodule}[3][\py@modulebadkey]{
 231   \renewcommand{\py@thismoduletype}{#2}
 232   \ifx\py@modulebadkey#1
 233     \renewcommand{\py@thismodulekey}{#3}
 234   \else
 235     \renewcommand{\py@thismodulekey}{#1}
 236   \fi
 237   \py@modindex{#3}{}
 238   %\label{module-\py@thismodulekey}
 239 }
 240
 241 % Record module platforms for the Module Index
 242 \newif\ifpy@ModPlatformFileIsOpen \py@ModPlatformFileIsOpenfalse
 243 \long\def\py@writeModPlatformFile#1{%
 244   \protected@write\py@ModPlatformFile%
 245     {\let\label\@gobble \let\index\@gobble \let\glossary\@gobble}%
 246     {\string#1}%
 247 }
 248 \newcommand{\py@ModPlatformFilename}{\jobname.pla}
 249 \newcommand{\platform}[1]{
 250   \ifpy@ModPlatformFileIsOpen\else
 251     \newwrite\py@ModPlatformFile
 252     \openout\py@ModPlatformFile=\py@ModPlatformFilename
 253     \py@ModPlatformFileIsOpentrue
 254   \fi
 255   \py@writeModPlatformFile{\py@defplatform{\py@thismodulekey}{#1}}
 256 }
 257 \newcommand{\py@defplatform}[2]{\expandafter\def\csname py@modplat@#1\endcsname{#2}}
 258 \newcommand{\platformof}[1]{\csname py@modplat@#1\endcsname}
 259
 260 \InputIfFileExists{\jobname.pla}{}{}
 261
 262 % \moduleauthor{name}{email}
 263 \newcommand{\moduleauthor}[2]{}
 264
 265 % \sectionauthor{name}{email}
 266 \newcommand{\sectionauthor}[2]{}
 267
 268 % Ignore module synopsis.
 269 \newcommand{\modulesynopsis}[1]{}
 270
 271 % Reset "current" objects.
 272 \newcommand{\resetcurrentobjects}{
 273   \renewcommand{\py@thisclass}{}
 274   \renewcommand{\py@thismodule}{}
 275   \renewcommand{\py@thismodulekey}{}
 276   \renewcommand{\py@thismoduletype}{}
 277 }
 278
 279 % Augment the sectioning commands used to get our own font family in place,
 280 % and reset some internal data items:
 281 \titleformat{\section}{\Large\py@HeaderFamily}%
 282             {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor}
 283 \titleformat{\subsection}{\large\py@HeaderFamily}%
 284             {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
 285 \titleformat{\subsubsection}{\py@HeaderFamily}%
 286             {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
 287 \titleformat{\paragraph}{\large\py@HeaderFamily}%
 288             {\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor}
 289
 290
 291 % Now for a lot of semantically-loaded environments that do a ton of magical
 292 % things to get the right formatting and index entries for the stuff in
 293 % Python modules and C API.
 294
 295
 296 % {fulllineitems} is used in one place in libregex.tex, but is really for
 297 % internal use in this file.
 298 %
 299 \newcommand{\py@itemnewline}[1]{%
 300   \@tempdima\linewidth%
 301   \advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
 302 }
 303
 304 \newenvironment{fulllineitems}{
 305   \begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
 306                  \rightmargin 0pt \topsep -\parskip \partopsep \parskip
 307                  \itemsep -\parsep
 308                  \let\makelabel=\py@itemnewline}
 309 }{\end{list}}
 310
 311 % \optional is mostly for use in the arguments parameters to the various
 312 % {*desc} environments defined below, but may be used elsewhere.  Known to
 313 % be used in the debugger chapter.
 314 %
 315 % Typical usage:
 316 %
 317 %     \begin{funcdesc}{myfunc}{reqparm\optional{, optparm}}
 318 %                                    ^^^       ^^^
 319 %                          No space here       No space here
 320 %
 321 % When a function has multiple optional parameters, \optional should be
 322 % nested, not chained.  This is right:
 323 %
 324 %     \begin{funcdesc}{myfunc}{\optional{parm1\optional{, parm2}}}
 325 %
 326 \let\py@badkey=\@undefined
 327
 328 \newcommand{\optional}[1]{%
 329   {\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
 330
 331 % This can be used when a function or method accepts an varying number
 332 % of arguments, such as by using the *args syntax in the parameter list.
 333 \newcommand{\py@moreargs}{...}
 334
 335 % This can be used when you don't want to document the parameters to a
 336 % function or method, but simply state that it's an alias for
 337 % something else.
 338 \newcommand{\py@unspecified}{...}
 339
 340 \newcommand{\py@varvars}[1]{{%
 341     {\let\unspecified=\py@unspecified%
 342       \let\moreargs=\py@moreargs%
 343       \emph{#1}}}}
 344
 345 \newlength{\py@argswidth}
 346 \newcommand{\py@sigparams}[1]{%
 347   \parbox[t]{\py@argswidth}{\py@varvars{#1}\code{)}}}
 348 \newcommand{\py@sigline}[2]{%
 349   \settowidth{\py@argswidth}{#1\code{(}}%
 350   \addtolength{\py@argswidth}{-2\py@argswidth}%
 351   \addtolength{\py@argswidth}{\textwidth}%
 352   \item[#1\code{(}\py@sigparams{#2}]}
 353
 354 % C functions ------------------------------------------------------------
 355 % \begin{cfuncdesc}[refcount]{type}{name}{arglist}
 356 % Note that the [refcount] slot should only be filled in by
 357 % tools/anno-api.py; it pulls the value from the refcounts database.
 358 \newcommand{\cfuncline}[3]{
 359   \py@sigline{\code{#1 \bfcode{#2}}}{#3}%
 360 }
 361 \newenvironment{cfuncdesc}[3]{
 362   \begin{fulllineitems}
 363     \cfuncline{#1}{#2}{#3}
 364 }{\end{fulllineitems}}
 365
 366 % C variables ------------------------------------------------------------
 367 % \begin{cvardesc}{type}{name}
 368 \newenvironment{cvardesc}[2]{
 369   \begin{fulllineitems}
 370     \item[\code{#1 \bfcode{#2}}]
 371 }{\end{fulllineitems}}
 372
 373 % C data types -----------------------------------------------------------
 374 % \begin{ctypedesc}[index name]{typedef name}
 375 \newenvironment{ctypedesc}[2][\py@badkey]{
 376   \begin{fulllineitems}
 377     \item[\bfcode{#2}]
 378 }{\end{fulllineitems}}
 379
 380 % C type fields ----------------------------------------------------------
 381 % \begin{cmemberdesc}{container type}{ctype}{membername}
 382 \newcommand{\cmemberline}[3]{
 383   \item[\code{#2 \bfcode{#3}}]
 384 }
 385 \newenvironment{cmemberdesc}[3]{
 386   \begin{fulllineitems}
 387     \cmemberline{#1}{#2}{#3}
 388 }{\end{fulllineitems}}
 389
 390 % Funky macros -----------------------------------------------------------
 391 % \begin{csimplemacrodesc}{name}
 392 % -- "simple" because it has no args; NOT for constant definitions!
 393 \newenvironment{csimplemacrodesc}[1]{
 394   \begin{fulllineitems}
 395     \item[\bfcode{#1}]
 396 }{\end{fulllineitems}}
 397
 398 % simple functions (not methods) -----------------------------------------
 399 % \begin{funcdesc}{name}{args}
 400 \newcommand{\funcline}[2]{%
 401   \py@sigline{\bfcode{#1}}{#2}}
 402 \newenvironment{funcdesc}[2]{
 403   \begin{fulllineitems}
 404     \funcline{#1}{#2}
 405 }{\end{fulllineitems}}
 406
 407 % classes ----------------------------------------------------------------
 408 % \begin{classdesc}{name}{constructor args}
 409 \newcommand{\classline}[2]{
 410   \py@sigline{\strong{class }\bfcode{#1}}{#2}}
 411 \newenvironment{classdesc}[2]{
 412   % Using \renewcommand doesn't work for this, for unknown reasons:
 413   \global\def\py@thisclass{#1}
 414   \begin{fulllineitems}
 415     \classline{#1}{#2}
 416 }{\end{fulllineitems}}
 417
 418 % \begin{excclassdesc}{name}{constructor args}
 419 % but indexes as an exception
 420 \newenvironment{excclassdesc}[2]{
 421   % Using \renewcommand doesn't work for this, for unknown reasons:
 422   \global\def\py@thisclass{#1}
 423   \begin{fulllineitems}
 424     \py@sigline{\strong{exception }\bfcode{#1}}{#2}%
 425 }{\end{fulllineitems}}
 426
 427 % There is no corresponding {excclassdesc*} environment.  To describe
 428 % a class exception without parameters, use the {excdesc} environment.
 429
 430
 431 \let\py@classbadkey=\@undefined
 432
 433 % object method ----------------------------------------------------------
 434 % \begin{methoddesc}[classname]{methodname}{args}
 435 \newcommand{\methodline}[3][\@undefined]{
 436   \py@sigline{\bfcode{#2}}{#3}}
 437 \newenvironment{methoddesc}[3][\@undefined]{
 438   \begin{fulllineitems}
 439     \ifx\@undefined#1\relax
 440       \methodline{#2}{#3}
 441     \else
 442       \def\py@thisclass{#1}
 443       \methodline{#2}{#3}
 444     \fi
 445 }{\end{fulllineitems}}
 446
 447 % static method ----------------------------------------------------------
 448 % \begin{staticmethoddesc}[classname]{methodname}{args}
 449 \newcommand{\staticmethodline}[3][\@undefined]{
 450   \py@sigline{static \bfcode{#2}}{#3}}
 451 \newenvironment{staticmethoddesc}[3][\@undefined]{
 452   \begin{fulllineitems}
 453     \ifx\@undefined#1\relax
 454       \staticmethodline{#2}{#3}
 455     \else
 456       \def\py@thisclass{#1}
 457       \staticmethodline{#2}{#3}
 458     \fi
 459 }{\end{fulllineitems}}
 460
 461 % class method ----------------------------------------------------------
 462 % \begin{classmethoddesc}[classname]{methodname}{args}
 463 \newcommand{\classmethodline}[3][\@undefined]{
 464   \py@sigline{class \bfcode{#2}}{#3}}
 465 \newenvironment{classmethoddesc}[3][\@undefined]{
 466   \begin{fulllineitems}
 467     \ifx\@undefined#1\relax
 468       \classmethodline{#2}{#3}
 469     \else
 470       \def\py@thisclass{#1}
 471       \classmethodline{#2}{#3}
 472     \fi
 473 }{\end{fulllineitems}}
 474
 475 % object data attribute --------------------------------------------------
 476 % \begin{memberdesc}[classname]{membername}
 477 \newcommand{\memberline}[2][\py@classbadkey]{%
 478   \ifx\@undefined#1\relax
 479     \item[\bfcode{#2}]
 480   \else
 481     \item[\bfcode{#2}]
 482   \fi
 483 }
 484 \newenvironment{memberdesc}[2][\py@classbadkey]{
 485   \begin{fulllineitems}
 486     \ifx\@undefined#1\relax
 487       \memberline{#2}
 488     \else
 489       \def\py@thisclass{#1}
 490       \memberline{#2}
 491     \fi
 492 }{\end{fulllineitems}}
 493
 494 % For exceptions: --------------------------------------------------------
 495 % \begin{excdesc}{name}
 496 %  -- for constructor information, use excclassdesc instead
 497 \newenvironment{excdesc}[1]{
 498   \begin{fulllineitems}
 499     \item[\strong{exception }\bfcode{#1}]
 500 }{\end{fulllineitems}}
 501
 502 % Module data or constants: ----------------------------------------------
 503 % \begin{datadesc}{name}
 504 \newcommand{\dataline}[1]{%
 505   \item[\bfcode{#1}]\nopagebreak}
 506 \newenvironment{datadesc}[1]{
 507   \begin{fulllineitems}
 508     \dataline{#1}
 509 }{\end{fulllineitems}}
 510
 511 % bytecode instruction ---------------------------------------------------
 512 % \begin{opcodedesc}{name}{var}
 513 % -- {var} may be {}
 514 \newenvironment{opcodedesc}[2]{
 515   \begin{fulllineitems}
 516     \item[\bfcode{#1}\quad\emph{#2}]
 517 }{\end{fulllineitems}}
 518
 519 % generic description ----------------------------------------------------
 520 \newcommand{\descline}[1]{%
 521   \item[\bfcode{#1}]\nopagebreak%
 522 }
 523 \newenvironment{describe}[1]{
 524   \begin{fulllineitems}
 525     \descline{#1}
 526 }{\end{fulllineitems}}
 527
 528 % This version is being checked in for the historical record; it shows
 529 % how I've managed to get some aspects of this to work.  It will not
 530 % be used in practice, so a subsequent revision will change things
 531 % again.  This version has problems, but shows how to do something
 532 % that proved more tedious than I'd expected, so I don't want to lose
 533 % the example completely.
 534 %
 535 \newcommand{\grammartoken}[1]{\texttt{#1}}
 536 \newenvironment{productionlist}[1][\py@badkey]{
 537   \def\optional##1{{\Large[}##1{\Large]}}
 538   \def\production##1##2{\code{##1}&::=&\code{##2}\\}
 539   \def\productioncont##1{& &\code{##1}\\}
 540   \def\token##1{##1}
 541   \let\grammartoken=\token
 542   \parindent=2em
 543   \indent
 544   \begin{tabular}{lcl}
 545 }{%
 546   \end{tabular}
 547 }
 548
 549 % Notices / Admonitions
 550 %
 551 \newlength{\py@noticelength}
 552
 553 \newcommand{\py@heavybox}{
 554   \setlength{\fboxrule}{1pt}
 555   \setlength{\fboxsep}{7pt}
 556   \setlength{\py@noticelength}{\linewidth}
 557   \addtolength{\py@noticelength}{-2\fboxsep}
 558   \addtolength{\py@noticelength}{-2\fboxrule}
 559   \setlength{\shadowsize}{3pt}
 560   \Sbox
 561   \minipage{\py@noticelength}
 562 }
 563 \newcommand{\py@endheavybox}{
 564   \endminipage
 565   \endSbox
 566   \fbox{\TheSbox}
 567 }
 568
 569 % Some are quite plain:
 570 \newcommand{\py@noticestart@note}{}
 571 \newcommand{\py@noticeend@note}{}
 572 \newcommand{\py@noticestart@hint}{}
 573 \newcommand{\py@noticeend@hint}{}
 574 \newcommand{\py@noticestart@important}{}
 575 \newcommand{\py@noticeend@important}{}
 576 \newcommand{\py@noticestart@tip}{}
 577 \newcommand{\py@noticeend@tip}{}
 578
 579 % Others gets more visible distinction:
 580 \newcommand{\py@noticestart@warning}{\py@heavybox}
 581 \newcommand{\py@noticeend@warning}{\py@endheavybox}
 582 \newcommand{\py@noticestart@caution}{\py@heavybox}
 583 \newcommand{\py@noticeend@caution}{\py@endheavybox}
 584 \newcommand{\py@noticestart@attention}{\py@heavybox}
 585 \newcommand{\py@noticeend@attention}{\py@endheavybox}
 586 \newcommand{\py@noticestart@danger}{\py@heavybox}
 587 \newcommand{\py@noticeend@danger}{\py@endheavybox}
 588 \newcommand{\py@noticestart@error}{\py@heavybox}
 589 \newcommand{\py@noticeend@error}{\py@endheavybox}
 590
 591 \newenvironment{notice}[2]{
 592   \def\py@noticetype{#1}
 593   \csname py@noticestart@#1\endcsname
 594   \par\strong{#2}
 595 }{\csname py@noticeend@\py@noticetype\endcsname}
 596
 597 % Allow the release number to be specified independently of the
 598 % \date{}.  This allows the date to reflect the document's date and
 599 % release to specify the release that is documented.
 600 %
 601 \newcommand{\py@release}{}
 602 \newcommand{\version}{}
 603 \newcommand{\shortversion}{}
 604 \newcommand{\releaseinfo}{}
 605 \newcommand{\releasename}{Release}
 606 \newcommand{\release}[1]{%
 607   \renewcommand{\py@release}{\releasename\space\version}%
 608   \renewcommand{\version}{#1}}
 609 \newcommand{\setshortversion}[1]{%
 610   \renewcommand{\shortversion}{#1}}
 611 \newcommand{\setreleaseinfo}[1]{%
 612   \renewcommand{\releaseinfo}{#1}}
 613
 614 % Allow specification of the author's address separately from the
 615 % author's name.  This can be used to format them differently, which
 616 % is a good thing.
 617 %
 618 \newcommand{\py@authoraddress}{}
 619 \newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
 620
 621 % This sets up the fancy chapter headings that make the documents look
 622 % at least a little better than the usual LaTeX output.
 623 %
 624 \@ifundefined{ChTitleVar}{}{
 625   \ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
 626   \ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
 627   \ChTitleVar{\raggedleft \rm\Huge\py@HeaderFamily}
 628   % This creates chapter heads without the leading \vspace*{}:
 629   \def\@makechapterhead#1{%
 630     {\parindent \z@ \raggedright \normalfont
 631       \ifnum \c@secnumdepth >\m@ne
 632         \DOCH
 633       \fi
 634       \interlinepenalty\@M
 635       \DOTI{#1}
 636     }
 637   }
 638 }
 639
 640 % Redefine description environment so that it is usable inside fulllineitems.
 641 %
 642 \renewcommand{\description}{%
 643   \list{}{\labelwidth\z@%
 644           \itemindent-\leftmargin%
 645           \labelsep5pt%
 646           \let\makelabel=\descriptionlabel}}
 647
 648 % Definition lists; requested by AMK for HOWTO documents.  Probably useful
 649 % elsewhere as well, so keep in in the general style support.
 650 %
 651 \newenvironment{definitions}{%
 652   \begin{description}%
 653   \def\term##1{\item[##1]\mbox{}\\*[0mm]}
 654 }{%
 655   \end{description}%
 656 }
 657
 658 % Tell TeX about pathological hyphenation cases:
 659 \hyphenation{Base-HTTP-Re-quest-Hand-ler}
 660
 661
 662 % The following is stuff copied from docutils' latex writer.
 663 %
 664 \newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
 665 \newenvironment{optionlist}[1]
 666 {\begin{list}{}
 667   {\setlength{\labelwidth}{#1}
 668    \setlength{\rightmargin}{1cm}
 669    \setlength{\leftmargin}{\rightmargin}
 670    \addtolength{\leftmargin}{\labelwidth}
 671    \addtolength{\leftmargin}{\labelsep}
 672    \renewcommand{\makelabel}{\optionlistlabel}}
 673 }{\end{list}}
 674
 675 \newlength{\lineblockindentation}
 676 \setlength{\lineblockindentation}{2.5em}
 677 \newenvironment{lineblock}[1]
 678 {\begin{list}{}
 679   {\setlength{\partopsep}{\parskip}
 680    \addtolength{\partopsep}{\baselineskip}
 681    \topsep0pt\itemsep0.15\baselineskip\parsep0pt
 682    \leftmargin#1}
 683  \raggedright}
 684 {\end{list}}
 685
 686 % Redefine includgraphics for avoiding images larger than the screen size
 687 % If the size is not specified.
 688 \let\py@Oldincludegraphics\includegraphics
 689
 690 \newbox\image@box%
 691 \newdimen\image@width%
 692 \renewcommand\includegraphics[2][\@empty]{%
 693   \ifx#1\@empty%
 694     \setbox\image@box=\hbox{\py@Oldincludegraphics{#2}}%
 695     \image@width\wd\image@box%
 696     \ifdim \image@width>\linewidth%
 697       \setbox\image@box=\hbox{\py@Oldincludegraphics[width=\linewidth]{#2}}%
 698       \box\image@box%
 699     \else%
 700       \py@Oldincludegraphics{#2}%
 701     \fi%
 702   \else%
 703     \py@Oldincludegraphics[#1]{#2}%
 704   \fi%
 705 }
 706
 707 % Fix the index and bibliography environments to add an entry to the Table of
 708 % Contents; this is much nicer than just having to jump to the end of the book
 709 % and flip around, especially with multiple indexes.
 710 %
 711 \let\py@OldTheindex=\theindex
 712 \renewcommand{\theindex}{
 713   \cleardoublepage
 714   \phantomsection
 715   \py@OldTheindex
 716   \addcontentsline{toc}{chapter}{\indexname}
 717 }
 718
 719 \let\py@OldThebibliography=\thebibliography
 720 \renewcommand{\thebibliography}[1]{
 721   \cleardoublepage
 722   \phantomsection
 723   \py@OldThebibliography{1}
 724   \addcontentsline{toc}{chapter}{\bibname}
 725 }
 726
 727 % Include hyperref last.
 728 \RequirePackage[colorlinks,breaklinks,
 729                 linkcolor=InnerLinkColor,filecolor=OuterLinkColor,
 730                 menucolor=OuterLinkColor,pagecolor=OuterLinkColor,
 731                 urlcolor=OuterLinkColor]{hyperref}
 732
 733 % From docutils.writers.latex2e
 734 \providecommand{\DUspan}[2]{%
 735   {% group ("span") to limit the scope of styling commands
 736     \@for\node@class@name:=#1\do{%
 737     \ifcsname docutilsrole\node@class@name\endcsname%
 738       \csname docutilsrole\node@class@name\endcsname%
 739     \fi%
 740     }%
 741     {#2}% node content
 742   }% close "span"
 743 }