1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
% 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}
|
