Using Epydoc

The epydoc script can be used to create API documentation for a set of modules and packages:

epydoc [--html|--pdf] [-o DIR] [-n NAME] [-v|-q] [-u URL] [-t PAGE] 
       [-c SHEET]  [--private-css SHEET]   [--private|--no-private] 
       [--inheritance STYLE] MODULES...

For example, the following commands are used to produce the API documentation for epydoc itself:

[epydoc]$ epydoc -o api  --css blue  --private-css green -v \
                 -n epydoc -u http://epydoc.sourceforge.net \
                 --inheritance listed src/epydoc
[epydoc]$ epydoc -o latex_api --pdf -n "Epydoc 2.0" src/epydoc

Note that all options must preceed the list of modules. The usage description above does not include all options; for a complete description of the command line usage for epydoc, see the epydoc(1) man page.

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 epydocgui command, or with epydoc.pyw in the Scripts subdirectory of the Python installation directory under Windows.

For more information, see the epydocgui(1) man page.

The epydoc 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 "-p" option is used, then these checks are run on both public and private objects; otherwise, the checks are only run on public objects.

epydoc --check [-p] MODULES...

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:

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

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 DocChecker class directly.

Epydoc creates two subdirectories, for the public and private documentation. Within each subdirectory, every module and class is documented in its own file. An index file, a trees file, a help file, and a frames-based table of contents are also created. The following list describes each of the files generated by epydoc:

• index.html The standard entry point for the documentation. Normally, index.html is a copy of the frames file (frames.html). But if the --no-frames option is used, then index.html 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).
• module-module.html The API documentation for a module. module is the complete dotted name of the module, such as sys or epydoc.epytext.
• class-class.html 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.
• trees.html The module and class hierarchies.
• indices.html The term and identifier indices.
• help.html The help page for the project. This page explains how to use and navigate the webpage produced by epydoc.
• frames.html 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.
• toc.html The top-level table of contents page. This page is displayed in the upper-left frame of frames.html, and provides links to the toc-everything.html and toc-module-module.html pages.
• toc-everything.html The table of contents for the entire project. This page is displayed in the lower-left frame of frames.html, and provides links to every class, type, exception, function, and variable defined by the project.
• toc-module-module.html The table of contents for a module. This page is displayed in the lower-left frame of frames.html, 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.
• epydoc.css The CSS stylesheet used to display all HTML pages.

Epydoc creates a CSS stylesheet (epydoc.css) when it builds the API documentation for a project. You can specify which stylesheet should be used using the -c 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 default stylesheet.

For a description of the errors that can be generated by epydoc, see the epydoc(1) man page.

[Epydoc]

[Installing]

[Epytext]

[Author]