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
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>Using Epydoc</title>
<link rel="stylesheet" href="epydoc.css" type="text/css"/>
</head>
<!-- $Id: using.html 1538 2007-02-20 09:39:50Z dvarrazzo $ -->
<body>
<div class="body">
<h1>Using Epydoc</h1>
<p>Epydoc provides two user interfaces:</p>
<ul>
<li> The <a href="#cli">command line interface</a>, which is
accessed via a script named <code>epydoc</code> (or
<code>epydoc.py</code> on Windows)</li>
<li> The <a href="#gui">graphical interface</a>, which is accessed
via a script named <code>epydocgui</code> (or
<code>epydoc.pyw</code> on Windows).</li>
</ul>
<p>Epydoc can also be accessed programmatically; see epydoc's <a
href="api/">API documentation</a> for more information. </p>
<a name="cli"></a><h2> The Command Line Interface </h2>
<p> The <code>epydoc</code> script extracts API documentation for a
set of python objects, and writes it using a selected output format.
Objects can be named using dotted names, module filenames, or package
directory names. (On Windows, this script is named
<code>epydoc.py</code>.) </p>
<div class="box">
<h2 class="box-title">Command Line Usage (Abbreviated)</h2>
<pre>
<b>epydoc</b> [<b>--html</b>|<b>--pdf</b>] [<b>-o</b> <code class="user">DIR</code>] [<b>--parse-only</b>|<b>--introspect-only</b>] [<b>-v</b>|<b>-q</b>]
<b> </b>[<b>--name</b> <code class="user">NAME</code>] [<b>--url</b> <code class="user">URL</code>] [<b>--docformat</b> <code class="user">NAME</code>] [<b>--graph</b> <code class="user">GRAPHTYPE</code>]
<b> </b>[<b>--inheritance</b> <code class="user">STYLE</code>] [<b>--config</b> <code class="user">FILE</code>] <code class="user">OBJECTS...</code>
</pre>
<dl>
<dt><code><code class="user">OBJECTS...</code></code></dt>
<dd>
A list of the Python objects that should be documented. Objects
can be specified using dotted names (such as
"<code>os.path</code>"), module filenames (such as
"<code>epydoc/epytext.py</code>"), or package directory names
(such as "<code>epydoc/</code>"). Packages are expanded to
include all sub-modules and sub-packages.
</dd>
<dt><code><b>--html</b></code></dt>
<dd>Generate HTML output. (default)
</dd>
<dt><code><b>--pdf</b></code></dt>
<dd>Generate Adobe Acrobat (PDF) output, using LaTeX.
</dd>
<dt><code><b>-o</b> <code class="user">DIR</code></code>, <code><b>--output</b> <code class="user">DIR</code></code>, <code><b>--target</b> <code class="user">DIR</code></code></dt>
<dd>The output directory.
</dd>
<dt><code><b>--parse-only</b></code>,
<code><b>--introspect-only</b></code></dt>
<dd>By default, epydoc will gather information about each Python
object using two methods: parsing the object's source code; and
importing the object and directly introspecting it. Epydoc combines
the information obtained from these two methods to provide more
complete and accurate documentation. However, if you wish, you can
tell epydoc to use only one or the other of these methods. For
example, if you are running epydoc on untrusted code, you should use
the <code>--parse-only</code> option. </dd>
<dt><code><b>-v</b></code>, <code><b>-q</b></code></dt>
<dd>Increase (<code>-v</code>) or decrease (<code>-q</code>) the
verbosity of the output. These options may be repeated to further
increase or decrease verbosity. Docstring markup warnings
are supressed unless <code>-v</code> is used at least once.
</dd>
<dt><code><b>--name</b> <code class="user">NAME</code></code></dt>
<dd>The documented project's name.
</dd>
<dt><code><b>--url</b> <code class="user">URL</code></code></dt>
<dd>The documented project's URL.
</dd>
<dt><code><b>--docformat</b> <code class="user">NAME</code></code></dt>
<dd>The markup language that should be used by default to process
modules' docstrings. This is only used for modules that do not
define the special <code>__docformat__</code> variable; it is recommended
that you explicitly specify <code>__docformat__</code> in all your
modules.
</dd>
<dt><code><b>--graph</b> <code class="user">GRAPHTYPE</code></code></dt>
<dd>Include graphs of type <code>GRAPHTYPE</code> in the generated
output. Graphs are generated using the Graphviz dot executable. If
this executable is not on the path, then use <code>--dotpath</code>
to specify its location. This option may be repeated to include
multiple graph types in the output. To include all graphs, use
<code>--graph all</code>. To see an example of each graph
type, click on it:
<ul>
<li><a href="notyet" target="epydoc_graph">
<code>classtree</code></a>: Displays each class's base classes and
subclasses.
</li>
<li><a href="notyet" target="epydoc_graph">
<code>callgraph</code></a>: Displays the callers and callees of each
function or method. These graphs are based on profiling information,
which must be specified using the <code>--pstate</code> option.
</li>
<li><a href="notyet" target="epydoc_graph">
<code>umlclass</code></a>: Displays each class's base classes and
subclasses, using UML style. Methods and attributes are listed in
the classes where they are defined. If type information is
available about attributes (via the <code>@type</code> field),
then those types are displayed as separate classes, and the
attributes are displayed as associations.
</li>
</ul>
</dd>
<dt><code><b>--inheritance</b> <code class="user">STYLE</code></code></dt>
<dd>The format that should be used to display inherited methods,
variables, and properties. Currently, three styles are supported.
To see an example of each style, click on it:
<ul>
<li> <a
href="examples/grouped/inh_example.Programmer-class.html"
target="epydoc_inh"><code>grouped</code></a>: Inherited objects are
gathered into groups, based on which class they are inherited
from.</li> <li> <a
href="examples/listed/inh_example.Programmer-class.html"
target="epydoc_inh"><code>listed</code></a>: Inherited objects are
listed in a short list at the end of the summary
table.</li>
<li> <a
href="examples/included/inh_example.Programmer-class.html"
target="epydoc_inh"><code>included</code></a>: Inherited objects
are mixed in with non-inherited objects. </li>
</ul>
</dd>
<dt><code><b>--config</b> <code class="user">FILE</code></code></dt>
<dd>Read the given configuration file, which can contain both
options and Python object names. This option may be used multiple
times, if you wish to use multiple configuration files. See <a
href="#configfile">Configuration Files</a> for more information.
</dd>
</dl>
<p>For a complete description of the command line usage for epydoc,
see the <a href="epydoc-man.html"><code>epydoc(1)</code> man
page</a></p>
</div>
<h3> Examples </h3>
<p>The following command will generate
HTML documentation for the <code>sys</code> module, and write it to
the directory <code>sys_docs</code>:</p>
<div class="screen"><pre>
<code class="prompt">[epydoc]$</code> epydoc --html sys -o sys_docs
</pre></div>
<p> The following commands are used to produce the API documentation
for epydoc itself. The first command writes html output to the
directory <code>html/api</code>, using <code>epydoc</code> as the
project name and <code>http://epydoc.sourcforge.net</code> as the
project URL. The <code>white</code> CSS style is used; inheritance is
displayed using the <code>listed</code> style; and all graphs are
included in the output. The second command writes pdf output to the
file <code>api.pdf</code> in the directory <code>latex/api</code>,
using <code>Epydoc</code> as the project name.</p>
<div class="screen"><pre>
<code class="prompt">[epydoc]$</code> epydoc -v -o html/api --name epydoc --css white \
--url http://epydoc.sourceforge.net \
--inheritance listed --graph all src/epydoc
<code class="prompt">[epydoc]$</code> epydoc -v -o latex/api --pdf --name "Epydoc" src/epydoc
</pre></div>
<a name="configfile"><h3> Configuration Files </h3></a>
Configuration files, specified using the <code>--config</code> 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
href="http://docs.python.org/lib/module-ConfigParser.html">ConfigParser</a>
module. The following is a simple example of a configuration file.
<div class="box">
<h2 class="box-title">Example Configuration File</h2>
<pre>
<b>[epydoc]</b> <i># Epydoc section marker (required by ConfigParser)</i>
<i># Information about the project.</i>
<b>name: My Cool Project</b>
<b>url: http://cool.project/</b>
<i># The list of modules to document. Modules can be named using</i>
<i># dotted names, module filenames, or package directory names.</i>
<i># This option may be repeated.</i>
<b>modules: sys, os.path, re</b>
<b>modules: my/project/driver.py</b>
<i># Write html output to the directory "apidocs"</i>
<b>output: html</b>
<b>target: apidocs/</b>
<i># Include all automatically generated graphs. These graphs are</i>
<i># generated using Graphviz dot.</i>
<b>graph: all</b>
<b>dotpath: /usr/local/bin/dot</b>
</pre></div>
<p>A <a href="configfile.html">more complete example</a>, including
all of the supported options, is also available.</p>
<a name="gui"><h2> The Graphical Interface </h2></a>
<p> Epydoc also includes a graphical interface, for systems where
command line interfaces are not convenient (such as Windows). The
graphical interface can be invoked with the <code>epydocgui</code>
command, or with <code>epydoc.pyw</code> in the <code>Scripts</code>
subdirectory of the Python installation directory under Windows.
Currently, the graphical interface can only generate HTML output.</p>
<a name="gui"/>
<center><p><img src="epydoc_gui.png"></p>
</center>
<p> Use the "Add" box to specify what objects you wish to document.
Objects can be specified using dotted names (such as
"<code>os.path</code>"), module filenames (such as
"<code>epydoc/epytext.py</code>"), or package directory names (such as
"<code>epydoc/</code>"). Packages are expanded to include all
sub-modules and sub-packages. Once you have added all of the modules
that you wish to document, press the "Start" button. Epydoc's
progress will be displayed on the progress bar. </p>
<p> To customize the output, click on the "Options" arrow at the
bottom of the window. This opens the options pane, which contains
fields corresponding to each command line option. </p>
<a name="guiconfig"/>
<center><p><img src="epydoc_guiconfig.png"></p>
</center>
<p> The epydoc graphical interface can save and load "project files",
which record the set of modules and the options that you have
selected. Select "<code>File→Save</code>" to save the current
modules and options to a project file; and
"<code>File→Open</code>" to open a previously saved project file.
(These project files do not currently use the same format as the
configuration files used by the command line interface.) </p>
<p> For more information, see the <a
href="epydocgui-man.html"><code>epydocgui(1)</code> man page</a>. </p>
<a name="checker"><h2> Documentation Completeness Checks </h2></a>
<p> The <code>epydoc</code> script can be used to check the
completeness of the reference documentation. In particular, it will
check that every module, class, method, and function has a
description; that every parameter has a description and a type; and
that every variable has a type. If the "<code>-p</code>" option is
used, then these checks are run on both public and private objects;
otherwise, the checks are only run on public objects. </p>
<div class="box">
<pre>
<b>epydoc</b> <b>--check</b> [<b>-p</b>] <code class="user">MODULES...</code>
</pre>
<dl>
<dt><code><code class="user">MODULES...</code></code></dt>
<dd>
A list of the modules that should be checked. Modules may be
specified using either filenames (such as
"<code>epydoc/epytext.py</code>") or module names (such as
"<code>os.path</code>"). The filename for a package is its
"<code>__init__.py</code>" file.
</dd>
<dt><code><b>-p</b></code></dt>
<dd>Run documentation completeness checks on private objects.
</dd>
</dl>
</div>
<p> For each object that fails a check, epydoc will print a warning.
For example, some of the warnings generated when checking the
completeness of the documentation for epydoc's private objects are:
</p>
<div class="screen"><pre>
epydoc.html.HTML_Doc._dom_link_to_html........No docs
epydoc.html.HTML_Doc._module..................No type
epydoc.html.HTML_Doc._link_to_html.link.......No descr
epydoc.html.HTML_Doc._author.return...........No type
epydoc.html.HTML_Doc._author.authors..........No descr, No type
epydoc.html.HTML_Doc._author.container........No descr, No type
epydoc.html.HTML_Doc._base_tree.uid...........No descr, No type
epydoc.html.HTML_Doc._base_tree.width.........No descr, No type
epydoc.html.HTML_Doc._base_tree.postfix.......No descr, No type
</pre></div>
<p> If you'd like more fine-grained control over what gets checked, or
you would like to check other fields (such as the author or version),
then you should use the <a
href="api/public/epydoc.checker.DocChecker.html"><code>DocChecker</code></a>
class directly. </p>
<a name="files"><h2> HTML Files </h2></a>
<p> Every Python module and class
is documented in its own file. Index files, tree files, a
help file, and a frames-based table of contents are also created.
The following list describes each of the files generated by
epydoc: </p>
<ul>
<li><b><code>index.html</code></b>
The standard entry point for the documentation. Normally,
<code>index.html</code> is a copy of the frames file
(<code>frames.html</code>). But if the <code>--no-frames</code>
option is used, then <code>index.html</code> is a copy of the API
documentation home page, which is normally the documentation page
for the top-level package or module (or the trees page if there is
no top-level package or module). </li>
<li><b><code><code class="user">module</code>-module.html</code></b>
The API documentation for a module. module is the complete dotted
name of the module, such as sys or epydoc.epytext. </li>
<li><b><code><code class="user">class</code>-class.html</code></b>
The API documentation for a class, exception, or type. class is the
complete dotted name of the class, such as epydoc.epytext.Token or
array.ArrayType. </li>
<li><b><code><code class="user">module</code>-pysrc.html</code></b>
A page with the module colourized source code, with links back to the
objects main documentation pages. The creation of the colourized source
pages can be controlled using the options <code>--show-sourcecode</code> and
<code>--no-sourcecode</code>.</li>
<li><b><code>module-tree.html</code></b>
The documented module hierarchy. </li>
<li><b><code>class-tree.html</code></b>
The documented classes hierarchy. </li>
<li><b><code>identifier-index.html</code></b>
The index of all the identifiers found in the documented items. </li>
<li><b><code>term-index.html</code></b>
The index of all the term definition found in the docstrings.
Term definitions are created using the <a href="epytext.html#indexed">Indexed
Term</a> markup. </li>
<li><b><code>bug-index.html</code></b>
The index of all the known bug in the documented sources.
Bugs are marked using the <code>@bug</code> tag. </li>
<li><b><code>todo-index.html</code></b>
The index of all the <i>to-do</i> items in the documented sources.
They are marked using the <code>@todo</code> tag. </li>
<li><b><code>help.html</code></b>
The help page for the project. This page explains how to use and
navigate the webpage produced by epydoc. </li>
<li><b><code>epydoc-log.html</code></b>
A page with the log of the epydoc execution. It is available clicking on the
timestamp below each page, if the documentation was created using the
<code>--include-log</code> option. The page also contains the list of the
options enabled when the documentation was created. </li>
<li><b><code>api-objects.txt</code></b>
A text file containing each available item and the URL where it is
documented. Each item dotted name takes a file line and it is separated by
the URL by a <code>tab</code> charecter. Such file can be used to create
documents linkig to the API: see the <code>--external-api</code>
documentation for details.</li>
<li><b><code>redirect.html</code></b>
A page containing Javascript code that redirect the browser to the
documentation page indicated by the accessed fragment. For example opening
the page <code>redirect.html#epydoc.apidoc.DottedName</code> the browser
will be redirected to the page
<code>epydoc.apidoc.DottedName-class.html</code>.</li>
<li><b><code>frames.html</code></b>
The main frames file. Two frames on the left side of the window
contain a table of contents, and the main frame on the right side of
the window contains API documentation pages. </li>
<li><b><code>toc.html</code></b>
The top-level table of contents page. This page is displayed in the
upper-left frame of <code>frames.html</code>, and provides links to
the <code>toc-everything.html</code> and
<code>toc-<code class="user">module</code>-module.html</code> pages. </li>
<li><b><code>toc-everything.html</code></b>
The table of contents for the entire project. This page is
displayed in the lower-left frame of <code>frames.html</code>, and
provides links to every class, type, exception, function, and
variable defined by the project. </li>
<li><b><code>toc-<code class="user">module</code>-module.html</code></b>
The table of contents for a module. This page is displayed in the
lower-left frame of <code>frames.html</code>, and provides links to
every class, type, exception, function, and variable defined by the
module. module is the complete dotted name of the module, such as
sys or epydoc.epytext. </li>
<li><b><code>epydoc.css</code></b>
The CSS stylesheet used to display all HTML pages. </li>
</ul>
<a name="css"><h2> CSS Stylesheets </h2></a>
<p> Epydoc creates a CSS stylesheet (<code>epydoc.css</code>) when it
builds the API documentation for a project. You can specify which
stylesheet should be used using the <code>--css</code> command-line
option. If you do not specify a stylesheet, and one is already
present, epydoc will use that stylesheet; otherwise, it will use the
default stylesheet. For a list of the CSS classes used by epydoc, see
the <a href="stylesheet.html">default stylesheet</a>. </p>
<a name="errors"><h2> Errors </h2></a>
<p> For a description of the errors that can be generated by epydoc,
see the <a href="epydoc-man.html#lbAH"><code>epydoc(1)</code> man
page</a>. </p>
</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="navselect" 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>
|
