% epydoc-base.sty%% Authors: Jonathan Guyer <guyer@nist.gov>% Edward Loper <edloper@seas.upenn.edu>% URL: <http://epydoc.sf.net>%% This LaTeX stylesheet defines the basic commands that are used by% epydoc's latex writer (epydoc.docwriter.latex). For more% information, see the epydoc webpage. This stylesheet accepts the% following options:%% - index: Include an index of defined objects.% - hyperlink: Create hyperlinks with the hyperref package.%% $Id:$\NeedsTeXFormat{LaTeX2e}%\ProvidesClass{epydoc-base}[2008/02/26 v3.0.1 Epydoc Python Documentation]% ======================================================================% Options% These two packages are used to process options:\RequirePackage{ifthen}\RequirePackage{xkeyval}% Define an option 'index' that sets the boolean value \@doIndex\newif\if@doIndex\@doIndexfalse\DeclareOptionX{index}{\@doIndextrue}% Define an option 'hyperlink' that sets the boolean value \@docHyperlink\newif\if@doHyperlink\@doHyperlinkfalse\DeclareOptionX{hyperlink}{\@doHyperlinktrue}% Pass the 'title' & 'creator' options to the hyperref package.\DeclareOptionX{title}[]{\PassOptionsToPackage{pdftitle={#1}}{hyperref}}\DeclareOptionX{creator}[]{\PassOptionsToPackage{pdfcreator={#1}}{hyperref}}% Process the options list.\ProcessOptionsX\relax% ======================================================================% Package Requirements\RequirePackage{alltt, boxedminipage}\RequirePackage{multirow, amssymb}\RequirePackage[headings]{fullpage}\RequirePackage[usenames]{color}\RequirePackage{graphicx}\@ifclassloaded{memoir}{%\RequirePackage[other,notbib]{tocbibind} }{%\if@doIndex\RequirePackage{makeidx}\fi\RequirePackage{parskip}\RequirePackage{fancyhdr}\RequirePackage[other]{tocbibind}\pagestyle{fancy} }\if@doIndex\makeindex\fi\ifx\pdfoutput\undefined\newcommand{\driver}{dvips}\else\ifnum\pdfoutput=1\newcommand{\driver}{pdftex}\else\newcommand{\driver}{dvips}\fi\fi\RequirePackage[\driver, pagebackref, bookmarks=true, bookmarksopen=false, pdfpagemode=UseOutlines, colorlinks=true, linkcolor=black, anchorcolor=black, citecolor=black, filecolor=black, menucolor=black, pagecolor=black, urlcolor=UrlColor] {hyperref}% ======================================================================% General Formatting% Setting this will make us less likely to get overfull hboxes:%\setlength{\emergencystretch}{1in}% Separate paragraphs by a blank line (do not indent them). We define% a new length variable. \EpydocParskip, for the paragraph-skip length.% This needs to be assigned to \parskip here as well as inside several% environments that reset \parskip (such as minipages).\newlength{\EpydocParskip}\newlength{\EpydocMetadataLongListParskip}\setlength{\EpydocParskip}{0.6\baselineskip}\setlength{\EpydocMetadataLongListParskip}{0.4\baselineskip}\setlength{\parskip}{\EpydocParskip}\setlength{\parindent}{0ex}% Fix the heading position -- without this, the headings generated% by the fancyheadings package sometimes overlap the text.\setlength{\headheight}{16pt}\setlength{\headsep}{24pt}\setlength{\topmargin}{-\headsep}% Display the section & subsection names in a header.\renewcommand{\sectionmark}[1]{\markboth{#1}{}}\renewcommand{\subsectionmark}[1]{\markright{#1}}% Create a 'base class' length named EpydocBCL for use in base trees.\newlength{\EpydocBCL}% base class length, for base trees.% In xkeyval arguments, we're not allowed to use \par. But we *are*% allowed to use a command that evaluates to \par, so define such a% command.\newcommand{\EpydocPar}{\par}% ======================================================================% Sections inside docstring% The following commands are used to mark section headers within% docstrings.\newcommand\EpydocUserSection[1]{%\par\vspace{3ex}{\large\bf#1 }\par\vspace{1.4ex}}\newcommand\EpydocUserSubsection[1]{%\par\vspace{2.8ex}{\bf#1 }\par\vspace{1.2ex}}\newcommand\EpydocUserSubsubsection[1]{%\par\vspace{2.6ex}{\bf\it#1 }\par\vspace{1.0ex}}% ======================================================================% Hyperlinks & Crossreferences% The \EpydocHypertarget command is used to mark targets that hyperlinks% may point to. It takes two arguments: a target label, and text% contents. (In some cases, the text contents will be empty.) Target% labels are formed by replacing '.'s in the name with ':'s. The% default stylesheet creates a \label for the target label, and displays% the text.\newcommand{\EpydocHypertarget}[2]{\label{#1}#2}% The \EpydocHyperlink command is used to create a link to a given target.% It takes two arguments: a target label, and text contents. The% default stylesheet just displays the text contents.\newcommand{\EpydocHyperlink}[2]{#2}% The \CrossRef command creates a cross-reference to a given target,% including a pageref. It takes one argument, a target label.\newcommand{\CrossRef}[1]{\textit{(Section\ref{#1}, p.~\pageref{#1})}}% If the [hyperlink] option is turned on, then enable hyperlinking.\if@doHyperlink\renewcommand{\EpydocHyperlink}[2]{\hyperlink{#1}{#2}}\renewcommand{\EpydocHypertarget}[2]{\label{#1}\hypertarget{#1}{#2}}\fi% ======================================================================% Index Terms% The \EpydocIndex command is used to mark items that should be included% in the index. It takes three arguments. The first argument is the% item's case-normalized name; this is typically discarded, and is% simply used to ensure the proper (i.e., case-insensitive) sort order% in the index. The second argument is the item's name; and the% third item is the item's "kind". "kind" can be Package, Script, Module,% Class, Class Method, Static Method, Method, Function, or Variable.% This command is used inside of the \index{...} command.\newcommand{\EpydocIndex}[3]{%#2%\ifthenelse{\equal{#3}{}}{}{\textit{(#3)}}}% ======================================================================% Descriptions (docstring contents)% All rendered markup derived from a docstring is wrapped in this% environment. By default, it simply sets the \parskip length% to \EpydocParskip (in case an enclosing environment had reset% it to its default value).\newenvironment{EpydocDescription}{%\setlength{\parskip}{\EpydocParskip}%\ignorespaces}{\ignorespacesafterend}% This environment is used to mark the description for a class% (which comes from the function's docstring).\newenvironment{EpydocClassDescription}{%\ignorespaces}{\ignorespacesafterend}% This environment is used to mark the description for a module% (which comes from the function's docstring).\newenvironment{EpydocModuleDescription}{%\ignorespaces}{\ignorespacesafterend}% ======================================================================% Python Source Code Syntax Highlighting.% Color constants.\definecolor{py@keywordcolor}{rgb}{1,0.45882,0}\definecolor{py@stringcolor}{rgb}{0,0.666666,0}\definecolor{py@commentcolor}{rgb}{1,0,0}\definecolor{py@ps1color}{rgb}{0.60784,0,0}\definecolor{py@ps2color}{rgb}{0.60784,0,1}\definecolor{py@inputcolor}{rgb}{0,0,0}\definecolor{py@outputcolor}{rgb}{0,0,1}\definecolor{py@exceptcolor}{rgb}{1,0,0}\definecolor{py@defnamecolor}{rgb}{1,0.5,0.5}\definecolor{py@builtincolor}{rgb}{0.58039,0,0.58039}\definecolor{py@identifiercolor}{rgb}{0,0,0}\definecolor{py@linenumcolor}{rgb}{0.4,0.4,0.4}\definecolor{py@inputcolor}{rgb}{0,0,0}% Syntax Highlighting Commands\newcommand{\pysrcprompt}[1]{\textcolor{py@ps1color}{\small\textbf{#1}}}\newcommand{\pysrcmore}[1]{\textcolor{py@ps2color}{\small\textbf{#1}}}\newcommand{\pysrckeyword}[1]{\textcolor{py@keywordcolor}{\small\textbf{#1}}}\newcommand{\pysrcbuiltin}[1]{\textcolor{py@builtincolor}{\small\textbf{#1}}}\newcommand{\pysrcstring}[1]{\textcolor{py@stringcolor}{\small\textbf{#1}}}\newcommand{\pysrcdefname}[1]{\textcolor{py@defnamecolor}{\small\textbf{#1}}}\newcommand{\pysrcother}[1]{\small\textbf{#1}}\newcommand{\pysrccomment}[1]{\textcolor{py@commentcolor}{\small\textbf{#1}}}\newcommand{\pysrcoutput}[1]{\textcolor{py@outputcolor}{\small\textbf{#1}}}\newcommand{\pysrcexcept}[1]{\textcolor{py@exceptcolor}{\small\textbf{#1}}}% ======================================================================% Grouping% This command is used to display group headers for objects that are in% the same group (as specified by the epydoc @group field). It is used% within the Epydoc*List environments. The definition provided here is% the default definition, but several of the Epydoc*List environments% use \renewcommand to provide definitions that are appropriate for the% style of that environment.\newcommand{\EpydocGroup}[1]{\par{\large#1}\par}% ======================================================================% Inheritance% This command is used to display a list of objects that were inherited% from a base class. It expects two arguments: the base class name,% and the list of inherited objects. The definition provided here is% the default definition, but several of the Epydoc*List environments% use \renewcommand to provide definitions that are appropriate for the% style of that environment.\newcommand{\EpydocInheritanceList}[2]{%\textbf{Inherited from {#1}:} #2\par}% ======================================================================% Submodule List% This list environment is used to list the submodules that are defined% by a module. Nested submodules are displayed using nested% EpydocModuleList environments. If the modules are divided into% groups (with the epydoc @group field), then groups are displayed% using the \EpydocGroup command.\newenvironment{EpydocModuleList}{%\renewcommand{\EpydocGroup}[1]{%\vspace{\EpydocParskip}\item[]\hspace{-\labelwidth}%\textbf{\large##1}}%\begin{itemize}%\setlength{\parskip}{0ex}}%{\end{itemize}}% Usage: \EpydocModule{name={...}, summary={...}, crossref={...}}\define@cmdkeys[Epydoc]{module}{name,summary,crossref}\newcommand{\EpydocModule}[1]{{%\setkeys[Epydoc]{module}{#1}%\item\textbf{\cmdEpydoc@module@name}:%\@ifundefined{cmdEpydoc@module@summary}{}{%\\cmdEpydoc@module@summary}%\@ifundefined{cmdEpydoc@module@crossref}{}{%\\cmdEpydoc@module@crossref}}}% ======================================================================% Class List%% These environments are *only* used if the --list-classes-separately% option is used.% This list environment is used to list the classes that are defined% by a module.\newenvironment{EpydocClassList}{%\renewcommand{\EpydocGroup}[1]{%\vspace{\EpydocParskip}\item[]\hspace{-\labelwidth}%\textbf{\large##1}}%\begin{itemize}%\setlength{\parskip}{0ex}}%{\end{itemize}}% Usage: \EpydocClass{name={...}, summary={...}, crossref={...}}\define@cmdkeys[Epydoc]{class}{name,summary,crossref}\newcommand{\EpydocClass}[1]{{%\setkeys[Epydoc]{class}{#1}%\item\textbf{\cmdEpydoc@class@name}:%\@ifundefined{cmdEpydoc@class@summary}{}{%\\cmdEpydoc@class@summary}%\@ifundefined{cmdEpydoc@class@crossref}{}{%\\cmdEpydoc@class@crossref}}}% ======================================================================% Function Lists% The EpydocFunctionList environment is used to describe functions% and methods. It contains one \EpydocFunction command for each% function or method. This command takes eight required arguments:%% - The function's signature: an EpydocFunctionSignature environment% specifying the signature for the function.%% - The function's description (from the docstring)%% - The function's parameters: An EpydocFunctionParameters list% environment providing descriptions of the function's parameters.% (from the epydoc @param, @arg, @kwarg, @vararg, @type fields)%% - The function's return description (from the epydoc @rerturns field)%% - The function's return type (from the epydoc @rtype field)%% - The function's exceptions: An EpydocFunctionRaises list% environment describing exceptions that the function may raise% (from the epydoc @raises field)%% - The function's override: An EpydocFunctionOverrides command% describing the method that this function overrides (if any)%% - The function's metadata: Zero or more EpydocMetadata*% commands/environments, taken from metadata fields (eg @author)%% All arguments except for the first (the signature) may be empty.%\define@cmdkeys[Epydoc]{function}{signature,description,parameters, returndescr,returntype,raises, overrides,metadata}\newenvironment{EpydocFunctionList}{%\newcommand{\EpydocFunction}[1]{{%\setkeys[Epydoc]{function}{##1}%{\Large\raggedright\cmdEpydoc@function@signature\par}\begin{quote}%\setlength{\parskip}{\EpydocParskip}%\@ifundefined{cmdEpydoc@function@description}{}{\par\cmdEpydoc@function@description}\@ifundefined{cmdEpydoc@function@parameters}{}{\par\cmdEpydoc@function@parameters}\@ifundefined{cmdEpydoc@function@returndescr}{}{\par\textbf{Returns:}\cmdEpydoc@function@returndescr}\@ifundefined{cmdEpydoc@function@returntype}{}{\par\textbf{Return Type:}\cmdEpydoc@function@returntype}\@ifundefined{cmdEpydoc@function@raises}{}{\par\cmdEpydoc@function@raises}\@ifundefined{cmdEpydoc@function@overrides}{}{\par\cmdEpydoc@function@overrides}\@ifundefined{cmdEpydoc@function@metadata}{}{\ifx\cmdEpydoc@function@metadata\empty\else\par\cmdEpydoc@function@metadata\fi}\end{quote}\par}}} {}% The EpydocFunctionSignature environment is used to display a% function's signature. It expects one argument, the function's% name. The body of the environment contains the parameter list.% The following commands are used in the parameter list, to mark% individual parameters:%% - \Param: Takes one required argument (the parameter name) and% one optional argument (the defaultt value).% - \VarArg: Takes one argument (the varargs parameter name)% - \KWArg: Takes one argument (the keyword parameter name)% - \GenericArg: Takes no arguments (this is used for '...', e.g.% when the signature is unknown).% - \TupleArg: Used inside of the \Param command, to mark% argument tuples. Individual elements of the argument tuple% are separated by the \and command.%% Parameters are separated by the \and command.\newenvironment{EpydocFunctionSignature}[1]{%\newcommand{\and}{, }%\newcommand{\VarArg}[1]{*\textit{##1}}%\newcommand{\GenericArg}{\textit{\ldots}}%\newcommand{\KWArg}[1]{**\textit{##1}}%\newcommand{\TupleArg}[1]{(##1)}%\newcommand{\Param}[2][]{%\textit{##2}%\ifthenelse{\equal{##1}{}}{}{=\texttt{##1}}}%\@hangfrom{\textbf{#1}(}%}{)}% The EpydocFunctionParameters environment is used to display% descriptions for the parameters that a function can take.% (From epydoc fields: @param, @arg, @kwarg, @vararg, @type)\newenvironment{EpydocFunctionParameters}[1]{%\textbf{Parameters}\vspace{-\EpydocParskip}\begin{quote}\begin{list}{}{%\renewcommand{\makelabel}[1]{\texttt{##1:}\hfil}%\settowidth{\labelwidth}{\texttt{#1:}}%\setlength{\leftmargin}{\labelsep}%\addtolength{\leftmargin}{\labelwidth}}}%{\end{list}\end{quote} }% This environment is used to display descriptions of exceptions% that can be raised by a function. (From epydoc field: @raise)\newenvironment{EpydocFunctionRaises}{%\renewcommand*{\descriptionlabel}[1]{\hspace\labelsep\normalfont\itshape##1}\textbf{Raises}\vspace{-\EpydocParskip}%\begin{quote}%\begin{description}%} {\end{description}\end{quote} }% This environment is used when a method overrides a base class% method, to display the name of the overridden method.\newcommand{\EpydocFunctionOverrides}[2][0]{%\textbf{Overrides:} #2%\ifthenelse{#1=1}{\textit{(inherited documentation)}{}}\par}% ======================================================================% Variable Lists%% There are three separate variable list environments:% - EpydocVariableList............ for a module's variables% - EpydocInstanceVariableList.... for a class's instance variables% - EpydocClassVariableList....... for a class's class variables% The EpydocVariableList environment is used to describe module% variables. It contains one \EpydocVariable command for each% variable. This command takes four required arguments:%% - The variable's name% - The variable's description (from the docstring)% - The variable's type (from the epydoc @type field)% - The variable's value%% If any of these arguments is not available, then the empty% string will be used.\define@cmdkeys[Epydoc]{variable}{name,description,type,value,metadata}\newenvironment{EpydocVariableList}{%\newcommand{\EpydocVariable}[1]{{%\setkeys[Epydoc]{variable}{##1}%{\Large\raggedright\cmdEpydoc@variable@name\par}\begin{quote}\setlength{\parskip}{\EpydocParskip}%\@ifundefined{cmdEpydoc@variable@description}{}{%\par\cmdEpydoc@variable@description}%\@ifundefined{cmdEpydoc@variable@type}{}{%\par\textbf{Type:}\cmdEpydoc@variable@type}%\@ifundefined{cmdEpydoc@variable@value}{}{%\par\textbf{Value:}\cmdEpydoc@variable@value}%\@ifundefined{cmdEpydoc@variable@metadata}{}{%\ifx\cmdEpydoc@variable@metadata\empty\else\par\cmdEpydoc@variable@metadata\fi}%\end{quote}\par}}} {}% The EpydocClassVariableList environment is used the same way as% the EpydocVariableList environment (shown above).\newenvironment{EpydocClassVariableList}{%\begin{EpydocVariableList}} {\end{EpydocVariableList}}% The EpydocClassVariableList environment is used the same way as% the EpydocVariableList environment (shown above).\newenvironment{EpydocInstanceVariableList}{%\begin{EpydocVariableList}} {\end{EpydocVariableList}}% ======================================================================% Property Lists% The EpydocPropertyList environment is used to describe class% properties. It contains one \EpydocProperty command for each% property. This command takes six required arguments:%% - The property's name% - The property's description (from the docstring)% - The property's type (from the epydoc @type field)% - The property's fget function% - The property's fset function% - The property's fdel function%% If any of these arguments is not available, then the empty% string will be used.\define@cmdkeys[Epydoc]{property}{name,description,type,fget, fset,fdel,metadata}\newenvironment{EpydocPropertyList}{%\newcommand{\EpydocProperty}[1]{{%\setkeys[Epydoc]{property}{##1}%{\Large\raggedright\cmdEpydoc@property@name\par}\begin{quote}\setlength{\parskip}{\EpydocParskip}%\@ifundefined{cmdEpydoc@property@description}{}{\par\cmdEpydoc@property@description}\@ifundefined{cmdEpydoc@property@type}{}{\par\textbf{Type:}\cmdEpydoc@property@type}\@ifundefined{cmdEpydoc@property@fget}{}{\par\textbf{Get:}\cmdEpydoc@property@fget}\@ifundefined{cmdEpydoc@property@fset}{}{\par\textbf{Set:}\cmdEpydoc@property@fset}\@ifundefined{cmdEpydoc@property@fdel}{}{\par\textbf{Delete:}\cmdEpydoc@property@fdel}\@ifundefined{cmdEpydoc@property@metadata}{}{\ifx\cmdEpydoc@property@metadata\empty\else\par\cmdEpydoc@property@metadata\fi}\end{quote}\par}}} {}% ======================================================================% Metadata% This command is used to display a metadata field with a single value\newcommand{\EpydocMetadataSingleValue}[2]{%\par\begin{list}{}{\itemindent-\leftmargin}\item\textbf{#1:} #2\end{list}\par\ignorespaces}% This environment is used to display a metadata field with multiple% values when the field declares that short=True; i.e., that multiple% values should be combined into a single comma-delimited list.\newenvironment{EpydocMetadataShortList}[1]{%\newcommand{\and}{, }%\par\begin{list}{}{\itemindent-\leftmargin}\item\textbf{#1:}\ignorespaces} {\end{list}\ignorespacesafterend\par}% This list environment is used to display a metadata field with% multiple values when the field declares that short=False; i.e., that% multiple values should be listed separately in a bulleted list.\newenvironment{EpydocMetadataLongList}[1]{%\par\textbf{#1:}\setlength{\parskip}{0ex}\begin{itemize}\setlength{\parskip}{\EpydocMetadataLongListParskip}\ignorespaces} {\end{itemize}\ignorespacesafterend\par}% ======================================================================% reStructuredText Admonitions% This environment is used to display reStructuredText admonitions,% such as ``..warning::'' and ``..note::''.\newenvironment{reSTadmonition}[1][]{%\begin{center}\begin{sffamily}%\begin{lrbox}{\@tempboxa}%\begin{minipage}{\admonitionwidth}%\textbf{\large#1}%\vspace{2mm}}%{\end{minipage}%\end{lrbox}%\fbox{\usebox{\@tempboxa}}%\end{sffamily}%\end{center}}% ======================================================================% Name Formatting%% This section defines the EpydocDottedName command, which is used to% display the names of Python objects.% The \EpydocDottedName command adds a possible break-point after every% period in the given string. It no longer escapes characters such as% underscore, since this interfered with the hyperref package; instead,% epydoc is responsible for escaping them. E.g., correct usage for a% name with an underscore is \EpydocDottedName{some\_name}.\newcommand\EpydocDottedName[1]{\Epydoc@DottedName #1.@}% This helper function performs the work of \EpydocDottedName. It% scans forward, looking for a period, and putting all text up to the% period into #1. The single character after the period is put in% #2. This function then checks if #2 is '@', indicating that we're% done, or some other character, indicating that we should continue.% Note that \ifx tests character codes; and that when '@' appears% in user code, it gets the character code 'other', but when it% appears here, it gets the character code 'letter'.\def\Epydoc@DottedName#1.#2{%\ifx#2@\relax#1\else#1\discretionary{.}{}{.}%\expandafter\expandafter\expandafter\Epydoc@DottedName\expandafter#2\fi%}% This style file is a derivative work, based on a public domain style% file that was originally developed at the National Institute of% Standards and Technology by employees of the Federal Government in the% course of their official duties. NIST assumes no responsibility% whatsoever for its use by other parties, and makes no guarantees,% expressed or implied, about its quality, reliability, or any other% characteristic.
| Home | Installing Epydoc | Using Epydoc | Epytext |
|