# Using Epydoc

## Command Line Interface

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...

``MODULES...``
  A list of the modules that should be documented. Modules can be specified using module names (such as "`os.path`"), filenames (such as "`epydoc/epytext.py`"), or directory names (such as "`epydoc/`"). Directory names specify packages, and are expanded to include all sub-modules and sub-packages.
`--html`
  Generate HTML output. (default)
`--pdf`
  Generate Adobe Acrobat (PDF) output, using LaTeX.
`-o `DIR``, `--output `DIR``, `--target `DIR``
  The output directory.
`-n `NAME``, `--name `NAME``
  The documented project's name.
`-v`, `-q`
  Increase (`-v`) or decrease (`-q`) the verbosity of the output.
`-u `URL``, `--url `URL``
  The documented project's URL.
`-t `PAGE``, `--top `PAGE``
  The "top page" for the HTML documentation. `PAGE` can be the name of a module or class; a URL; `"trees.html"`; `"indices.html"`; or `"help.html"`.
`-c `SHEET``, `--css `SHEET``
  CSS stylesheet for HTML files containing public documentation. `SHEET` can be a filename, or the name of a built-in stylesheet. For a list of the built-in stylesheets, run "`epydoc --help css`".
`--private-css `SHEET``
  CSS stylesheet for HTML files containing private documentation.
`--private`, `--no-private`
  Specify whether documentation should be generated for private objects. By default, documentation is generated for private objects in the HTML output, but not in the PDF output.
`--inheritance `STYLE``
  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:
  - `grouped`: Inherited objects are gathered into groups, based on which class they are inherited from. (default for HTML output)
  - `listed`: Inherited objects are listed in a short list at the end of the summary table. (default for PDF output)
  - `included`: Inherited objects are mixed in with non-inherited objects.

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.

## Graphical Interface

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.

Use the "Add" box to specify what modules you wish to document. You can specify modules using filenames (such as "`epydoc/epytext.py`") or module names (such as "`os.path`"). Once you have added all of the modules that you wish to document, press the "Go!" button. Epydoc's progress will be displayed on the progress bar.

To specify the package's name and URL, the output directory, and the CSS stylesheet, 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.

The epydoc graphical interface can save and load "project files", which record the set of modules and the options that you have selected. Select "`File→Save`" to save the current modules and options to a project file; and "`File→Open`" to open a previously saved project file.

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

## Documentation Completeness Checks

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...

``MODULES...``
  A list of the modules that should be checked. Modules may be specified using either filenames (such as "`epydoc/epytext.py`") or module names (such as "`os.path`"). The filename for a package is its "`__init__.py`" file.
`-p`
  Run documentation completeness checks on private objects.

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.

## HTML Files

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.

## CSS Stylesheets

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.

## Errors

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

[Epydoc] | [Installing] | [Epytext] | [Author] |

Last modified: Sun Jul 20 14:13:56 XXX 2003