% epydoc -- Demo & description of latex writer output%% Copyright (C) 2008 Edward Loper% Author: Edward Loper <edloper@loper.org>% URL: <http://epydoc.sf.net>%% $Id: apidoc.py 1729 2008-02-19 16:49:16Z edloper $% This is the basic preamble that's always included (in the api.tex file).% If any reStructuredText docstrings are used, then it is extended using% the preamble material used by reStructuredText.\documentclass{article}\usepackage[index]{epydoc}\usepackage[utf8]{inputenc}\definecolor{UrlColor}{rgb}{0,0.08,0.45}\usepackage[pdftex, pagebackref, pdftitle={API Documentation},%pdfcreator={epydoc 3.0.1}, bookmarks=true, bookmarksopen=false,%pdfpagemode=UseOutlines, colorlinks=true, linkcolor=black,%anchorcolor=black, citecolor=black, filecolor=black, menucolor=black,%pagecolor=black, urlcolor=UrlColor]{hyperref}\begin{document}\title{Epydoc LaTeX Writer Output Demo}\author{}\date{}\maketitleThis file provides a demonstration and description of epydoc's LaTeX output. Most of the important information is in the comments, so you should read this file in its original form (and not as a rendered pdf). By looking at this file, and at the epydoc-default.sty file, you should be able to determine how to write your own customized style file.% ======================================================================\section{General Formatting}\subsection{Hyperlinks and Crossreferences}% The \EpydocDottedName command is used to escape dotted names. In% particular, it escapes underscores (_) and allows non-hyphenated% wrapping at '.' separator characters.\EpydocDottedName{my_module.Zip}% 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.\EpydocHypertarget{foo:bar:baz}{\EpydocDottedName{foo.bar.baz}}% 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.\EpydocHyperlink{foo:bar:baz}{\EpydocDottedName{foo.bar.baz}}% The \CrossRef command creates a cross-reference to a given target,% including a pageref. It takes one argument, a target label.\CrossRef{foo:bar:baz}\subsection{Indexing}% 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.%% For modules and classes, the \index formatting strings "|(" and% "|)" are appended to mark the beginning and end of the object's% documentation. For methods, variables, and nested classes, the% index formatting string "!" is used to create nested index entries.% See the docs for the latex \index command for more information.\index{\EpydocIndex{mymodule}{mymodule}{module}|(}\index{\EpydocIndex{foo}{Foo}{class}|(}\index{\EpydocIndex{foo}{Foo}{class}!\EpydocIndex{foo.f}{Foo.f}{method}}\index{\EpydocIndex{foo}{Foo}{class}!\EpydocIndex{foo.f}{Foo.g}{method}}\index{\EpydocIndex{foo}{Foo}{class}|)}\index{\EpydocIndex{mymodule}{mymodule}{module}|)}\subsection{Source Code Syntax Highlighting}% Doctest blocks are colorized using a variety of commands, all beginning% with the prefix "\pysrc". See epydoc-default.sty for a full list.\begin{alltt}\pysrcprompt{{\textgreater}{\textgreater}{\textgreater} }f(x)\pysrcoutput{123}\end{alltt}\subsection{reStructuredText Admonitions}% These would be defined by rst's style file:\newlength{\admonitionwidth}\setlength{\admonitionwidth}{.8\textwidth}% The reSTadmonition environment is used to display reStructuredText% admonitions, such as ``..warning::'' and ``..note::''. It takes% one optional argument, the admonition type.\begin{reSTadmonition}[note] This is a note.\end{reSTadmonition}\subsubsection{Sections inside Docstrings}% The commands \EpydocUserSection, \EpydocUserSubsection, and% \EpydocUserSubsubsection are used to add section headings inside% of docstrings\EpydocUserSection{Intra-docstring heading 1}\EpydocUserSubsection{Intra-docstring heading 2}\EpydocUserSubsubsection{Intra-docstring heading 3}% ======================================================================% Each module is listed in its own section. (These sections are created% as separate files, and \include-ed into the main api.tex file). The% section contains:% - The module description (from the module's docstring)% - A metadata section (author, version, warnings, etc)% - A list of submodules (if it's a package)% - A list of classes defined by the module (only if the% --list-classes-separately option is used).% - A subsection describing the functions defined by the module.% - A subsection describing the variables defined by the module.% - A subsection for each class defined by the module (only if% the --list-classes-separately option is *not* used).\section{my\_module}% The EpydocModuleDescription environment is used to mark the% module's description (from its docstring)\begin{EpydocModuleDescription} This is an example module, used to demonstrate the LaTeX commands and environments used by epydoc.\end{EpydocModuleDescription}% Each metadata item is listed separately. There are three environments% and commands used for metadata:% - The \EpydocMetadataSingleValue command is used to display a metadata% field with a single value. It takes two arguments: the metadata% field name and the metadata description.% - The \EpydocMetadataShortList 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. It takes one argument (the metadata% field name); and items should be separated by the \and command.% - The \EpydocMetadataLongList 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. It takes one argument (the metadata% field name); and items should marked wit hthe \item command.\EpydocMetadataSingleValue{See Also}{some reference.}\begin{EpydocMetadataShortList}{Author} joe\andmary\end{EpydocMetadataShortList}\begin{EpydocMetadataLongList}{Notes}\itemThis is one note.\itemThis is a second note.\end{EpydocMetadataLongList}% The list of submodules that a package contains is put it its own% subsection. The list is displayed using the EpydocModuleList% environment. 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, followed by a nested EpydocModuleList.\subsection{Submodules}\begin{EpydocModuleList}\item[\EpydocHyperlink{my_module:foo}{\EpydocDottedName{my_module.foo}}] Description of my\_module.foo.\item[\EpydocHyperlink{my_module:bar}{\EpydocDottedName{my_module.bar}}] Description of my\_module.bar.\begin{EpydocModuleList}\item[\EpydocHyperlink{my_module:bar:soap} {\EpydocDottedName{my_module.bar.soap}}] Description of my\_module.bar.soap.\end{EpydocModuleList}\EpydocGroup{Some Group}\begin{EpydocModuleList}\item[\EpydocHyperlink{my_module:baz} {\EpydocDottedName{my_module.baz}}] Description of my\_module.baz.\end{EpydocModuleList}\end{EpydocModuleList}% The list of classes that a module contains is just like the list% of submodules that a package contains, except that the list% environment EpydocClassList and the command \EpydocGroup% are used. (Note that this list is only included when the% --list-classes-separately option is used.)\subsection{Classes}\begin{EpydocClassList}\item[\EpydocHyperlink{my_module:Zip} {\EpydocDottedName{my_module.Zip}}] Description of my\_module.Zip.\item[\EpydocHyperlink{my_module:Zap} {\EpydocDottedName{my_module.Zap}}] Description of my\_module.Zap.\EpydocGroup{Some Group}\begin{EpydocClassList}\item[\EpydocHyperlink{my_module:Zam} {\EpydocDottedName{my_module.Zam}}] Description of my\_module.Zam.\item[\EpydocHyperlink{my_module:Zam} {\EpydocDottedName{my_module.Zam}}] Description of my\_module.Zam.\end{EpydocClassList}\end{EpydocClassList}% The functions that a module contains are listed in a separate% subsection. This subsection contains a single EpydocFunctionList% environment\subsection{Functions}% The EpydocFunctionList environment is used to display functions.% It contains one \EpydocFunction command for each function. This% command takes 8 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.%\begin{EpydocFunctionList}\EpydocFunction{% Argument 1: The function signature%% The EpydocFunctionSignature is used to display a function's% signature. It expects one argument, the function's name. The% body of the environment containd 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.\begin{EpydocFunctionSignature}{myfunc}%\Param{x}%\and\Param{y}%\and\Param{i}%\and\Param{j}%\and\Param{\TupleArg{a\andb}}%\and\VarArg{rest},\KWArg{keywords}%\end{EpydocFunctionSignature} }{% Argument 2: The function descriptionThis is an example function. }{% Argument 3: The function parameter descriptions%% The EpydocFunctionParameters list environment is used to% describe the function's parameters. It takes a single% required argument, a string which can be used to set the% label width for the list. (I.e., this string is as long% as the longest parameter name.) The list contains one% \item for each parameter description. Parameter types% are currently listed as part of the text (not using any% special environments or commands)\begin{EpydocFunctionParameters}{xxxxxxxx}\item[x] Description of parameter x. (type=int)\item[i, j] Description of parameters x and y.\item[keywords] Description of the keywords parameter.\end{EpydocFunctionParameters} }{% Argument 4: The function return value descriptiondescription of the return value }{% Argument 5: The function return value tupeint }{% Argument 6: The function exception descriptions%% The EpydocRaises list environment is used to display the% list of exceptions that the function may raise. The list% contains one \item for each exception.\begin{EpydocFunctionRaises}\item[ValueError] If there's some problem with a value.\item[TypeError] If the wrong type is given.\end{EpydocFunctionRaises} }{% Argument 7: The function overrides command%% (this is only used for methods, not functions)}{% Argument 8: The function metadta%% The metadata section uses the same commands that the module-% level metadata section uses; see the discussion above.\EpydocMetadataSingleValue{See Also}{some reference.}\begin{EpydocMetadataShortList}{Author} joe\andmary\end{EpydocMetadataShortList}\begin{EpydocMetadataLongList}{Notes}\itemThis is one note.\itemThis is a second note.\end{EpydocMetadataLongList} }% If functions are divided into groups (with the epydoc @group% field), then group headers are marked with the \EpydocGropu% command.\EpydocGroup{Some Group}\EpydocFunction{\begin{EpydocFunctionSignature}{\EpydocDottedName{some_func}}\Param{x}\and\Param{y}\and\Param{z}\end{EpydocFunctionSignature}} {}{}{}{}{}{}{}\end{EpydocFunctionList}% The variables that a module contains are listed in a separate% subsection. This section contains a single EpydocVariableList% environment\subsection{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.%% If the variables are divided into groups (with the epydoc @group% field), then the \EpydocInternalHeader command is used to mark% the beginning of each variable group.\begin{EpydocVariableList}\EpydocVariable{\EpydocHyperlink{my_module:gorp} {\EpydocDottedName{my_module.gorp}}} {Description of the variable gorp} {int} {12}\EpydocVariable{\EpydocHyperlink{my_module:moo} {\EpydocDottedName{my_module.moo}}} {Description of the variable moo} {str} {'hello'}\EpydocVariable{\EpydocHyperlink{my_module:cow} {\EpydocDottedName{my_module.cow}}} {}% no description{}% no type{}% no value\end{EpydocVariableList}% The remaineder of the module's section consists of one subsection% for each class defined by the module. (However, if the% --list-classes-separately option is used, then these subsections% are not generated; instead, epydoc will generate a separate% top-level section for each class.) Each class section contains:% - The class's base tree (or a class tree graph, if the options% "--graph classtree" or "--graph umlclasstree" are used).% - A list of known subclasses.% - The class description (from the class's docstring)% - A metadata section (author, version, warnings, etc)% - A list of methods defined by the class% - A list of properties defined by the class% - A list of class variables defined by the class% - A list of instance variables defined by the class\subsection{Class\EpydocDottedName{Zip}}% The base tree is 'drawn' using a carefully constructed tabular% environment. Here's an example of what it can look like:\begin{tabular}{cccccc}\multicolumn{2}{r}{\settowidth{\EpydocBCL}{\EpydocDottedName{MyBaseClass}}\multirow{2}{\EpydocBCL}{\EpydocHyperlink{object} {\EpydocDottedName{MyBaseClass}}}} &&\\\cline{3-3} &&\multicolumn{1}{c|}{} &&\\&&\multicolumn{2}{l}{\textbf{\EpydocDottedName{my_module.Zip}}}\end{tabular}% The known subclasses are displayed using an \EpydocMetadataSingleValue% command or an \EpydocMetadataShortList environment. See the% description of these above (for module metadata).\begin{EpydocMetadataShortList}{Known Subclasses}\EpydocHyperlink{my_module:Zap}{\EpydocDottedName{my_module.zap}}\and\EpydocHyperlink{my_module:Zam}{\EpydocDottedName{my_module.zam}}\end{EpydocMetadataShortList}% The EpydocClassDescription environment is used to mark the% class's description (from its docstring)\begin{EpydocClassDescription} This is an example class, used to demonstrate the LaTeX commands and environments used by epydoc.\end{EpydocClassDescription}% The metadata section uses the same commands that the module-% level metadata section uses; see the discussion above.\EpydocMetadataSingleValue{See Also}{some reference.}\begin{EpydocMetadataShortList}{Author} joe\andmary\end{EpydocMetadataShortList}% The methods that a class defines are listed in a separate% subsubsection. This subsubsection contains a single% EpydocFunctionList environment.\subsubsection{Methods}% The EpydocFunction environment was described above (when it was% used with module-level functions.) The only difference here is% that functions may optionally include a command specifying% what method is overridden by this method (\EpydocFunctionOverrides)% as the seventh argument to the \EpydocFunction command.\begin{EpydocFunctionList}\EpydocFunction{\begin{EpydocFunctionSignature}{mymethod}\Param{x}\and\Param{y}\end{EpydocFunctionSignature}} {This is an example function.} {}{}{}{} {% The \EpydocFunctionOverrides command specifies which method% was overridden by this method. It comes just before the% metadata section. It takes one optional argument, which will% be "1" if documentation was inherited from the overridden% method; and one required argument, containing the name of% the overridden method.\EpydocFunctionOverrides[1]{\EpydocHyperlink{MyBaseClass:mymethod} {\EpydocDottedName{MyBaseClass.mymethod}}} }{}\end{EpydocFunctionList}% The properties that a class defines are listed in a separate% subsection. This section contains a single EpydocPropertyList% environment.\subsubsection{Properties}% 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.%% If the properties are divided into groups (with the epydoc @group% field), then the \EpydocInternalHeader command is used to mark% the beginning of each property group.%% If any properties are inherited from a base class, and if% --inheritance=listed (the default), then they will be listed% after all the other properties, using the% \EpydocInheritanceList command. This command will be used% once for each base class that properties are inherited from.% It takes two arguments: the name of the base class that the% properties were inherited from, and a list of property names.\begin{EpydocPropertyList}\EpydocProperty{\EpydocHyperlink{my_module:Zip:duck} {\EpydocDottedName{duck}}} {Description of the property duck} {int} {\EpydocDottedName{get_dock}} {\EpydocDottedName{set_dock}} {\EpydocDottedName{del_dock}}\EpydocInheritanceList{MyBaseClass}{goose, pig}\end{EpydocPropertyList}% The class variabless that a class defines are listed in a% separate subsection. This section contains a single% EpydocClassVariableList environment.\subsubsection{Class Variables}% The EpydocClassVariableList environment is used the same way as% the EpydocVariableList environment (shown above), with one% exception: if any variables are inherited from a base class,% and if--inheritance=listed (the default), then they will be% listed after all the other properties, using the% \EpydocInheritanceList command. This command will be used% once for each base class that variabless are inherited from.% It takes two arguments: the name of the base class that the% properties were inherited from, and a list of property names.\begin{EpydocClassVariableList}\EpydocVariable{\EpydocHyperlink{my_module:Zip:quack} {\EpydocDottedName{my_module.Zip.quack}}} {Description of the class variable quack} {str}% type{}% no value\EpydocInheritanceList{MyBaseClass}{oink, bark}\end{EpydocClassVariableList}% The instance variabless that a instance defines are listed in a% separate subsection. This section contains a single% EpydocInstanceVariableList environment.\subsubsection{Instance Variables}% The EpydocInstanceVariableList environment is used the same% way as the EpydocClassVariableList environment (shown above).\begin{EpydocClassVariableList}\EpydocVariable{\EpydocHyperlink{my_module:Zip:florp} {\EpydocDottedName{my_module.Zip.flrop}}} {Description of the class variable florp} {list}% type{}% no value\EpydocInheritanceList{MyBaseClass}{blorp}\end{EpydocClassVariableList}% That's all, folks!\end{document}
| Home | Installing Epydoc | Using Epydoc | Epytext |
|