% 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 descrition, 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 understands both can sizes. Because spamification requires \UNIX{} process management, the module is 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. The default varies per supermarket. This variable should not be changed once 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 ommitted. \begin{excdesc}{error} Exception raised when an operation fails for a Spam specific reason. The exception argument is a string describing the reason of the failure. \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 the following methods: \begin{methoddesc}[spam]{empty}{} Empty the can into the trash. \end{methoddesc}