1EPYDOC(1) General Commands Manual EPYDOC(1)
2
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 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 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 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 BASIC OPTIONS
49 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 --config file
60 A configuration file, specifying additional option‐
61 sand/ornames. This option may be repeated.
62 --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 --debug
69 Show full tracebacks for internal errors.
70 --simple-term
72 Do not try to use color or cursor control when displaying
73 the progress bar, warnings, or errors.
74 ACTIONS
76 --html Write HTML output. [default]
78 --latex Write LaTeX output.
80 --dvi Write DVI output.
82 --ps Write Postscript output.
84 --pdf Write Adobe Acrobat (pdf) output.
86 --check Perform completeness checks on the documentation.
88 --pickle Write the documentation to a pickle file.
90 GENERATION OPTIONS
92 --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 --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 --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 --exclude PATTERN
117 Do not document any object whose name matches the given reg‐
118 ular expression pattern.
119 --exclude-introspect PATTERN
121 Do not use introspection to gather information about any
122 object whose name matches the given regular expression.
123 --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 --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 --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 --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 --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 --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 OUTPUT OPTIONS
166 -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 -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 -n name, --name name
181 The name of the project whose documentation is being gener‐
182 ated.
183 -u url, --url url
185 The URL of the project's homepage.
186 --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 --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 --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 --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 GRAPH OPTIONS
218 --graph graphtype
220 Include graphs of type graphtype in the generated
221 output. Graphs are generated using the Graphviz
222 dot executable. If this executable is not on the
223 path, then use --dotpath to specify its location.
224 This option may be repeated to include multiple
225 graph types in the output. graphtype should be
226 one of: all, classtree, callgraph, or uml‐
227 classtree.
228 --dotpath path
230 The path to the Graphviz dot executable.
231 --graph-font font
233 The name of the font used to generate Graphviz
234 graphs. (e.g., helvetica or times).
235 --graph-font-size size
237 The size of the font used to generate Graphviz
238 graphs, in points.
239 --pstat file
241 A pstat output file, to be used in generating
242 call graphs.
243 RETURN VALUE OPTIONS
245 --fail-on-error
247 Return a non-zero exit status, indicating fail‐
248 ure, if any errors are encountered.
249 --fail-on-warning
251 Return a non-zero exit status, indicating fail‐
252 ure, if any errors or warnings are encountered
253 (not including docstring warnings).
254 --fail-on-docstring-warning
256 Return a non-zero exit status, indicating fail‐
257 ure, if any errors or warnings are encountered
258 (including docstring warnings).
259
261 The HTML API documentation produced by epydoc consists of
262 the following files:
263 OBJECT DOCUMENTATION PAGES
265 index.html
267 The standard entry point for the documentation.
268 Normally, index.html is a copy of the frames file
269 (frames.html). But if the --no-frames option is
270 used, then index.html is a copy of the API docu‐
271 mentation home page, which is normally the docu‐
272 mentation page for the top-level package or mod‐
273 ule (or the trees page if there is no top-level
274 package or module).
275 module-module.html
277 The API documentation for a module. module is
278 the complete dotted name of the module, such as
279 sys or epydoc.epytext.
280 class-class.html
282 The API documentation for a class, exception, or
283 type. class is the complete dotted name of the
284 class, such as epydoc.epytext.Token or
285 array.ArrayType.
286 module-pysrc.html
288 A syntax-highlighted page containing the Python
289 source code for module. This page includes links
290 back to the API documentation pages.
291 module-tree.html
293 The module hierarchy.
294 class-tree.html
296 The class hierarchy. This page is only generated
297 if at least one class is documented.
298 INDICES
300 identifier-index.html
302 An index of all documented identifiers. If the
303 identifier index contains more than 3,000
304 entries, then it will be split into separate
305 pages for each letter, named identifier-index-
306 a.html, identifier-index-b.html, etc.
307 term-index.html
309 An index of all explicitly marked definitional
310 terms. This page is only generated if at least
311 one definition term is marked in a formatted doc‐
312 string.
313 bug-index.html
315 An index of all explicitly marked @bug fields.
316 This page is only generated if at least one @bug
317 field is listed in a formatted docstring.
318 todo-index.html
320 An index of all explicitly marked @todo fields.
321 This page is only generated if at least one @todo
322 field is listed in a formatted docstring.
323 changed-index.html
325 An index of all explicitly marked @changed
326 fields. This page is only generated if at least
327 one @changed field is listed in a formatted doc‐
328 string.
329 deprecated-index.html
331 An index of all explicitly marked @deprecated
332 fields. This page is only generated if at least
333 one @deprecated field is listed in a formatted
334 docstring.
335 since-index.html
337 An index of all explicitly marked @since fields.
338 This page is only generated if at least one
339 @since field is listed in a formatted docstring.
340 FRAMES-BASED TABLE OF CONTENTS
342 frames.html
344 The main frames file. Two frames on the left
345 side of the window contain a table of contents,
346 and the main frame on the right side of the win‐
347 dow contains API documentation pages.
348 toc.html
350 The top-level table of contents page. This page
351 is displayed in the upper-left frame of
352 frames.html, and provides links to the toc-every‐
353 thing.html and toc-module-module.html pages.
354 toc-everything.html
356 The table of contents for the entire project.
357 This page is displayed in the lower-left frame of
358 frames.html, and provides links to every class,
359 type, exception, function, and variable defined
360 by the project.
361 toc-module-module.html
363 The table of contents for a module. This page is
364 displayed in the lower-left frame of frames.html,
365 and provides links to every class, type, excep‐
366 tion, function, and variable defined by the mod‐
367 ule. module is the complete dotted name of the
368 module, such as sys or epydoc.epytext.
369 OTHER PAGES
371 help.html
373 The help page for the project. This page
374 explains how to use and navigate the webpage pro‐
375 duced by epydoc.
376 redirect.html
378 This page uses javascript to translate dotted
379 names to their corresponding URLs. For example,
380 in epydoc's documentation, loading the page <re‐
381 direct.html#epydoc.apidoc.DottedName> will auto‐
382 matically redirect the browser to <epydoc.apidoc-
383 module.html#DottedName>.
384 epydoc.css
386 The CSS stylesheet used to display all HTML
387 pages.
388 epydoc.js
390 A javascript file used to define javascript func‐
391 tions used by epydoc.
392 epydoc-log.html
394 A page containing a log of all warnings and
395 errors that were generated by epydoc, along with
396 a table listing all of the options that were
397 used.
398
400 The LaTeX API documentation produced by epydoc consists of
401 the following files:
402 api.pdf
404 An Adobe Acrobat (pdf) file containing the com‐
405 plete API documentation. This file is only gen‐
406 erated if you use the --pdf option.
407 api.tex
409 The top-level LaTeX file. This file imports the
410 other LaTeX files, to create a single unified
411 document.
412 api.dvi
414 A dvi file containing the complete API documenta‐
415 tion. This file is only generated if you use the
416 --dvi option, the --ps option, or the --pdf
417 option.
418 api.ps A postscript file containing the complete API
420 documentation. This file is only generated if
421 you use the --ps option or the --pdf option.
422 module-module.tex
424 The API documentation for a module. module is
425 the complete dotted name of the module, such as
426 sys or epydoc.epytext.
427 class-class.tex
429 The API documentation for a class, exception, or
430 type. class is the complete dotted name of the
431 class, such as epydoc.epytext.Token or
432 array.ArrayType. These class documentation files
433 are only created if the --separate-classes option
434 is used; otherwise, the documentation for each
435 class is included in its module's documentation
436 file.
437
439 EPYTEXT MARKUP WARNING MESSAGES
440 Epytext errors are caused by epytext docstrings that
441 contain invalid markup. Whenever an epytext error is
442 detected, the docstring in question is treated as a
443 plaintext docstring. Epydoc can generate the following
444 epytext errors:
445 Bad link target.
447 The target specified for an inline link contruc‐
448 tion (L{...}) is not well-formed. Link targets
449 must be valid python identifiers.
450 Bad uri target.
452 The target specified for an inline uri contruc‐
453 tion (U{...}) is not well-formed. This typically
454 occurs if inline markup is nested inside the URI
455 target.
456 Fields must be at the top level.
458 The list of fields (@param, etc.) is contained
459 by some other block structure (such as a list or
460 a section).
461 Fields must be the final elements.
463 The list of fields (@param, etc.) is not at the
464 end of a docstring.
465 Headings must occur at top level.
467 The heading is contianed in some other block
468 structure (such as a list).
469 Improper doctest block indentation.
471 The doctest block dedents past the indentation of
472 its initial prompt line.
473 Improper heading indentation.
475 The heading for a section is not left-aligned
476 with the paragraphs in the section that contains
477 it.
478 Improper paragraph indentation.
480 The paragraphs within a block are not left-
481 aligned. This error is often generated when
482 plaintext docstrings are parsed using epytext.
483 Invalid escape.
485 An unknown escape sequence was used with the
486 inline escape construction (E{...}).
487 Lists must be indented.
489 An unindented line immediately following a para‐
490 graph starts with a list bullet. Epydoc is not
491 sure whether you meant to start a new list item,
492 or meant for a paragraph to include a word that
493 looks like a bullet. If you intended the former,
494 then indent the list. If you intended the lat‐
495 ter, then change the word-wrapping of the para‐
496 graph, or escape the first character of the word
497 that looks like a bullet.
498 Unbalanced '{'.
500 The docstring contains unbalanced braces. Epy‐
501 text requires that all braces must be balanced.
502 To include a single unbalanced brace, use the
503 escape sequences E{lb} (left brace) and E{rb}
504 (right brace).
505 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 Unknown inline markup tag.
514 An unknown tag was used with the inline markup
515 construction ( x{...} ).
516 Wrong underline character for heading.
518 The underline character used for this section
519 heading does not indicate an appopriate section
520 level. The "=" character should be used to
521 underline sections; "-" for subsections; and "~"
522 for subsubsections.
523 Possible mal-formatted field item.
525 Epytext detected a line that looks like a field
526 item, but is not correctly formatted. This typi‐
527 cally occurs when the trailing colon (":") is not
528 included in the field tag.
529 Possible heading typo.
531 Epytext detected a pair of lines that looks like
532 a heading, but the number of underline characters
533 does not match the number of characters in the
534 heading. The number of characters in these two
535 lines must match exactly for them to be consid‐
536 ered a heading.
537 FIELD WARNINGS
539 Field warnings are caused by docstrings containing
540 invalid fields. The contents of the invalid field are
541 generally ignored. Epydoc can generate the following
542 field warnings:
543 @param for unknown parameter param.
545 A @param field was used to specify the type for a
546 parameter that is not included in the function's
547 signature. This is typically caused by a typo in
548 the parameter name.
549 tag did not expect an argument.
551 The field tag tag was used with an argument, but
552 it does not take one.
553 tag expected an argument.
555 The field tag tag was used without an argument,
556 but it requires one.
557 @type for unknown parameter param.
559 A @type field was used to specify the type for a
560 parameter that is not included in the function's
561 signature. This is typically caused by a typo in
562 the parameter name.
563 @type for unknown variable var.
565 A @type field was used to specify the type for a
566 variable, but no other information is known about
567 the variable. This is typically caused by a typo
568 in the variable name.
569 Unknown field tag tag.
571 A docstring contains a field with the unknown tag
572 tag.
573 Redefinition of field.
575 Multiple field tags define the value of field in
576 the same docstring, but field can only take a
577 single value.
578
580 epydoc -n epydoc -u http://epydoc.sf.net epydoc/
581 Generate the HTML API documentation for the epydoc
582 package and all of its submodules, and write the out‐
583 put to the html directory. In the headers and foot‐
584 ers, use epydoc as the project name, and http://epy‐
585 doc.sf.net as the project URL.
586 epydoc --pdf -n epydoc epydoc/
588 Generate the LaTeX API documentation for the epydoc
589 package and all of its submodules, and write the out‐
590 put to the latex directory.
591
593 0 Successful program execution.
594 1 Usage error.
596 2 Epydoc generated an error or warning, and one of the
598 options --fail-on-error, --fail-on-warning, or
599 --fail-on-docstring-warning was specified.
600 other Internal error (Python exception).
602
604 Epydoc was written by Edward Loper. This man page was orig‐
605 inally written by Moshe Zadka, and is currently maintained
606 by Edward Loper.
607
609 Report bugs to <edloper@users.sourceforge.net>.
610
612 epydocgui(1)
613 The epydoc webpage
615 <http://epydoc.sourceforge.net>
616 The epytext markup language manual
618 <http://epydoc.sourceforge.net/epytext.html>
619 EPYDOC(1)