# cpython-fullhistory / Doc / templates / module.tex

  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 /lib.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}