References

Command Line Usage

Usage: epydoc.py [ACTION] [options] NAMES...

NAMES...

A list of the Python objects that should be documented. Objects can be specified using dotted names (such as os.path), module filenames (such as epydoc/epytext.py), or package directory names (such as epydoc/). Packages are expanded to include all sub-modules and sub-packages.

options

--config=FILE         A configuration file, specifying additional OPTIONS
                      and/or NAMES.  This option may be repeated.
-o PATH, --output=PATH
                      The output directory.  If PATH does not exist, then it
                      will be created.
-q, --quiet           Decrease the verbosity.
-v, --verbose         Increase the verbosity.
--debug               Show full tracebacks for internal errors.
--simple-term         Do not try to use color or cursor control when
                      displaying the progress bar, warnings, or errors.

Actions:
  --html              Write HTML output.
  --text              Write plaintext output. (not implemented yet)
  --latex             Write LaTeX output.
  --dvi               Write DVI output.
  --ps                Write Postscript output.
  --pdf               Write PDF output.
  --check             Check completeness of docs.
  --pickle            Write the documentation to a pickle file.
  --version           Show epydoc's version number and exit.
  -h, --help          Show this message and exit.  For help on specific
                      topics, use "--help TOPIC".  Use "--help topics" for a
                      list of available help topics

Generation Options:
  --docformat=NAME    The default markup language for docstrings.  Defaults
                      to "epytext".
  --parse-only        Get all information from parsing (don't introspect)
  --introspect-only   Get all information from introspecting (don't parse)
  --exclude=PATTERN   Exclude modules whose dotted name matches the regular
                      expression PATTERN
  --exclude-introspect=PATTERN
                      Exclude introspection of modules whose dotted name
                      matches the regular expression PATTERN
  --exclude-parse=PATTERN
                      Exclude parsing of modules whose dotted name matches
                      the regular expression PATTERN
  --inheritance=STYLE
                      The format for showing inheritance objects.  STYLE
                      should be one of: grouped, listed, included.
  --show-private      Include private variables in the output. (default)
  --no-private        Do not include private variables in the output.
  --show-imports      List each module's imports.
  --no-imports        Do not list each module's imports. (default)
  --show-sourcecode   Include source code with syntax highlighting in the
                      HTML output. (default)
  --no-sourcecode     Do not include source code with syntax highlighting in
                      the HTML output.
  --include-log       Include a page with the process log (epydoc-log.html)

Output Options:
  --name=NAME         The documented project's name (for the navigation
                      bar).
  --css=STYLESHEET    The CSS stylesheet.  STYLESHEET can be either a
                      builtin stylesheet or the name of a CSS file.
  --url=URL           The documented project's URL (for the navigation bar).
  --navlink=HTML      HTML code for a navigation link to place in the
                      navigation bar.
  --top=PAGE          The "top" page for the HTML documentation.  PAGE can
                      be a URL, the name of a module or class, or one of the
                      special names "trees.html", "indices.html", or
                      "help.html"
  --help-file=FILE    An alternate help file.  FILE should contain the body
                      of an HTML file -- navigation bars will be added to
                      it.
  --show-frames       Include frames in the HTML output. (default)
  --no-frames         Do not include frames in the HTML output.
  --separate-classes  When generating LaTeX or PDF output, list each class
                      in its own section, instead of listing them under
                      their containing module.

API Linking Options:
  --external-api=NAME
                      Define a new API document.  A new interpreted text
                      role NAME will be added.
  --external-api-file=NAME:FILENAME
                      Use records in FILENAME to resolve objects in the API
                      named NAME.
  --external-api-root=NAME:STRING
                      Use STRING as prefix for the URL generated from the
                      API NAME.

Graph Options:
  --graph=GRAPHTYPE   Include graphs of type GRAPHTYPE in the generated
                      output.  Graphs are generated using the Graphviz dot
                      executable.  If this executable is not on the path,
                      then use --dotpath to specify its location.  This
                      option may be repeated to include multiple graph types
                      in the output.  GRAPHTYPE should be one of: all,
                      classtree, callgraph, umlclasstree.
  --dotpath=PATH      The path to the Graphviz 'dot' executable.
  --graph-font=FONT   Specify the font used to generate Graphviz graphs.
                      (e.g., helvetica or times).
  --graph-font-size=SIZE
                      Specify the font size used to generate Graphviz
                      graphs, in points.
  --pstat=FILE        A pstat output file, to be used in generating call
                      graphs.

Return Value Options:
  --fail-on-error     Return a non-zero exit status, indicating failure, if
                      any errors are encountered.
  --fail-on-warning   Return a non-zero exit status, indicating failure, if
                      any errors or warnings are encountered (not including
                      docstring warnings).
  --fail-on-docstring-warning
                      Return a non-zero exit status, indicating failure, if
                      any errors or warnings are encountered (including
                      docstring warnings).

Sample Configuration File

Configuration files, specified using the --config option, may be used to specify both the list of objects to document, and the options that should be used to document them. Configuration files are read using the standard ConfigParser module. The following example configuration file demonstrates the various options that you can set. Lines beginning with # or ; are treated as comments.

[epydoc] # Epydoc section marker (required by ConfigParser)

# The list of objects to document.  Objects can be named using
# dotted names, module filenames, or package directory names.
# Alases for this option include "objects" and "values".
modules: sys, os.path, re

# The type of output that should be generated.  Should be one
# of: html, text, latex, dvi, ps, pdf.
output: html

# The path to the output directory.  May be relative or absolute.
target: html/

# An integer indicating how verbose epydoc should be.  The default
# value is 0; negative values will supress warnings and errors;
# positive values will give more verbose output.
verbosity: 0

# A boolean value indicating that Epydoc should show a tracaback
# in case of unexpected error. By default don't show tracebacks
debug: 0

# If True, don't try to use colors or cursor control when doing
# textual output. The default False assumes a rich text prompt
simple-term: 0


### Generation options

# The default markup language for docstrings, for modules that do
# not define __docformat__.  Defaults to epytext.
docformat: epytext

# Whether or not parsing should be used to examine objects.
parse: yes

# Whether or not introspection should be used to examine objects.
introspect: yes

# Don't examine in any way the modules whose dotted name match this
# regular expression pattern.
#exclude

# Don't perform introspection on the modules whose dotted name match this
# regular expression pattern.
#exclude-introspect

# Don't perform parsing on the modules whose dotted name match this
# regular expression pattern.
#exclude-parse

# The format for showing inheritance objects.
# It should be one of: 'grouped', 'listed', 'included'.
inheritance: listed

# Whether or not to inclue private variables.  (Even if included,
# private variables will be hidden by default.)
private: yes

# Whether or not to list each module's imports.
imports: no

# Whether or not to include syntax highlighted source code in
# the output (HTML only).
sourcecode: yes

# Whether or not to includea a page with Epydoc log, containing
# effective option at the time of generation and the reported logs.
include-log: no


### Output options

# The documented project's name.
#name: Example

# The CSS stylesheet for HTML output.  Can be the name of a builtin
# stylesheet, or the name of a file.
css: white

# The documented project's URL.
#url: http://some.project/

# HTML code for the project link in the navigation bar.  If left
# unspecified, the project link will be generated based on the
# project's name and URL.
#link: <a href="somewhere">My Cool Project</a>

# The "top" page for the documentation.  Can be a URL, the name
# of a module or class, or one of the special names "trees.html",
# "indices.html", or "help.html"
#top: os.path

# An alternative help file.  The named file should contain the
# body of an HTML file; navigation bars will be added to it.
#help: my_helpfile.html

# Whether or not to include a frames-based table of contents.
frames: yes

# Whether each class should be listed in its own section when
# generating LaTeX or PDF output.
separate-classes: no


### API linking options

# Define a new API document.  A new interpreted text role
# will be created
#external-api: epydoc

# Use the records in this file to resolve objects in the API named NAME.
#external-api-file: epydoc:api-objects.txt

# Use this URL prefix to configure the string returned for external API.
#external-api-root: epydoc:http://epydoc.sourceforge.net/api


### Graph options

# The list of graph types that should be automatically included
# in the output.  Graphs are generated using the Graphviz "dot"
# executable.  Graph types include: "classtree", "callgraph",
# "umlclass".  Use "all" to include all graph types
graph: all

# The path to the Graphviz "dot" executable, used to generate
# graphs.
dotpath: /usr/local/bin/dot

# The name of one or more pstat files (generated by the profile
# or hotshot module).  These are used to generate call graphs.
pstat: profile.out

# Specify the font used to generate Graphviz graphs.
# (e.g., helvetica or times).
graph-font: Helvetica

# Specify the font size used to generate Graphviz graphs.
graph-font-size: 10


### Return value options

# The condition upon which Epydoc should exit with a non-zero
# exit status. Possible values are error, warning, docstring_warning
#fail-on: error

Customizing LaTeX and PDF Output

Epydoc's LaTeX output, and the outputs that are derived from it (dvi, ps, and pdf), can be customized by creating a custom LaTeX style file. To help you create custom stylesheets, a complete description of the specialized LaTeX commands that epydoc uses to generate its output is available here:

Epydoc LaTeX Style Reference

Additionaly, you may find it useful to look at the builtin style files that epydoc provides:

Warnings and Errors

If epydoc encounters an error while processing a docstring, it issues a warning message that describes the error, and attempts to continue generating documentation. Errors related to epytext are divided into three categories:

Epytext Warnings: are caused by epytext docstrings that contain questionable or suspicious markup. Epytext warnings do not prevent the docstring in question from being parsed.
Field Warnings: are caused by epytext docstrings containing invalid fields. The contents of the invalid field are generally ignored.
Epytext Errors: are caused by epytext docstrings that contain invalid markup. Whenever an epytext error is detected, the docstring in question is treated as a plaintext docstring.

The following sections list and describe the warning messages that epydoc can generate. They are intended as a reference resource, which you can search for more information and possible causes if you encounter an error and do not understand it. These descriptions are also available in the epydoc(1) man page.

Epytext Warnings

Possible mal-formatted field item.: Epytext detected a line that looks like a field item, but is not correctly formatted. This typically occurs when the trailing colon (:) is not included in the field tag.
Possible heading typo.: Epytext detected a pair of lines that looks like a heading, but the number of underline characters does not match the number of characters in the heading. The number of characters in these two lines must match exactly for them to be considered a heading.

Field Warnings

@param for unknown parameter param.: A @param field was used to specify the type for a parameter that is not included in the function's signature. This is typically caused by a typo in the parameter name.
tag did not expect an argument.: The field tag tag was used with an argument, but it does not take one.
tag expected an argument.: The field tag tag was used without an argument, but it requires one.
@type for unknown parameter param.: A @type field was used to specify the type for a parameter that is not included in the function's signature. This is typically caused by a typo in the parameter name.
@type for unknown variable var.: A @type field was used to specify the type for a variable, but no other information is known about the variable. This is typically caused by a typo in the variable name.
Unknown field tag tag.: A docstring contains a field with the unknown tag tag.
Redefinition of field.: Multiple field tags define the value of field in the same docstring, but field can only take a single value.

Epytext Errors

Bad link target.: The target specified for an inline link contruction (L{...}) is not well-formed. Link targets must be valid Python identifiers.
Bad uri target.: The target specified for an inline uri contruction (U{...}) is not well-formed. This typically occurs if inline markup is nested inside the URI target.
Fields must be at the top level.: The list of fields (@param, etc.) is contained by some other block structure (such as a list or a section).
Fields must be the final elements in an epytext string.: The list of fields (@param, etc.) is not at the end of a docstring.
Headings must occur at top level.: The heading is contianed in some other block structure (such as a list).
Improper doctest block indentation.: The doctest block dedents past the indentation of its initial prompt line.
Improper heading indentation.: The heading for a section is not left-aligned with the paragraphs in the section that contains it.
Improper paragraph indentation.: The paragraphs within a block are not left-aligned. This error is often generated when plaintext docstrings are parsed using epytext.
Invalid escape.: An unknown escape sequence was used with the inline escape construction (E{...}).
Lists must be indented.: An unindented line immediately following a paragraph starts with a list bullet. Epydoc is not sure whether you meant to start a new list item, or meant for a paragraph to include a word that looks like a bullet. If you intended the former, then indent the list. If you intended the latter, then change the word-wrapping of the paragraph, or escape the first character of the word that looks like a bullet.
Unbalanced '{'.: The docstring contains unbalanced braces. Epytext requires that all braces must be balanced. To include a single unbalanced brace, use the escape sequences E{lb} (left brace) and E{rb} (right brace).
Unbalanced '}'.: The docstring contains unbalanced braces. Epytext requires that all braces must be balanced. To include a single unbalanced brace, use the escape sequences E{lb} (left brace) and E{rb} (right brace).
Unknown inline markup tag.: An unknown tag was used with the inline markup construction (x{...}).
Wrong underline character for heading.: The underline character used for this section heading does not indicate an appopriate section level. The '=' character should be used to underline sections; '-' for subsections; and '~' for subsubsections.