% Template for a library manual section.% PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE%% Complete documentation on the extended LaTeX markup used for Python% documentation is available in ``Documenting Python'', which is part% of the standard documentation for Python.  It may be found online% at:%%     http://www.python.org/doc/current/doc/doc.html % ==== 0. ====% Copy this file to <mydir>/lib<mymodule>.tex, and edit that file% according to the instructions below.  % ==== 1. ====% The section prologue.  Give the section a title and provide some% meta-information.  References to the module should use% \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as% appropriate. \section{\module{spam} ---         Short description, for section title and table of contents} % Choose one of these to specify the module module name.  If there's% an underscore in the name, use% \declaremodule[modname]{...}{mod_name} instead.%\declaremodule{builtin}{spam}		% standard library, in C\declaremodule{standard}{spam}		% standard library, in Python\declaremodule{extension}{spam}		% not standard, in C\declaremodule{}{spam}			% not standard, in Python % Portability statement:  Uncomment and fill in the parameter to specify the% availability of the module.  The parameter can be Unix, IRIX, SunOS, Mac,% Windows, or lots of other stuff.  When ``Mac'' is specified, the availability% statement will say ``Macintosh'' and the Module Index may say ``Mac''.% Please use a name that has already been used whenever applicable.  If this% is omitted, no availability statement is produced or implied.%%   \platform{Unix} % These apply to all modules, and may be given more than once: \moduleauthor{name}{email}		% Author of the module code;					% omit if not known.\sectionauthor{name}{email}		% Author of the documentation,					% even if not a module section.  % Leave at least one blank line after this, to simplify ad-hoc tools% that are sometimes used to massage these files.\modulesynopsis{This is a one-line description, for the chapter header.}  % ==== 2. ====% Give a short overview of what the module does.% If it is platform specific, mention this.% Mention other important restrictions or general operating principles.% For example: The \module{spam} module defines operations for handling cans of Spam.It knows the four generally available Spam varieties and understandsboth can sizes. Because spamification requires \UNIX{} process management, the moduleis only available on genuine \UNIX{} systems.  % ==== 3. ====% List the public functions defined by the module.  Begin with a% standard phrase.  You may also list the exceptions and other data% items defined in the module, insofar as they are important for the% user. The \module{spam} module defines the following functions: % ---- 3.1. ----% For each function, use a ``funcdesc'' block.  This has exactly two% parameters (each parameters is contained in a set of curly braces):% the first parameter is the function name (this automatically% generates an index entry); the second parameter is the function's% argument list.  If there are no arguments, use an empty pair of% curly braces.  If there is more than one argument, separate the% arguments with backslash-comma.  Optional parts of the parameter% list are contained in \optional{...} (this generates a set of square% brackets around its parameter).  Arguments are automatically set in% italics in the parameter list.  Each argument should be mentioned at% least once in the description; each usage (even inside \code{...})% should be enclosed in \var{...}. \begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}Open the file \var{filename} as a can of Spam.  The optional\var{mode} and \var{buffersize} arguments specify the read/write mode(\code{'r'} (default) or \code{'w'}) and the buffer size (default:system dependent).\end{funcdesc} % ---- 3.2. ----% Data items are described using a ``datadesc'' block.  This has only% one parameter: the item's name. \begin{datadesc}{cansize}The default can size, in ounces.  Legal values are 7 and 12.  Thedefault varies per supermarket.  This variable should not be changedonce the \function{open()} function has been called.\end{datadesc} % --- 3.3. ---% Exceptions are described using a ``excdesc'' block.  This has only% one parameter: the exception name.  Exceptions defined as classes in% the source code should be documented using this environment, but% constructor parameters must be omitted. \begin{excdesc}{error}Exception raised when an operation fails for a Spam specific reason.The exception argument is a string describing the reason of thefailure.\end{excdesc} % ---- 3.4. ----% Other standard environments:%%  classdesc	- Python classes; same arguments are funcdesc%  methoddesc	- methods, like funcdesc but has an optional parameter %		  to give the type name: \begin{methoddesc}[mytype]{name}{args}%		  By default, the type name will be the name of the%		  last class defined using classdesc.  The type name%		  is required if the type is implemented in C (because %		  there's no classdesc) or if the class isn't directly %		  documented (if it's private).%  memberdesc	- data members, like datadesc, but with an optional%		  type name like methoddesc.  % ==== 4. ====% Now is probably a good time for a complete example.  (Alternatively,% an example giving the flavor of the module may be given before the% detailed list of functions.) \subsection{Example \label{spam-example}} The following example demonstrates how to open a can of spam using the\module{spam} module. \begin{verbatim}>>> import spam>>> can = spam.open('/etc/passwd')>>> can.empty()>>> can.close()\end{verbatim}% Note that there is no trailing ">>> " prompt shown. % ==== 5. ====% If your module defines new object types (for a built-in module) or% classes (for a module written in Python), you should list the% methods and instance variables (if any) of each type or class in a% separate subsection. \subsection{Spam Objects}\label{spam-objects}% This label is generally useful for referencing this section, but is% also used to give a filename when generating HTML. Spam objects, as returned by \function{open()} above, have thefollowing methods: \begin{methoddesc}[spam]{empty}{}Empty the can into the trash.\end{methoddesc}