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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
|
<?xml version="1.0" encoding="ascii" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ascii" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>References</title>
<link rel="stylesheet" href="custom.css" type="text/css" />
</head>
<body>
<div class="document" id="references">
<h1 class="title">References</h1>
<!-- $Id: manual-reference.txt 1549 2007-02-24 16:23:49Z dvarrazzo $ -->
<div class="section" id="command-line-usage">
<h1>Command Line Usage</h1>
<p>Usage: <tt class="docutils literal"><span class="pre">epydoc.py</span></tt> [<em>ACTION</em>] [<em>options</em>] <em>NAMES...</em></p>
<dl class="docutils">
<dt>NAMES...</dt>
<dd>A list of the Python objects that should be documented. Objects can be
specified using dotted names (such as <tt class="docutils literal"><span class="pre">os.path</span></tt>), module filenames (such
as <tt class="docutils literal"><span class="pre">epydoc/epytext.py</span></tt>), or package directory names (such as
<tt class="docutils literal"><span class="pre">epydoc/</span></tt>). Packages are expanded to include all sub-modules and
sub-packages.</dd>
<dt>options</dt>
<dd><pre class="first last literal-block">
--config=FILE A configuration file, specifying additional OPTIONS
and/or NAMES. This option may be repeated.
-o PATH, --output=PATH
The output directory. If PATH does not exist, then it
will be created.
-q, --quiet Decrease the verbosity.
-v, --verbose Increase the verbosity.
--debug Show full tracebacks for internal errors.
--simple-term Do not try to use color or cursor control when
displaying the progress bar, warnings, or errors.
Actions:
--html Write HTML output.
--text Write plaintext output. (not implemented yet)
--latex Write LaTeX output.
--dvi Write DVI output.
--ps Write Postscript output.
--pdf Write PDF output.
--check Check completeness of docs.
--pickle Write the documentation to a pickle file.
--version Show epydoc's version number and exit.
-h, --help Show this message and exit. For help on specific
topics, use "--help TOPIC". Use "--help topics" for a
list of available help topics
Generation Options:
--docformat=NAME The default markup language for docstrings. Defaults
to "epytext".
--parse-only Get all information from parsing (don't introspect)
--introspect-only Get all information from introspecting (don't parse)
--exclude=PATTERN Exclude modules whose dotted name matches the regular
expression PATTERN
--exclude-introspect=PATTERN
Exclude introspection of modules whose dotted name
matches the regular expression PATTERN
--exclude-parse=PATTERN
Exclude parsing of modules whose dotted name matches
the regular expression PATTERN
--inheritance=STYLE
The format for showing inheritance objects. STYLE
should be one of: grouped, listed, included.
--show-private Include private variables in the output. (default)
--no-private Do not include private variables in the output.
--show-imports List each module's imports.
--no-imports Do not list each module's imports. (default)
--show-sourcecode Include source code with syntax highlighting in the
HTML output. (default)
--no-sourcecode Do not include source code with syntax highlighting in
the HTML output.
--include-log Include a page with the process log (epydoc-log.html)
Output Options:
--name=NAME The documented project's name (for the navigation
bar).
--css=STYLESHEET The CSS stylesheet. STYLESHEET can be either a
builtin stylesheet or the name of a CSS file.
--url=URL The documented project's URL (for the navigation bar).
--navlink=HTML HTML code for a navigation link to place in the
navigation bar.
--top=PAGE The "top" page for the HTML documentation. PAGE can
be a URL, the name of a module or class, or one of the
special names "trees.html", "indices.html", or
"help.html"
--help-file=FILE An alternate help file. FILE should contain the body
of an HTML file -- navigation bars will be added to
it.
--show-frames Include frames in the HTML output. (default)
--no-frames Do not include frames in the HTML output.
--separate-classes When generating LaTeX or PDF output, list each class
in its own section, instead of listing them under
their containing module.
API Linking Options:
--external-api=NAME
Define a new API document. A new interpreted text
role NAME will be added.
--external-api-file=NAME:FILENAME
Use records in FILENAME to resolve objects in the API
named NAME.
--external-api-root=NAME:STRING
Use STRING as prefix for the URL generated from the
API NAME.
Graph Options:
--graph=GRAPHTYPE Include graphs of type GRAPHTYPE in the generated
output. Graphs are generated using the Graphviz dot
executable. If this executable is not on the path,
then use --dotpath to specify its location. This
option may be repeated to include multiple graph types
in the output. GRAPHTYPE should be one of: all,
classtree, callgraph, umlclasstree.
--dotpath=PATH The path to the Graphviz 'dot' executable.
--graph-font=FONT Specify the font used to generate Graphviz graphs.
(e.g., helvetica or times).
--graph-font-size=SIZE
Specify the font size used to generate Graphviz
graphs, in points.
--pstat=FILE A pstat output file, to be used in generating call
graphs.
Return Value Options:
--fail-on-error Return a non-zero exit status, indicating failure, if
any errors are encountered.
--fail-on-warning Return a non-zero exit status, indicating failure, if
any errors or warnings are encountered (not including
docstring warnings).
--fail-on-docstring-warning
Return a non-zero exit status, indicating failure, if
any errors or warnings are encountered (including
docstring warnings).
</pre>
</dd>
</dl>
</div>
<div class="section" id="sample-configuration-file">
<h1>Sample Configuration File</h1>
<p>Configuration files, specified using the <tt class="docutils literal"><span class="pre">--config</span></tt> option, may be used to
specify both the list of objects to document, and the options that should be
used to document them. Configuration files are read using the standard
<a class="reference external" href="http://docs.python.org/lib/module-ConfigParser.html">ConfigParser</a> module. The following example configuration file demonstrates the
various options that you can set. Lines beginning with <tt class="docutils literal"><span class="pre">#</span></tt> or <tt class="docutils literal"><span class="pre">;</span></tt> are
treated as comments.</p>
<pre class="literal-block">
<strong>[epydoc]</strong> <em># Epydoc section marker (required by ConfigParser)</em>
<em># The list of objects to document. Objects can be named using</em>
<em># dotted names, module filenames, or package directory names.</em>
<em># Alases for this option include "objects" and "values".</em>
<strong>modules: sys, os.path, re</strong>
<em># The type of output that should be generated. Should be one</em>
<em># of: html, text, latex, dvi, ps, pdf.</em>
<strong>output: html</strong>
<em># The path to the output directory. May be relative or absolute.</em>
<strong>target: html/</strong>
<em># An integer indicating how verbose epydoc should be. The default</em>
<em># value is 0; negative values will supress warnings and errors;</em>
<em># positive values will give more verbose output.</em>
<strong>verbosity: 0</strong>
<em># A boolean value indicating that Epydoc should show a tracaback</em>
<em># in case of unexpected error. By default don't show tracebacks</em>
<strong>debug: 0</strong>
<em># If True, don't try to use colors or cursor control when doing</em>
<em># textual output. The default False assumes a rich text prompt</em>
<strong>simple-term: 0</strong>
<strong>### Generation options</strong>
<em># The default markup language for docstrings, for modules that do</em>
<em># not define __docformat__. Defaults to epytext.</em>
<strong>docformat: epytext</strong>
<em># Whether or not parsing should be used to examine objects.</em>
<strong>parse: yes</strong>
<em># Whether or not introspection should be used to examine objects.</em>
<strong>introspect: yes</strong>
<em># Don't examine in any way the modules whose dotted name match this</em>
<em># regular expression pattern.</em>
<strong>#exclude</strong>
<em># Don't perform introspection on the modules whose dotted name match this</em>
<em># regular expression pattern.</em>
<strong>#exclude-introspect</strong>
<em># Don't perform parsing on the modules whose dotted name match this</em>
<em># regular expression pattern.</em>
<strong>#exclude-parse</strong>
<em># The format for showing inheritance objects.</em>
<em># It should be one of: 'grouped', 'listed', 'included'.</em>
<strong>inheritance: listed</strong>
<em># Whether or not to inclue private variables. (Even if included,</em>
<em># private variables will be hidden by default.)</em>
<strong>private: yes</strong>
<em># Whether or not to list each module's imports.</em>
<strong>imports: no</strong>
<em># Whether or not to include syntax highlighted source code in</em>
<em># the output (HTML only).</em>
<strong>sourcecode: yes</strong>
<em># Whether or not to includea a page with Epydoc log, containing</em>
<em># effective option at the time of generation and the reported logs.</em>
<strong>include-log: no</strong>
<strong>### Output options</strong>
<em># The documented project's name.</em>
<strong>#name: Example</strong>
<em># The CSS stylesheet for HTML output. Can be the name of a builtin</em>
<em># stylesheet, or the name of a file.</em>
<strong>css: white</strong>
<em># The documented project's URL.</em>
<strong>#url: http://some.project/</strong>
<em># HTML code for the project link in the navigation bar. If left</em>
<em># unspecified, the project link will be generated based on the</em>
<em># project's name and URL.</em>
<strong>#link: <a href="somewhere">My Cool Project</a></strong>
<em># The "top" page for the documentation. Can be a URL, the name</em>
<em># of a module or class, or one of the special names "trees.html",</em>
<em># "indices.html", or "help.html"</em>
<strong>#top: os.path</strong>
<em># An alternative help file. The named file should contain the</em>
<em># body of an HTML file; navigation bars will be added to it.</em>
<strong>#help: my_helpfile.html</strong>
<em># Whether or not to include a frames-based table of contents.</em>
<strong>frames: yes</strong>
<em># Whether each class should be listed in its own section when</em>
<em># generating LaTeX or PDF output.</em>
<strong>separate-classes: no</strong>
<strong>### API linking options</strong>
<em># Define a new API document. A new interpreted text role</em>
<em># will be created</em>
<strong>#external-api: epydoc</strong>
<em># Use the records in this file to resolve objects in the API named NAME.</em>
<strong>#external-api-file: epydoc:api-objects.txt</strong>
<em># Use this URL prefix to configure the string returned for external API.</em>
<strong>#external-api-root: epydoc:http://epydoc.sourceforge.net/api</strong>
<strong>### Graph options</strong>
<em># The list of graph types that should be automatically included</em>
<em># in the output. Graphs are generated using the Graphviz "dot"</em>
<em># executable. Graph types include: "classtree", "callgraph",</em>
<em># "umlclass". Use "all" to include all graph types</em>
<strong>graph: all</strong>
<em># The path to the Graphviz "dot" executable, used to generate</em>
<em># graphs.</em>
<strong>dotpath: /usr/local/bin/dot</strong>
<em># The name of one or more pstat files (generated by the profile</em>
<em># or hotshot module). These are used to generate call graphs.</em>
<strong>pstat: profile.out</strong>
<em># Specify the font used to generate Graphviz graphs.</em>
<em># (e.g., helvetica or times).</em>
<strong>graph-font: Helvetica</strong>
<em># Specify the font size used to generate Graphviz graphs.</em>
<strong>graph-font-size: 10</strong>
<strong>### Return value options</strong>
<em># The condition upon which Epydoc should exit with a non-zero</em>
<em># exit status. Possible values are error, warning, docstring_warning</em>
<strong>#fail-on: error</strong>
</pre>
</div>
<div class="section" id="warnings-and-errors">
<h1>Warnings and Errors</h1>
<p>If epydoc encounters an error while processing a docstring, it issues a warning
message that describes the error, and attempts to continue generating
documentation. Errors related to epytext are divided into three categories:</p>
<dl class="docutils">
<dt>Epytext Warnings</dt>
<dd>are caused by epytext docstrings that contain questionable or suspicious
markup. Epytext warnings do not prevent the docstring in question from
being parsed.</dd>
<dt>Field Warnings</dt>
<dd>are caused by epytext docstrings containing invalid fields. The contents of
the invalid field are generally ignored.</dd>
<dt>Epytext Errors</dt>
<dd>are caused by epytext docstrings that contain invalid markup. Whenever an
epytext error is detected, the docstring in question is treated as a
plaintext docstring.</dd>
</dl>
<p>The following sections list and describe the warning messages that epydoc can
generate. They are intended as a reference resource, which you can search for
more information and possible causes if you encounter an error and do not
understand it. These descriptions are also available in the <tt class="docutils literal"><span class="pre">epydoc(1)</span></tt> man
page.</p>
<div class="section" id="epytext-warnings">
<h2>Epytext Warnings</h2>
<dl class="docutils">
<dt>Possible mal-formatted field item.</dt>
<dd>Epytext detected a line that looks like a field item, but is not correctly
formatted. This typically occurs when the trailing colon (<tt class="docutils literal"><span class="pre">:</span></tt>) is not
included in the field tag.</dd>
<dt>Possible heading typo.</dt>
<dd>Epytext detected a pair of lines that looks like a heading, but the number
of underline characters does not match the number of characters in the
heading. The number of characters in these two lines must match exactly for
them to be considered a heading.</dd>
</dl>
</div>
<div class="section" id="field-warnings">
<h2>Field Warnings</h2>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">@param</span></tt> for unknown parameter <em>param</em>.</dt>
<dd>A <tt class="docutils literal"><span class="pre">@param</span></tt> field was used to specify the type for a parameter that is not
included in the function's signature. This is typically caused by a typo in
the parameter name.</dd>
<dt><em>tag</em> did not expect an argument.</dt>
<dd>The field tag <em>tag</em> was used with an argument, but it does not take one.</dd>
<dt><em>tag</em> expected an argument.</dt>
<dd>The field tag <em>tag</em> was used without an argument, but it requires one.</dd>
<dt><tt class="docutils literal"><span class="pre">@type</span></tt> for unknown parameter <em>param</em>.</dt>
<dd>A <tt class="docutils literal"><span class="pre">@type</span></tt> field was used to specify the type for a parameter that is not
included in the function's signature. This is typically caused by a typo in
the parameter name.</dd>
<dt><tt class="docutils literal"><span class="pre">@type</span></tt> for unknown variable <em>var</em>.</dt>
<dd>A <tt class="docutils literal"><span class="pre">@type</span></tt> field was used to specify the type for a variable, but no
other information is known about the variable. This is typically caused
by a typo in the variable name.</dd>
<dt>Unknown field tag <em>tag</em>.</dt>
<dd>A docstring contains a field with the unknown tag <em>tag</em>.</dd>
<dt>Redefinition of <em>field</em>.</dt>
<dd>Multiple field tags define the value of field in the same docstring, but
field can only take a single value.</dd>
</dl>
</div>
<div class="section" id="epytext-errors">
<h2>Epytext Errors</h2>
<dl class="docutils">
<dt>Bad link target.</dt>
<dd>The target specified for an inline link contruction (L{...}) is not
well-formed. Link targets must be valid Python identifiers.</dd>
<dt>Bad uri target.</dt>
<dd>The target specified for an inline uri contruction (<tt class="docutils literal"><span class="pre">U{...}</span></tt>) is not
well-formed. This typically occurs if inline markup is nested inside the
URI target.</dd>
<dt>Fields must be at the top level.</dt>
<dd>The list of fields (<tt class="docutils literal"><span class="pre">@param</span></tt>, etc.) is contained by some other block
structure (such as a list or a section).</dd>
<dt>Fields must be the final elements in an epytext string.</dt>
<dd>The list of fields (<tt class="docutils literal"><span class="pre">@param</span></tt>, etc.) is not at the end of a docstring.</dd>
<dt>Headings must occur at top level.</dt>
<dd>The heading is contianed in some other block structure (such as a list).</dd>
<dt>Improper doctest block indentation.</dt>
<dd>The doctest block dedents past the indentation of its initial prompt line.</dd>
<dt>Improper heading indentation.</dt>
<dd>The heading for a section is not left-aligned with the paragraphs in the
section that contains it.</dd>
<dt>Improper paragraph indentation.</dt>
<dd>The paragraphs within a block are not left-aligned. This error is often
generated when plaintext docstrings are parsed using epytext.</dd>
<dt>Invalid escape.</dt>
<dd>An unknown escape sequence was used with the inline escape construction
(<tt class="docutils literal"><span class="pre">E{...}</span></tt>).</dd>
<dt>Lists must be indented.</dt>
<dd>An unindented line immediately following a paragraph starts with a list
bullet. Epydoc is not sure whether you meant to start a new list item, or
meant for a paragraph to include a word that looks like a bullet. If you
intended the former, then indent the list. If you intended the latter, then
change the word-wrapping of the paragraph, or escape the first character of
the word that looks like a bullet.</dd>
<dt>Unbalanced '<tt class="docutils literal"><span class="pre">{</span></tt>'.</dt>
<dd>The docstring contains unbalanced braces. Epytext requires that all braces
must be balanced. To include a single unbalanced brace, use the escape
sequences <tt class="docutils literal"><span class="pre">E{lb}</span></tt> (left brace) and <tt class="docutils literal"><span class="pre">E{rb}</span></tt> (right brace).</dd>
<dt>Unbalanced '<tt class="docutils literal"><span class="pre">}</span></tt>'.</dt>
<dd>The docstring contains unbalanced braces. Epytext requires that all braces
must be balanced. To include a single unbalanced brace, use the escape
sequences <tt class="docutils literal"><span class="pre">E{lb}</span></tt> (left brace) and <tt class="docutils literal"><span class="pre">E{rb}</span></tt> (right brace).</dd>
<dt>Unknown inline markup tag.</dt>
<dd>An unknown tag was used with the inline markup construction (<tt class="docutils literal"><span class="pre">x{...}</span></tt>).</dd>
<dt>Wrong underline character for heading.</dt>
<dd>The underline character used for this section heading does not indicate an
appopriate section level. The '<tt class="docutils literal"><span class="pre">=</span></tt>' character should be used to underline
sections; '<tt class="docutils literal"><span class="pre">-</span></tt>' for subsections; and '<tt class="docutils literal"><span class="pre">~</span></tt>' for subsubsections.</dd>
</dl>
</div>
</div>
</div>
<table width="100%" class="navbox" cellpadding="1" cellspacing="0">
<tr>
<a class="nav" href="index.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="index.html">
Home</a></td></a>
<a class="nav" href="installing.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="installing.html">
Installing Epydoc</a></td></a>
<a class="nav" href="using.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="using.html">
Using Epydoc</a></td></a>
<a class="nav" href="epytext.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="epytext.html">
Epytext</a></td></a>
<td align="center" width="20%" class="nav">
<A href="http://sourceforge.net/projects/epydoc">
<IMG src="sflogo.png"
width="88" height="26" border="0" alt="SourceForge"
align="top"/></A></td>
</tr>
</table>
</body>
</html>
|
