1EPYDOC(1) General Commands Manual EPYDOC(1)
2
6 epydoc - generate API documentation from Python docstrings
7
9 epydoc [--html | --latex | --dvi | --ps | --pdf] [-o dir] [--docformat
10 format] [-n name] [-u url] [-t page] [-c sheet] [--private-css
11 sheet] [--navlink html] [--help-file file] [--private]
12 [--no-private] [--inheritance style] [--show-imports]
13 [--builtins] [--ignore-param-mismatch] [--separate-classes] [-q]
14 [-v] modules...
15 epydoc --check [--tests tests] [--private] [--builtins]
17 [--ignore-param-mismatch] [-q] [-v] modules...
18 epydoc -h [topic]
20 epydoc -V
22
24 epydoc generates API documentation for Python modules and packages,
25 based on their docstrings. A lightweight markup language called epy‐
26 text can be used to format docstrings, and to add information about
27 specific fields, such as parameters and instance variables. Epydoc
28 also understands docstrings written in ReStructuredText, Javadoc, and
29 plaintext. Currently, epydoc supports two basic output formats: HTML
30 and LaTeX.
31 The HTML API documentation produced by epydoc consists of a set of HTML
33 files. Two subdirectories are created for the public and private docu‐
34 mentation. Within each subdirectory, every class and module is docu‐
35 mented in its own file. An index file, a trees file, a help file, and
36 a frames-based table of contents are also created.
37 The LaTeX API documentation produced by epydoc consists of a main LaTeX
39 file, and a LaTeX file for each module. If you use the --dvi, --ps, or
40 --pdf options, then epydoc will invoke external commands to convert the
41 LaTeX output to the requested format. Note that the LaTeX files con‐
42 taining the documentation for individual modules can be included as
43 chapters or sections of other LaTeX documents, using the LaTeX \include
44 command. If you wish to include individual classes in other LaTeX doc‐
45 uments, then use the --separate-classes option to produce a separate
46 LaTeX file for each class.
47 epydoc can also be used to check the completeness of the API documenta‐
49 tion. By default, it checks that every public package, module, class,
50 method, and function has a docstring description. The --tests option
51 can be used to specify additional tests to perform.
52
54 Options are divided into five categories: action selection options;
55 HTML documentation generation options; LaTeX documentation generation
56 options; documentation checking options; and other options. All
57 options must preceed the list of modules.
58 ACTION SELECTION OPTIONS
60 --html Generate HTML output. (default)
62 --latex
64 Generate LaTeX output.
65 --dvi Generate dvi output. This option first creates LaTeX out‐
67 put, and then uses latex and makeindex to convert the LaTeX
68 files into a single dvi file.
69 --ps Generate postscript output. This option first creates LaTeX
71 output, and then uses latex, makeindex, and dvips to convert
72 the LaTeX files into a single postscript file.
73 --pdf Generate Adobe Acrobat (pdf) output. This option first cre‐
75 ates LaTeX output, and then uses latex, makeindex, dvips,
76 and ps2pdf to convert the LaTeX files into a single pdf
77 file.
78 --check
80 Perform completeness checks on the documentation.
81 HTML DOCUMENTATION GENERATION OPTIONS
83 modules...
85 The list of the modules that should be documented. Modules
86 can be specified using module names (such as os.path), file‐
87 names (such as epydoc/epytext.py), or directory names (such
88 as epydoc/). Directory names specify packages, and are
89 expanded to include all sub-modules and sub-packages.
90 --builtins
92 Add the builtin modules (as defined by sys.builtin_mod‐
93 ule_names) to the list of modules to document.
94 -c sheet, --css sheet
96 CSS stylesheet for HTML files containing public API documen‐
97 tation. If sheet is a file, then the stylesheet is copied
98 from that file; otherwise, sheet is taken to be the name of
99 a built-in stylesheet. For a list of the built-in
100 stylesheets, run epydoc --help css. If a CSS stylesheet is
101 not specified, then the default stylesheet is used.
102 --docformat format
104 Set the default value for __docformat__ to format. __doc‐
105 format__ is a module variable that specifies the markup lan‐
106 guage for the docstrings in a module. Its value consists of
107 the name of a markup language, optionally followed by a lan‐
108 guage code (such as en for English). For a list of the
109 markup languages currently recognized by epydoc, run epydoc
110 --help docformat.
111 --help-file file
113 A file containing the body of the help page for the HTML
114 output. Navigation bars will be added at the top and bottom
115 of this help file. If no file is specified, then a default
116 help file is used.
117 --ignore-param-mismatch
119 Do not issue warnings when a method's parameters do not
120 match the parameters of the base class method that it over‐
121 rides.
122 --inheritance format
124 The format that should be used to display inherited methods,
125 variables, and properties in the "summary" tables. If for‐
126 mat is "grouped," then inherited objects are gathered into
127 groups, based on which class that they are inherited from.
128 If format is "listed," then inherited objects are listed in
129 a short list at the end of the summary table. If format is
130 "included," then inherited objects are mixed in with non-
131 inherited objects. The default format for HTML output is
132 "grouped."
133 -n name, --name name
135 The name of the project whose documentation is being gener‐
136 ated. This is used in the index page's title, and in the
137 help page. It is also used to create the homepage link on
138 the navigation bar, if the --navlink option is not used.
139 --navlink html
141 HTML code for the homepage link on the navigation bar. If
142 this HTML code contains any hyperlinks (<a href=...>), then
143 it will be inserted verbatim. If it does not contain any
144 hperlinks, and a project url is specified (with --url), then
145 a hyperlink to the specified URL is added to the link.
146 --no-frames
148 Do not display the frames-based table of contents on the
149 main API documentation page (index.html). This option just
150 changes the default view; the user can still access the
151 frames-based table of contents by clicking on frames in the
152 navigation bar.
153 -o dir, --output dir, --target dir
155 The output directory for HTML files. By default, HTML files
156 are written to the html directory.
157 --private, --no-private
159 These options control whether documentation is generated for
160 private objects. By default, HTML documentation includes
161 private objects, and users can choose whether to view pri‐
162 vate objects or not, by clicking on "show private" and "hide
163 private" links. But if you want to discourage users from
164 directly accessing private objects, then you may prefer not
165 to generate documentation for private objects. The
166 --no-private option is also useful if you want to generate
167 documentation more quickly, since epydoc will only need to
168 produce half as many HTML pages.
169 --private-css sheet
171 CSS stylesheet for HTML files containing private API docu‐
172 mentation. If sheet is a file, then the stylesheet is
173 copied from that file; otherwise, sheet is taken to be the
174 name of a built-in stylesheet. For a list of the built-in
175 stylesheets, run epydoc --help css. If a CSS stylesheet is
176 not specified, then epydoc copies the stylesheet for public
177 API documentation (see --css).
178 -q, --quiet
180 Produce quiet output. If -q is used multiple times, it pro‐
181 duces successively more quiet output (by suppressing warning
182 messages).
183 --show-imports
185 Include a list of the classes, functions, and variables that
186 each module imports on the module documentation pages.
187 -t page, --top page
189 The top page for the documentation. page can be the name of
190 a documented module or a class; the name of a file contain‐
191 ing a documented module; an absolute URL (starting with
192 "http:"); or one of the special names trees.html,
193 indices.html, or help.html, indicating the corresponding API
194 documentation pages.
195 -u url, --url url
197 The URL of the project's homepage. This URL is used by the
198 homepage link on the navigation bar.
199 -v, --verbose
201 Produce verbose output. If -v is used multiple times, it
202 produces successively more verbose output.
203 LATEX DOCUMENTATION GENERATION OPTIONS
205 LaTeX documentation generation options are used when producing
206 LaTeX, postscript (ps), or pdf output.
207 modules...
209 The list of the modules that should be documented. Modules
210 can be specified using module names (such as os.path), file‐
211 names (such as epydoc/epytext.py), or directory names (such
212 as epydoc/). Directory names specify packages, and are
213 expanded to include all sub-modules and sub-packages.
214 --builtins
216 Add the builtin modules (as defined by sys.builtin_mod‐
217 ule_names) to the list of modules to document.
218 --docformat format
220 Set the default value for __docformat__ to format. __doc‐
221 format__ is a module variable that specifies the markup lan‐
222 guage for the docstrings in a module. Its value consists of
223 the name of a markup language, optionally followed by a lan‐
224 guage code (such as en for English). For a list of the
225 markup languages currently recognized by epydoc, run epydoc
226 --help docformat.
227 --ignore-param-mismatch
229 Do not issue warnings when a method's parameters do not
230 match the parameters of the base class method that it over‐
231 rides.
232 --inheritance format
234 The format that should be used to display inherited methods,
235 variables, and properties. If format is "grouped," then
236 inherited objects are gathered into groups, based on which
237 class that they are inherited from. If format is "listed,"
238 then inherited objects are listed in a short list at the end
239 of their section. If format is "included," then inherited
240 objects are mixed in with non-inherited objects. The
241 default format for LaTeX output is "listed."
242 -n name, --name name
244 The name of the project whose documentation is being gener‐
245 ated. This is used on the title page, in the page header,
246 and in the pdf metadata.
247 -o dir, --output dir, --target dir
249 The output directory. By default, HTML files are written to
250 the html directory, and LaTeX files are written to the latex
251 directory.
252 --private, --no-private
254 These options control whether documentation is generated for
255 private objects. By default, LaTeX output only includes
256 documentation for public objects.
257 -q, --quiet
259 Produce quiet output. If -q is used multiple times, it pro‐
260 duces successively more quiet output (by suppressing warning
261 messages).
262 --separate-classes
264 Describe all classes in a separate section of the documenta‐
265 tion, instead of including them in the documentation for
266 their modules. This creates a separate LaTeX file for each
267 class, so it can also be useful if you want to include the
268 documentation for one or two classes as sections of your own
269 LaTeX document.
270 -v, --verbose
272 Produce verbose output. If -v is used multiple times, it
273 produces successively more verbose output.
274 DOCUMENTATION COMPLETENESS CHECKING OPTIONS
276 The --check option is used to perform completeness checks on the
277 documentation of your project. By default, epydoc checks to make
278 sure that all public objects have docstrings. Additional checks
279 can be added with the --tests option.
280 modules...
282 The list of the modules whose documentation should be
283 checked. Modules can be specified using module names (such
284 as os.path), filenames (such as epydoc/epytext.py), or
285 directory names (such as epydoc/). Directory names specify
286 packages, and are expanded to include all sub-modules and
287 sub-packages.
288 --ignore-param-mismatch
290 Do not issue warnings when a method's parameters do not
291 match the parameters of the base class method that it over‐
292 rides.
293 --private
295 Perform checks on private objects
296 -q, --quiet
298 Produce quiet output. If -q is used multiple times, it pro‐
299 duces successively more quiet output (by suppressing warning
300 messages).
301 --tests tests, --checks tests
303 Perform additional tests on the documentation. For a list
304 of the additional tests that are available, run epydoc
305 --help tests.
306 -v, --verbose
308 Produce verbose output. If -v is used multiple times, it
309 produces successively more verbose output.
310 OTHER OPTIONS
312 -h, --help, --usage, -?
314 Display a usage message.
315 -h topic, --help topic
317 Display information about a specific topic. Currently,
318 information is available about the following topics: css,
319 version, and usage.
320 -V, --version
322 Print the version of Epydoc.
323
325 epydoc -n epydoc -u http://epydoc.sf.net epydoc/
326 Generate the HTML API documentation for the epydoc package and
327 all of its submodules, and write the output to the html direc‐
328 tory. In the headers and footers, use epydoc as the project
329 name, and http://epydoc.sf.net as the project URL.
330 epydoc --pdf -n epydoc epydoc/
332 Generate the LaTeX API documentation for the epydoc package and
333 all of its submodules, and write the output to the latex direc‐
334 tory.
335 epydoc -o api --css blue --private-css green sys
337 Generate API documentation for the sys module, and write the
338 output to the api directory. Use different stylesheets for the
339 public and private versions of the documentation.
340
342 The HTML API documentation produced by epydoc consists of the following
343 files:
344 index.html
346 The standard entry point for the documentation. Normally,
347 index.html is a copy of the frames file (frames.html). But
348 if the --no-frames option is used, then index.html is a copy
349 of the API documentation home page, which is normally the
350 documentation page for the top-level package or module (or
351 the trees page if there is no top-level package or module).
352 module-module.html
354 The API documentation for a module. module is the complete
355 dotted name of the module, such as sys or epydoc.epytext.
356 class-class.html
358 The API documentation for a class, exception, or type.
359 class is the complete dotted name of the class, such as epy‐
360 doc.epytext.Token or array.ArrayType.
361 trees.html
363 The module and class hierarchies.
364 indices.html
366 The term and identifier indices.
367 help.html
369 The help page for the project. This page explains how to
370 use and navigate the webpage produced by epydoc.
371 frames.html
373 The main frames file. Two frames on the left side of the
374 window contain a table of contents, and the main frame on
375 the right side of the window contains API documentation
376 pages.
377 toc.html
379 The top-level table of contents page. This page is dis‐
380 played in the upper-left frame of frames.html, and provides
381 links to the toc-everything.html and toc-module-module.html
382 pages.
383 toc-everything.html
385 The table of contents for the entire project. This page is
386 displayed in the lower-left frame of frames.html, and pro‐
387 vides links to every class, type, exception, function, and
388 variable defined by the project.
389 toc-module-module.html
391 The table of contents for a module. This page is displayed
392 in the lower-left frame of frames.html, and provides links
393 to every class, type, exception, function, and variable
394 defined by the module. module is the complete dotted name
395 of the module, such as sys or epydoc.epytext.
396 epydoc.css
398 The CSS stylesheet used to display all HTML pages.
399 By default, epydoc creates two subdirectories in the output directory:
401 public and private. Each directory contains all of the files specified
402 above. But if the --no-private option is used, then no subdirectories
403 are created, and the public documentation is written directly to the
404 output directory.
405
407 The LaTeX API documentation produced by epydoc consists of the follow‐
408 ing files:
409 api.pdf
411 An Adobe Acrobat (pdf) file containing the complete API doc‐
412 umentation. This file is only generated if you use the
413 --pdf option.
414 api.tex
416 The top-level LaTeX file. This file imports the other LaTeX
417 files, to create a single unified document.
418 api.dvi
420 A dvi file containing the complete API documentation. This
421 file is only generated if you use the --dvi option, the --ps
422 option, or the --pdf option.
423 api.ps A postscript file containing the complete API documentation.
425 This file is only generated if you use the --ps option or
426 the --pdf option.
427 module-module.tex
429 The API documentation for a module. module is the complete
430 dotted name of the module, such as sys or epydoc.epytext.
431 class-class.tex
433 The API documentation for a class, exception, or type.
434 class is the complete dotted name of the class, such as epy‐
435 doc.epytext.Token or array.ArrayType. These class documen‐
436 tation files are only created if the --separate-classes
437 option is used; otherwise, the documentation for each class
438 is included in its module's documentation file.
439
441 Errors are divided into five categories: import errors; epytext errors;
442 epytext warnings; field warnings; and inspection errors. Whenver epy‐
443 doc encounters an error, it issues a warning message that describes the
444 error, and attempts to continue generating documentation.
445 Import errors indicate that epydoc was unable to import a module.
447 Import errors typically prevent epydoc from generating documentation
448 for the module in question. Epydoc can generate the following import
449 errors:
450 Bad module name module
452 Epydoc attempted to import module, but module is not a valid
453 name for a Python module.
454 Could not find a UID for link-target
456 Epydoc was unable to find the object referred to by an
457 inline link construction (L{...}). This is usually caused
458 by a typo in the link.
459 Could not import module
461 Epydoc attempted to import module, but it failed. This typ‐
462 ically occurs when module raises an exception.
463 file does not exist
465 Epydoc attempted to import the module contained in file, but
466 file does not exist.
467 Epytext errors are caused by epytext docstrings that contain invalid
469 markup. Whenever an epytext error is detected, the docstring in ques‐
470 tion is treated as a plaintext docstring. Epydoc can generate the fol‐
471 lowing epytext errors:
472 Bad link target.
474 The target specified for an inline link contruction (L{...})
475 is not well-formed. Link targets must be valid python iden‐
476 tifiers.
477 Bad uri target.
479 The target specified for an inline uri contruction (U{...})
480 is not well-formed. This typically occurs if inline markup
481 is nested inside the URI target.
482 Fields must be at the top level.
484 The list of fields (@param, etc.) is contained by some
485 other block structure (such as a list or a section).
486 Fields must be the final elements.
488 The list of fields (@param, etc.) is not at the end of a
489 docstring.
490 Headings must occur at top level.
492 The heading is contianed in some other block structure (such
493 as a list).
494 Improper doctest block indentation.
496 The doctest block dedents past the indentation of its ini‐
497 tial prompt line.
498 Improper heading indentation.
500 The heading for a section is not left-aligned with the para‐
501 graphs in the section that contains it.
502 Improper paragraph indentation.
504 The paragraphs within a block are not left-aligned. This
505 error is often generated when plaintext docstrings are
506 parsed using epytext.
507 Invalid escape.
509 An unknown escape sequence was used with the inline escape
510 construction (E{...}).
511 Lists must be indented.
513 An unindented line immediately following a paragraph starts
514 with a list bullet. Epydoc is not sure whether you meant to
515 start a new list item, or meant for a paragraph to include a
516 word that looks like a bullet. If you intended the former,
517 then indent the list. If you intended the latter, then
518 change the word-wrapping of the paragraph, or escape the
519 first character of the word that looks like a bullet.
520 Unbalanced '{'.
522 The docstring contains unbalanced braces. Epytext requires
523 that all braces must be balanced. To include a single
524 unbalanced brace, use the escape sequences E{lb} (left
525 brace) and E{rb} (right brace).
526 Unbalanced '}'.
528 The docstring contains unbalanced braces. Epytext requires
529 that all braces must be balanced. To include a single
530 unbalanced brace, use the escape sequences E{lb} (left
531 brace) and E{rb} (right brace).
532 Unknown inline markup tag.
534 An unknown tag was used with the inline markup construction
535 ( x{...} ).
536 Wrong underline character for heading.
538 The underline character used for this section heading does
539 not indicate an appopriate section level. The "=" character
540 should be used to underline sections; "-" for subsections;
541 and "~" for subsubsections.
542 Epytext warnings are caused by epytext docstrings that contain ques‐
544 tionable or suspicious markup. Epytext warnings do not prevent the
545 docstring in question from being parsed. Epydoc can generate the fol‐
546 lowing epytext warnings:
547 Possible mal-formatted field item.
549 Epytext detected a line that looks like a field item, but is
550 not correctly formatted. This typically occurs when the
551 trailing colon (":") is not included in the field tag.
552 Possible heading typo.
554 Epytext detected a pair of lines that looks like a heading,
555 but the number of underline characters does not match the
556 number of characters in the heading. The number of charac‐
557 ters in these two lines must match exactly for them to be
558 considered a heading.
559 Field warnings are caused by epytext docstrings containing invalid
561 fields. The contents of the invalid field are generally ignored. Epy‐
562 doc can generate the following field warnings:
563 @param for unknown parameter param.
565 A @param field was used to specify the type for a parameter
566 that is not included in the function's signature. This is
567 typically caused by a typo in the parameter name.
568 tag did not expect an argument.
570 The field tag tag was used with an argument, but it does not
571 take one.
572 tag expected an argument.
574 The field tag tag was used without an argument, but it
575 requires one.
576 @type for unknown parameter param.
578 A @type field was used to specify the type for a parameter
579 that is not included in the function's signature. This is
580 typically caused by a typo in the parameter name.
581 @type for unknown variable var.
583 A @type field was used to specify the type for a variable,
584 but no other information is known about the variable. This
585 is typically caused by a typo in the variable name.
586 Unknown field tag tag.
588 A docstring contains a field with the unknown tag tag.
589 Redefinition of field.
591 Multiple field tags define the value of field in the same
592 docstring, but field can only take a single value.
593 Inspection errors are generated if epydoc encounters problems while
595 attempting to inspect the properties of a documented object. Most of
596 inspection errors do not prevent epydoc from documenting the object in
597 question. Epydoc can generate the following inspection errors:
598 The parameters of inhmethod do not match basemethod.
600 The parameters of the undocumented method inhmethod do not
601 match the parameters of the base class method basemethod
602 that it overrides. As a result, inhmethod does not inherit
603 documentation from basemethod. If the difference in parame‐
604 ters is intentional, then you can eliminate the warning by
605 adding a (possibly empty) docstring to inhmethod.
606 Docmap cannot add a type
608 Epydoc attempted to document an object with an unknown type.
609 This error is typically generated by packages and modules
610 that manipulate the import mechanism, such that importing a
611 module produces some other type of object.
612 UID conflict detected: uid
614 Two different objects were assigned the same unique identi‐
615 fier by epydoc. This can cause epydoc to substitute the
616 documentation of one object with the documentation of
617 another object that is assigned the same unique identifier.
618 However, this will usually only cause problems if the two
619 objects with the same unique identifiers are both modules or
620 classes, in which case the API documentation page for one
621 object will overwrite the API documentation page for the
622 other object.
623 object appears in multiple builtin modules
625 While attempting to determine which module defines the
626 builtin object object, epydoc encountered multiple candi‐
627 dates, and was unable to decide which candidate was correct.
628 In this case, epydoc arbitrarily chooses the first candidate
629 that it finds.
630 object appears in multiple .py modules
632 While attempting to determine which module defines the
633 builtin object object, epydoc encountered multiple candi‐
634 dates, and was unable to decide which candidate was correct.
635 In this case, epydoc arbitrarily chooses the first candidate
636 that it finds.
637 object appears in multiple .so modules
639 While attempting to determine which module defines the
640 builtin object object, epydoc encountered multiple candi‐
641 dates, and was unable to decide which candidate was correct.
642 In this case, epydoc arbitrarily chooses the first candidate
643 that it finds.
644 Could not find a module for object
646 Epydoc was unable to determine which module defines object.
647 If object is a function, then this will prevent epydoc from
648 generating any documentation for object, since it does not
649 know what page to put the documentation on. Otherwise, this
650 will prevent the documentation for object from including a
651 link to its containing module.
652
654 0 Successful program execution.
655 1 Usage error.
657 other Internal error (Python exception).
659
661 Epydoc was written by Edward Loper. This man page was originally writ‐
662 ten by Moshe Zadka, and is currently maintained by Edward Loper.
663
665 Report bugs to <edloper@gradient.cis.upenn.edu>.
666
668 epydocgui(1)
669 The epydoc webpage
671 <http://epydoc.sourceforge.net>
672 The epytext markup language manual
674 <http://epydoc.sourceforge.net/epytext.html>
675 EPYDOC(1)