1EPYDOC(1) General Commands Manual EPYDOC(1)
2
3
4
6 epydoc - generate API documentation from Python docstrings
7
9 epydoc [action] [options] names...
10
12 epydoc generates API documentation for Python modules and packages,
13 based on their docstrings. A lightweight markup language called epy‐
14 text can be used to format docstrings, and to add information about
15 specific fields, such as parameters and instance variables. Epydoc
16 also understands docstrings written in ReStructuredText, Javadoc, and
17 plaintext. Currently, epydoc supports two basic output formats: HTML
18 and LaTeX.
19
20 The HTML API documentation produced by epydoc consists of a set of HTML
21 files, including: an API documentation page for each class and module;
22 a syntax-highlighted source code page for each module; an identifier
23 index page; a help page; and a frames-based table of contents. When
24 appropriate, epydoc will also generate index pages for bugs, defined
25 terms, and to-do items; a class hierarchy page; and a package hierarchy
26 page.
27
28 The LaTeX API documentation produced by epydoc consists of a main LaTeX
29 file, and a LaTeX file for each module. If you use --dvi, --ps, or
30 --pdf , then epydoc will invoke external commands to convert the LaTeX
31 output to the requested format. Note that the LaTeX files containing
32 the documentation for individual modules can be included as chapters or
33 sections of other LaTeX documents, using the LaTeX \include command.
34 If you wish to include individual classes in other LaTeX documents,
35 then use the --separate-classes option to produce a separate LaTeX file
36 for each class.
37
38 epydoc can also be used to check the completeness of the API documenta‐
39 tion. By default, it checks that every public package, module, class,
40 method, and function has a docstring description. The --tests option
41 can be used to specify additional tests to perform.
42
44 Epydoc's options are divided into six categories: basic options,
45 actions, generation options, output options, graph options, and return
46 value options.
47
48 BASIC OPTIONS
49
50 names...
51 The list of objects that should be documented. Objects can
52 be specified using Python dotted names (such as os.path),
53 filenames (such as epydoc/epytext.py), or directory names
54 (such as epydoc/). Directory names specify packages, and
55 are expanded to include all sub-modules and sub-packages.
56 If you wish to exclude certain sub-modules or sub-packages,
57 use the --exclude option (described below).
58
59 --config file
60 A configuration file, specifying additional option‐
61 sand/ornames. This option may be repeated.
62
63 --q, --quiet, --v, --verbose
64 Produce quite (or verbose) output. If used multiple times,
65 this option produces successively more quiet (or verbose)
66 output.
67
68 --debug
69 Show full tracebacks for internal errors.
70
71 --simple-term
72 Do not try to use color or cursor control when displaying
73 the progress bar, warnings, or errors.
74
75 ACTIONS
76
77 --html Write HTML output. [default]
78
79 --latex Write LaTeX output.
80
81 --dvi Write DVI output.
82
83 --ps Write Postscript output.
84
85 --pdf Write Adobe Acrobat (pdf) output.
86
87 --check Perform completeness checks on the documentation.
88
89 --pickle Write the documentation to a pickle file.
90
91 GENERATION OPTIONS
92
93 --docformat format
94 Set the default value for __docformat__ to format. __doc‐
95 format__ is a module variable that specifies the markup lan‐
96 guage for the docstrings in a module. Its value consists of
97 the name of a markup language, optionally followed by a lan‐
98 guage code (such as en for English). For a list of the
99 markup languages currently recognized by epydoc, run epydoc
100 --help docformat.
101
102 --parse-only
103 Gather all information about the documented objects by pars‐
104 ing the relevant Python source code; in particular, do not
105 use introspection to gather information about the documented
106 objects. This option should be used when epydoc is run on
107 untrusted code; or on code that can not be introspected
108 because of missing dependencies, or because importing it
109 would cause undesired side-effects.
110
111 --introspect-only
112 Gather all information about the documented objects by
113 introspection; in particular, do not gather information by
114 parsing the object's Python source code.
115
116 --exclude PATTERN
117 Do not document any object whose name matches the given reg‐
118 ular expression pattern.
119
120 --exclude-introspect PATTERN
121 Do not use introspection to gather information about any
122 object whose name matches the given regular expression.
123
124 --exclude-parse PATTERN
125 Do not use Python source code parsing to gather information
126 about any object whose name matches the given regular
127 expression.
128
129 --inheritance format
130 The format that should be used to display inherited methods,
131 variables, and properties in the generated "summary" tables.
132 If format is "grouped," then inherited objects are gathered
133 into groups, based on which class that they are inherited
134 from. If format is "listed," then inherited objects are
135 listed in a short list at the end of the summary table. If
136 format is "included," then inherited objects are mixed in
137 with non-inherited objects. The default format for HTML
138 output is "grouped."
139
140 --show-private, --no-private
141 These options control whether documentation is generated for
142 private objects. By default, the generated documentation
143 includes private objects, and users can choose whether to
144 view private objects or not, by clicking on "show private"
145 and "hide private" links. But if you want to discourage
146 users from directly accessing private objects, then you may
147 prefer not to generate documentation for private objects.
148
149 --show-imports, --no-imports
150 These options control whether module imports are included in
151 the generated documentation. By default, imports are not
152 included.
153
154 --show-sourcecode, --no-sourcecode
155 These options control whether or not epydoc should generate
156 syntax-highlighted pages containing the souce code of each
157 module in the HTML output. By default, the sourcecode pages
158 are generated.
159
160 --include-log
161 Generate an HTML page epydoc-log.html containing all error
162 and warning messages that are generated by epydoc, and
163 include it in the generated output.
164
165 OUTPUT OPTIONS
166
167 -o dir, --output dir
168 The output directory. If dir does not exist, then it will
169 be created. If no output directory is specified, then the
170 action name (e.g., html or pdf). html
171
172 -c sheet, --css sheet
173 CSS stylesheet for HTML output files. If sheet is a file,
174 then the stylesheet is copied from that file; otherwise,
175 sheet is taken to be the name of a built-in stylesheet. For
176 a list of the built-in stylesheets, run epydoc --help css.
177 If a CSS stylesheet is not specified, then the default
178 stylesheet is used.
179
180 -n name, --name name
181 The name of the project whose documentation is being gener‐
182 ated.
183
184 -u url, --url url
185 The URL of the project's homepage.
186
187
188 --navlink html
189 HTML code for the homepage link on the HTML navi‐
190 gation bar. If this HTML code contains any
191 hyperlinks (<a href=...>), then it will be
192 inserted verbatim. If it does not contain any
193 hyperlinks, and a project url is specified (with
194 --url), then a hyperlink to the specified URL is
195 added to the link.
196
197 --help-file file
198 An alternate help file. file should contain the
199 body of an HTML file -- navigation bars will be
200 added to it.
201
202 --show-frames, --no-frames
203 These options control whether HMTL output will
204 include a frames-base table of contents page. By
205 default, the frames-based table of contents is
206 included.
207
208 --separate-classes
209 In the LaTeX output, describe each class in a
210 separate section of the documentation, instead of
211 including them in the documentation for their
212 modules. This creates a separate LaTeX file for
213 each class, so it can also be useful if you want
214 to include the documentation for one or two
215 classes as sections of your own LaTeX document.
216
217 --include-timestamp
218 Include a timestamp in the generated output.
219
220 --suppress-timestamp
221 ignored, only exists for backwards compatibility.
222 (it is now the default)
223
224 GRAPH OPTIONS
225
226 --graph graphtype
227 Include graphs of type graphtype in the generated
228 output. Graphs are generated using the Graphviz
229 dot executable. If this executable is not on the
230 path, then use --dotpath to specify its location.
231 This option may be repeated to include multiple
232 graph types in the output. graphtype should be
233 one of: all, classtree, callgraph, or uml‐
234 classtree.
235
236 --dotpath path
237 The path to the Graphviz dot executable.
238
239 --graph-font font
240 The name of the font used to generate Graphviz
241 graphs. (e.g., helvetica or times).
242
243 --graph-font-size size
244 The size of the font used to generate Graphviz
245 graphs, in points.
246
247 --pstat file
248 A pstat output file, to be used in generating
249 call graphs.
250
251 RETURN VALUE OPTIONS
252
253 --fail-on-error
254 Return a non-zero exit status, indicating fail‐
255 ure, if any errors are encountered.
256
257 --fail-on-warning
258 Return a non-zero exit status, indicating fail‐
259 ure, if any errors or warnings are encountered
260 (not including docstring warnings).
261
262 --fail-on-docstring-warning
263 Return a non-zero exit status, indicating fail‐
264 ure, if any errors or warnings are encountered
265 (including docstring warnings).
266
268 The HTML API documentation produced by epydoc consists of
269 the following files:
270
271 OBJECT DOCUMENTATION PAGES
272
273 index.html
274 The standard entry point for the documentation.
275 Normally, index.html is a copy of the frames file
276 (frames.html). But if the --no-frames option is
277 used, then index.html is a copy of the API docu‐
278 mentation home page, which is normally the docu‐
279 mentation page for the top-level package or mod‐
280 ule (or the trees page if there is no top-level
281 package or module).
282
283 module-module.html
284 The API documentation for a module. module is
285 the complete dotted name of the module, such as
286 sys or epydoc.epytext.
287
288 class-class.html
289 The API documentation for a class, exception, or
290 type. class is the complete dotted name of the
291 class, such as epydoc.epytext.Token or
292 array.ArrayType.
293
294 module-pysrc.html
295 A syntax-highlighted page containing the Python
296 source code for module. This page includes links
297 back to the API documentation pages.
298
299 module-tree.html
300 The module hierarchy.
301
302 class-tree.html
303 The class hierarchy. This page is only generated
304 if at least one class is documented.
305
306 INDICES
307
308 identifier-index.html
309 An index of all documented identifiers. If the
310 identifier index contains more than 3,000
311 entries, then it will be split into separate
312 pages for each letter, named identifier-index-
313 a.html, identifier-index-b.html, etc.
314
315 term-index.html
316 An index of all explicitly marked definitional
317 terms. This page is only generated if at least
318 one definition term is marked in a formatted doc‐
319 string.
320
321 bug-index.html
322 An index of all explicitly marked @bug fields.
323 This page is only generated if at least one @bug
324 field is listed in a formatted docstring.
325
326 todo-index.html
327 An index of all explicitly marked @todo fields.
328 This page is only generated if at least one @todo
329 field is listed in a formatted docstring.
330
331 changed-index.html
332 An index of all explicitly marked @changed
333 fields. This page is only generated if at least
334 one @changed field is listed in a formatted doc‐
335 string.
336
337 deprecated-index.html
338 An index of all explicitly marked @deprecated
339 fields. This page is only generated if at least
340 one @deprecated field is listed in a formatted
341 docstring.
342
343 since-index.html
344 An index of all explicitly marked @since fields.
345 This page is only generated if at least one
346 @since field is listed in a formatted docstring.
347
348 FRAMES-BASED TABLE OF CONTENTS
349
350 frames.html
351 The main frames file. Two frames on the left
352 side of the window contain a table of contents,
353 and the main frame on the right side of the win‐
354 dow contains API documentation pages.
355
356 toc.html
357 The top-level table of contents page. This page
358 is displayed in the upper-left frame of
359 frames.html, and provides links to the toc-every‐
360 thing.html and toc-module-module.html pages.
361
362 toc-everything.html
363 The table of contents for the entire project.
364 This page is displayed in the lower-left frame of
365 frames.html, and provides links to every class,
366 type, exception, function, and variable defined
367 by the project.
368
369 toc-module-module.html
370 The table of contents for a module. This page is
371 displayed in the lower-left frame of frames.html,
372 and provides links to every class, type, excep‐
373 tion, function, and variable defined by the mod‐
374 ule. module is the complete dotted name of the
375 module, such as sys or epydoc.epytext.
376
377 OTHER PAGES
378
379 help.html
380 The help page for the project. This page
381 explains how to use and navigate the webpage pro‐
382 duced by epydoc.
383
384 redirect.html
385 This page uses javascript to translate dotted
386 names to their corresponding URLs. For example,
387 in epydoc's documentation, loading the page <re‐
388 direct.html#epydoc.apidoc.DottedName> will auto‐
389 matically redirect the browser to <epydoc.apidoc-
390 module.html#DottedName>.
391
392 epydoc.css
393 The CSS stylesheet used to display all HTML
394 pages.
395
396 epydoc.js
397 A javascript file used to define javascript func‐
398 tions used by epydoc.
399
400 epydoc-log.html
401 A page containing a log of all warnings and
402 errors that were generated by epydoc, along with
403 a table listing all of the options that were
404 used.
405
407 The LaTeX API documentation produced by epydoc consists of
408 the following files:
409
410 api.pdf
411 An Adobe Acrobat (pdf) file containing the com‐
412 plete API documentation. This file is only gen‐
413 erated if you use the --pdf option.
414
415 api.tex
416 The top-level LaTeX file. This file imports the
417 other LaTeX files, to create a single unified
418 document.
419
420 api.dvi
421 A dvi file containing the complete API documenta‐
422 tion. This file is only generated if you use the
423 --dvi option, the --ps option, or the --pdf
424 option.
425
426 api.ps A postscript file containing the complete API
427 documentation. This file is only generated if
428 you use the --ps option or the --pdf option.
429
430 module-module.tex
431 The API documentation for a module. module is
432 the complete dotted name of the module, such as
433 sys or epydoc.epytext.
434
435 class-class.tex
436 The API documentation for a class, exception, or
437 type. class is the complete dotted name of the
438 class, such as epydoc.epytext.Token or
439 array.ArrayType. These class documentation files
440 are only created if the --separate-classes option
441 is used; otherwise, the documentation for each
442 class is included in its module's documentation
443 file.
444
446 EPYTEXT MARKUP WARNING MESSAGES
447 Epytext errors are caused by epytext docstrings that
448 contain invalid markup. Whenever an epytext error is
449 detected, the docstring in question is treated as a
450 plaintext docstring. Epydoc can generate the following
451 epytext errors:
452
453 Bad link target.
454 The target specified for an inline link contruc‐
455 tion (L{...}) is not well-formed. Link targets
456 must be valid python identifiers.
457
458 Bad uri target.
459 The target specified for an inline uri contruc‐
460 tion (U{...}) is not well-formed. This typically
461 occurs if inline markup is nested inside the URI
462 target.
463
464 Fields must be at the top level.
465 The list of fields (@param, etc.) is contained
466 by some other block structure (such as a list or
467 a section).
468
469 Fields must be the final elements.
470 The list of fields (@param, etc.) is not at the
471 end of a docstring.
472
473 Headings must occur at top level.
474 The heading is contianed in some other block
475 structure (such as a list).
476
477 Improper doctest block indentation.
478 The doctest block dedents past the indentation of
479 its initial prompt line.
480
481 Improper heading indentation.
482 The heading for a section is not left-aligned
483 with the paragraphs in the section that contains
484 it.
485
486 Improper paragraph indentation.
487 The paragraphs within a block are not left-
488 aligned. This error is often generated when
489 plaintext docstrings are parsed using epytext.
490
491 Invalid escape.
492 An unknown escape sequence was used with the
493 inline escape construction (E{...}).
494
495 Lists must be indented.
496 An unindented line immediately following a para‐
497 graph starts with a list bullet. Epydoc is not
498 sure whether you meant to start a new list item,
499 or meant for a paragraph to include a word that
500 looks like a bullet. If you intended the former,
501 then indent the list. If you intended the lat‐
502 ter, then change the word-wrapping of the para‐
503 graph, or escape the first character of the word
504 that looks like a bullet.
505
506 Unbalanced '{'.
507 The docstring contains unbalanced braces. Epy‐
508 text requires that all braces must be balanced.
509 To include a single unbalanced brace, use the
510 escape sequences E{lb} (left brace) and E{rb}
511 (right brace).
512
513 Unbalanced '}'.
514 The docstring contains unbalanced braces. Epy‐
515 text requires that all braces must be balanced.
516 To include a single unbalanced brace, use the
517 escape sequences E{lb} (left brace) and E{rb}
518 (right brace).
519
520 Unknown inline markup tag.
521 An unknown tag was used with the inline markup
522 construction ( x{...} ).
523
524 Wrong underline character for heading.
525 The underline character used for this section
526 heading does not indicate an appopriate section
527 level. The "=" character should be used to
528 underline sections; "-" for subsections; and "~"
529 for subsubsections.
530
531 Possible mal-formatted field item.
532 Epytext detected a line that looks like a field
533 item, but is not correctly formatted. This typi‐
534 cally occurs when the trailing colon (":") is not
535 included in the field tag.
536
537 Possible heading typo.
538 Epytext detected a pair of lines that looks like
539 a heading, but the number of underline characters
540 does not match the number of characters in the
541 heading. The number of characters in these two
542 lines must match exactly for them to be consid‐
543 ered a heading.
544
545 FIELD WARNINGS
546 Field warnings are caused by docstrings containing
547 invalid fields. The contents of the invalid field are
548 generally ignored. Epydoc can generate the following
549 field warnings:
550
551 @param for unknown parameter param.
552 A @param field was used to specify the type for a
553 parameter that is not included in the function's
554 signature. This is typically caused by a typo in
555 the parameter name.
556
557 tag did not expect an argument.
558 The field tag tag was used with an argument, but
559 it does not take one.
560
561 tag expected an argument.
562 The field tag tag was used without an argument,
563 but it requires one.
564
565 @type for unknown parameter param.
566 A @type field was used to specify the type for a
567 parameter that is not included in the function's
568 signature. This is typically caused by a typo in
569 the parameter name.
570
571 @type for unknown variable var.
572 A @type field was used to specify the type for a
573 variable, but no other information is known about
574 the variable. This is typically caused by a typo
575 in the variable name.
576
577 Unknown field tag tag.
578 A docstring contains a field with the unknown tag
579 tag.
580
581 Redefinition of field.
582 Multiple field tags define the value of field in
583 the same docstring, but field can only take a
584 single value.
585
587 epydoc -n epydoc -u http://epydoc.sf.net epydoc/
588 Generate the HTML API documentation for the epydoc
589 package and all of its submodules, and write the out‐
590 put to the html directory. In the headers and foot‐
591 ers, use epydoc as the project name, and http://epy‐
592 doc.sf.net as the project URL.
593
594 epydoc --pdf -n epydoc epydoc/
595 Generate the LaTeX API documentation for the epydoc
596 package and all of its submodules, and write the out‐
597 put to the latex directory.
598
600 0 Successful program execution.
601
602 1 Usage error.
603
604 2 Epydoc generated an error or warning, and one of the
605 options --fail-on-error, --fail-on-warning, or
606 --fail-on-docstring-warning was specified.
607
608 other Internal error (Python exception).
609
611 Epydoc was written by Edward Loper. This man page was orig‐
612 inally written by Moshe Zadka, and is currently maintained
613 by Edward Loper.
614
616 Report bugs to <edloper@users.sourceforge.net>.
617
619 epydocgui(1)
620
621 The epydoc webpage
622 <http://epydoc.sourceforge.net>
623
624 The epytext markup language manual
625 <http://epydoc.sourceforge.net/epytext.html>
626
627
628
629 EPYDOC(1)