DragonFly On-Line Manual Pages
EPYDOC(1) DragonFly General Commands Manual EPYDOC(1)
NAME
epydoc - generate API documentation from Python docstrings
SYNOPSIS
epydoc [action] [options] names...
DESCRIPTION
epydoc generates API documentation for Python modules and packages,
based on their docstrings. A lightweight markup language called
epytext can be used to format docstrings, and to add information about
specific fields, such as parameters and instance variables. Epydoc
also understands docstrings written in ReStructuredText, Javadoc, and
plaintext. Currently, epydoc supports two basic output formats: HTML
and LaTeX.
The HTML API documentation produced by epydoc consists of a set of HTML
files, including: an API documentation page for each class and module;
a syntax-highlighted source code page for each module; an identifier
index page; a help page; and a frames-based table of contents. When
appropriate, epydoc will also generate index pages for bugs, defined
terms, and to-do items; a class hierarchy page; and a package hierarchy
page.
The LaTeX API documentation produced by epydoc consists of a main LaTeX
file, and a LaTeX file for each module. If you use --dvi, --ps, or
--pdf , then epydoc will invoke external commands to convert the LaTeX
output to the requested format. Note that the LaTeX files containing
the documentation for individual modules can be included as chapters or
sections of other LaTeX documents, using the LaTeX \include command.
If you wish to include individual classes in other LaTeX documents,
then use the --separate-classes option to produce a separate LaTeX file
for each class.
epydoc can also be used to check the completeness of the API
documentation. By default, it checks that every public package,
module, class, method, and function has a docstring description. The
--tests option can be used to specify additional tests to perform.
OPTIONS
Epydoc's options are divided into six categories: basic options,
actions, generation options, output options, graph options, and return
value options.
BASIC OPTIONS
names...
The list of objects that should be documented. Objects can
be specified using Python dotted 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.
If you wish to exclude certain sub-modules or sub-packages,
use the --exclude option (described below).
--config file
A configuration file, specifying additional
optionsand/ornames. This option may be repeated.
--q, --quiet, --v, --verbose
Produce quite (or verbose) output. If used multiple times,
this option produces successively more quiet (or verbose)
output.
--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. [default]
--latex Write LaTeX output.
--dvi Write DVI output.
--ps Write Postscript output.
--pdf Write Adobe Acrobat (pdf) output.
--check Perform completeness checks on the documentation.
--pickle Write the documentation to a pickle file.
GENERATION OPTIONS
--docformat format
Set the default value for __docformat__ to format.
__docformat__ is a module variable that specifies the markup
language for the docstrings in a module. Its value consists
of the name of a markup language, optionally followed by a
language code (such as en for English). For a list of the
markup languages currently recognized by epydoc, run epydoc
--help docformat.
--parse-only
Gather all information about the documented objects by
parsing the relevant Python source code; in particular, do
not use introspection to gather information about the
documented objects. This option should be used when epydoc
is run on untrusted code; or on code that can not be
introspected because of missing dependencies, or because
importing it would cause undesired side-effects.
--introspect-only
Gather all information about the documented objects by
introspection; in particular, do not gather information by
parsing the object's Python source code.
--exclude PATTERN
Do not document any object whose name matches the given
regular expression pattern.
--exclude-introspect PATTERN
Do not use introspection to gather information about any
object whose name matches the given regular expression.
--exclude-parse PATTERN
Do not use Python source code parsing to gather information
about any object whose name matches the given regular
expression.
--inheritance format
The format that should be used to display inherited methods,
variables, and properties in the generated "summary" tables.
If format is "grouped," then inherited objects are gathered
into groups, based on which class that they are inherited
from. If format is "listed," then inherited objects are
listed in a short list at the end of the summary table. If
format is "included," then inherited objects are mixed in
with non-inherited objects. The default format for HTML
output is "grouped."
--show-private, --no-private
These options control whether documentation is generated for
private objects. By default, the generated documentation
includes private objects, and users can choose whether to
view private objects or not, by clicking on "show private"
and "hide private" links. But if you want to discourage
users from directly accessing private objects, then you may
prefer not to generate documentation for private objects.
--show-imports, --no-imports
These options control whether module imports are included in
the generated documentation. By default, imports are not
included.
--show-sourcecode, --no-sourcecode
These options control whether or not epydoc should generate
syntax-highlighted pages containing the souce code of each
module in the HTML output. By default, the sourcecode pages
are generated.
--include-log
Generate an HTML page epydoc-log.html containing all error
and warning messages that are generated by epydoc, and
include it in the generated output.
OUTPUT OPTIONS
-o dir, --output dir
The output directory. If dir does not exist, then it will
be created. If no output directory is specified, then the
action name (e.g., html or pdf). html
-c sheet, --css sheet
CSS stylesheet for HTML output files. If sheet is a file,
then the stylesheet is copied from that file; otherwise,
sheet is taken to be the name of a built-in stylesheet. For
a list of the built-in stylesheets, run epydoc --help css.
If a CSS stylesheet is not specified, then the default
stylesheet is used.
-n name, --name name
The name of the project whose documentation is being
generated.
-u url, --url url
The URL of the project's homepage.
--navlink html
HTML code for the homepage link on the HTML navigation bar.
If this HTML code contains any hyperlinks (<a href=...>),
then it will be inserted verbatim. If it does not contain
any hyperlinks, and a project url is specified (with --url),
then a hyperlink to the specified URL is added to the link.
--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, --no-frames
These options control whether HMTL output will include a
frames-base table of contents page. By default, the frames-
based table of contents is included.
--separate-classes
In the LaTeX output, describe each class in a separate
section of the documentation, instead of including them in
the documentation for their modules. This creates a
separate LaTeX file for each class, so it can also be useful
if you want to include the documentation for one or two
classes as sections of your own LaTeX document.
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, or
umlclasstree.
--dotpath path
The path to the Graphviz dot executable.
--graph-font font
The name of the font used to generate Graphviz graphs.
(e.g., helvetica or times).
--graph-font-size size
The size of the font 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).
HTML FILES
The HTML API documentation produced by epydoc consists of the following
files:
OBJECT DOCUMENTATION PAGES
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.
module-pysrc.html
A syntax-highlighted page containing the Python source code
for module. This page includes links back to the API
documentation pages.
module-tree.html
The module hierarchy.
class-tree.html
The class hierarchy. This page is only generated if at
least one class is documented.
INDICES
identifier-index.html
An index of all documented identifiers. If the identifier
index contains more than 3,000 entries, then it will be
split into separate pages for each letter, named
identifier-index-a.html, identifier-index-b.html, etc.
term-index.html
An index of all explicitly marked definitional terms. This
page is only generated if at least one definition term is
marked in a formatted docstring.
bug-index.html
An index of all explicitly marked @bug fields. This page is
only generated if at least one @bug field is listed in a
formatted docstring.
todo-index.html
An index of all explicitly marked @todo fields. This page
is only generated if at least one @todo field is listed in a
formatted docstring.
changed-index.html
An index of all explicitly marked @changed fields. This
page is only generated if at least one @changed field is
listed in a formatted docstring.
deprecated-index.html
An index of all explicitly marked @deprecated fields. This
page is only generated if at least one @deprecated field is
listed in a formatted docstring.
since-index.html
An index of all explicitly marked @since fields. This page
is only generated if at least one @since field is listed in
a formatted docstring.
FRAMES-BASED TABLE OF CONTENTS
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.
OTHER PAGES
help.html
The help page for the project. This page explains how to
use and navigate the webpage produced by epydoc.
redirect.html
This page uses javascript to translate dotted names to their
corresponding URLs. For example, in epydoc's documentation,
loading the page <redirect.html#epydoc.apidoc.DottedName>
will automatically redirect the browser to
<epydoc.apidoc-module.html#DottedName>.
epydoc.css
The CSS stylesheet used to display all HTML pages.
epydoc.js
A javascript file used to define javascript functions used
by epydoc.
epydoc-log.html
A page containing a log of all warnings and errors that were
generated by epydoc, along with a table listing all of the
options that were used.
LATEX FILES
The LaTeX API documentation produced by epydoc consists of the
following files:
api.pdf
An Adobe Acrobat (pdf) file containing the complete API
documentation. This file is only generated if you use the
--pdf option.
api.tex
The top-level LaTeX file. This file imports the other LaTeX
files, to create a single unified document.
api.dvi
A dvi file containing the complete API documentation. This
file is only generated if you use the --dvi option, the --ps
option, or the --pdf option.
api.ps A postscript file containing the complete API documentation.
This file is only generated if you use the --ps option or
the --pdf option.
module-module.tex
The API documentation for a module. module is the complete
dotted name of the module, such as sys or epydoc.epytext.
class-class.tex
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. These class
documentation files are only created if the
--separate-classes option is used; otherwise, the
documentation for each class is included in its module's
documentation file.
DIAGNOSTICS
EPYTEXT MARKUP WARNING MESSAGES
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. Epydoc
can generate the following 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.
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.
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
Field warnings are caused by docstrings containing invalid fields.
The contents of the invalid field are generally ignored. Epydoc
can generate the following 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.
EXAMPLES
epydoc -n epydoc -u http://epydoc.sf.net epydoc/
Generate the HTML API documentation for the epydoc package and
all of its submodules, and write the output to the html
directory. In the headers and footers, use epydoc as the
project name, and http://epydoc.sf.net as the project URL.
epydoc --pdf -n epydoc epydoc/
Generate the LaTeX API documentation for the epydoc package and
all of its submodules, and write the output to the latex
directory.
EXIT STATUS
0 Successful program execution.
1 Usage error.
2 Epydoc generated an error or warning, and one of the options
--fail-on-error, --fail-on-warning, or
--fail-on-docstring-warning was specified.
other Internal error (Python exception).
AUTHOR
Epydoc was written by Edward Loper. This man page was originally
written by Moshe Zadka, and is currently maintained by Edward Loper.
BUGS
Report bugs to <edloper@users.sourceforge.net>.
SEE ALSO
epydocgui(1)
The epydoc webpage
<http://epydoc.sourceforge.net>
The epytext markup language manual
<http://epydoc.sourceforge.net/epytext.html>
EPYDOC(1)