Doc/templates/module.tex

   1 % Template for a library manual section.
   2 % PLEASE REMOVE THE COMMENTS AFTER USING THE TEMPLATE
   3 %
   4 % Complete documentation on the extended LaTeX markup used for Python
   5 % documentation is available in ``Documenting Python'', which is part
   6 % of the standard documentation for Python.  It may be found online
   7 % at:
   8 %
   9 %     http://www.python.org/doc/current/doc/doc.html
  10
  11 % ==== 0. ====
  12 % Copy this file to <mydir>/lib<mymodule>.tex, and edit that file
  13 % according to the instructions below.
  14
  15
  16 % ==== 1. ====
  17 % The section prologue.  Give the section a title and provide some
  18 % meta-information.  References to the module should use
  19 % \refbimodindex, \refstmodindex, \refexmodindex or \refmodindex, as
  20 % appropriate.
  21
  22 \section{\module{spam} ---
  23          Short description, for section title and table of contents}
  24
  25 % Choose one of these to specify the module module name.  If there's
  26 % an underscore in the name, use
  27 % \declaremodule[modname]{...}{mod_name} instead.
  28 %
  29 \declaremodule{builtin}{spam}           % standard library, in C
  30 \declaremodule{standard}{spam}          % standard library, in Python
  31 \declaremodule{extension}{spam}         % not standard, in C
  32 \declaremodule{}{spam}                  % not standard, in Python
  33
  34 % Portability statement:  Uncomment and fill in the parameter to specify the
  35 % availability of the module.  The parameter can be Unix, IRIX, SunOS, Mac,
  36 % Windows, or lots of other stuff.  When ``Mac'' is specified, the availability
  37 % statement will say ``Macintosh'' and the Module Index may say ``Mac''.
  38 % Please use a name that has already been used whenever applicable.  If this
  39 % is omitted, no availability statement is produced or implied.
  40 %
  41 %   \platform{Unix}
  42
  43 % These apply to all modules, and may be given more than once:
  44
  45 \moduleauthor{name}{email}              % Author of the module code;
  46                                         % omit if not known.
  47 \sectionauthor{name}{email}             % Author of the documentation,
  48                                         % even if not a module section.
  49
  50
  51 % Leave at least one blank line after this, to simplify ad-hoc tools
  52 % that are sometimes used to massage these files.
  53 \modulesynopsis{This is a one-line descrition, for the chapter header.}
  54
  55
  56 % ==== 2. ====
  57 % Give a short overview of what the module does.
  58 % If it is platform specific, mention this.
  59 % Mention other important restrictions or general operating principles.
  60 % For example:
  61
  62 The \module{spam} module defines operations for handling cans of Spam.
  63 It knows the four generally available Spam varieties and understands
  64 both can sizes.
  65
  66 Because spamification requires \UNIX{} process management, the module
  67 is only available on genuine \UNIX{} systems.
  68
  69
  70 % ==== 3. ====
  71 % List the public functions defined by the module.  Begin with a
  72 % standard phrase.  You may also list the exceptions and other data
  73 % items defined in the module, insofar as they are important for the
  74 % user.
  75
  76 The \module{spam} module defines the following functions:
  77
  78 % ---- 3.1. ----
  79 % For each function, use a ``funcdesc'' block.  This has exactly two
  80 % parameters (each parameters is contained in a set of curly braces):
  81 % the first parameter is the function name (this automatically
  82 % generates an index entry); the second parameter is the function's
  83 % argument list.  If there are no arguments, use an empty pair of
  84 % curly braces.  If there is more than one argument, separate the
  85 % arguments with backslash-comma.  Optional parts of the parameter
  86 % list are contained in \optional{...} (this generates a set of square
  87 % brackets around its parameter).  Arguments are automatically set in
  88 % italics in the parameter list.  Each argument should be mentioned at
  89 % least once in the description; each usage (even inside \code{...})
  90 % should be enclosed in \var{...}.
  91
  92 \begin{funcdesc}{open}{filename\optional{, mode\optional{, buffersize}}}
  93 Open the file \var{filename} as a can of Spam.  The optional
  94 \var{mode} and \var{buffersize} arguments specify the read/write mode
  95 (\code{'r'} (default) or \code{'w'}) and the buffer size (default:
  96 system dependent).
  97 \end{funcdesc}
  98
  99 % ---- 3.2. ----
 100 % Data items are described using a ``datadesc'' block.  This has only
 101 % one parameter: the item's name.
 102
 103 \begin{datadesc}{cansize}
 104 The default can size, in ounces.  Legal values are 7 and 12.  The
 105 default varies per supermarket.  This variable should not be changed
 106 once the \function{open()} function has been called.
 107 \end{datadesc}
 108
 109 % --- 3.3. ---
 110 % Exceptions are described using a ``excdesc'' block.  This has only
 111 % one parameter: the exception name.  Exceptions defined as classes in
 112 % the source code should be documented using this environment, but
 113 % constructor parameters must be ommitted.
 114
 115 \begin{excdesc}{error}
 116 Exception raised when an operation fails for a Spam specific reason.
 117 The exception argument is a string describing the reason of the
 118 failure.
 119 \end{excdesc}
 120
 121 % ---- 3.4. ----
 122 % Other standard environments:
 123 %
 124 %  classdesc    - Python classes; same arguments are funcdesc
 125 %  methoddesc   - methods, like funcdesc but has an optional parameter
 126 %                 to give the type name: \begin{methoddesc}[mytype]{name}{args}
 127 %                 By default, the type name will be the name of the
 128 %                 last class defined using classdesc.  The type name
 129 %                 is required if the type is implemented in C (because
 130 %                 there's no classdesc) or if the class isn't directly
 131 %                 documented (if it's private).
 132 %  memberdesc   - data members, like datadesc, but with an optional
 133 %                 type name like methoddesc.
 134
 135
 136 % ==== 4. ====
 137 % Now is probably a good time for a complete example.  (Alternatively,
 138 % an example giving the flavor of the module may be given before the
 139 % detailed list of functions.)
 140
 141 \subsection{Example \label{spam-example}}
 142
 143 The following example demonstrates how to open a can of spam using the
 144 \module{spam} module.
 145
 146 \begin{verbatim}
 147 >>> import spam
 148 >>> can = spam.open('/etc/passwd')
 149 >>> can.empty()
 150 >>> can.close()
 151 \end{verbatim}
 152 % Note that there is no trailing ">>> " prompt shown.
 153
 154 % ==== 5. ====
 155 % If your module defines new object types (for a built-in module) or
 156 % classes (for a module written in Python), you should list the
 157 % methods and instance variables (if any) of each type or class in a
 158 % separate subsection.
 159
 160 \subsection{Spam Objects}
 161 \label{spam-objects}
 162 % This label is generally useful for referencing this section, but is
 163 % also used to give a filename when generating HTML.
 164
 165 Spam objects, as returned by \function{open()} above, have the
 166 following methods:
 167
 168 \begin{methoddesc}[spam]{empty}{}
 169 Empty the can into the trash.
 170 \end{methoddesc}