diff options
Diffstat (limited to 'Doc/templates/module.tex')
-rw-r--r-- | Doc/templates/module.tex | 170 |
1 files changed, 0 insertions, 170 deletions
diff --git a/Doc/templates/module.tex b/Doc/templates/module.tex deleted file mode 100644 index 69e1b12..0000000 --- a/Doc/templates/module.tex +++ /dev/null @@ -1,170 +0,0 @@ -% 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 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 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 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} |