Epydoc provides two user interfaces:
Epydoc can also be accessed programmatically; see epydoc's API documentation for more information.
epydoc script extracts API documentation for a
set of python objects, and writes it using a selected output format.
Objects can be named using dotted names, module filenames, or package
directory names. (On Windows, this script is named
epydoc [--html|--pdf] [-o
DIR] [--parse-only|--introspect-only] [-v|-q] [--name
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.
-v) or decrease (
-q) the verbosity of the output. These options may be repeated to further increase or decrease verbosity. Docstring markup warnings are supressed unless
-vis used at least once.
__docformat__variable; it is recommended that you explicitly specify
__docformat__in all your modules.
GRAPHTYPEin the generated output. Graphs are generated using the Graphviz dot executable. If this executable is not on the path, then use
--dotpathto specify its location. This option may be repeated to include multiple graph types in the output. To include all graphs, use
--graph all. To see an example of each graph type, click on it:
classtree: Displays each class's base classes and subclasses.
callgraph: Displays the callers and callees of each function or method. These graphs are based on profiling information, which must be specified using the
umlclass: Displays each class's base classes and subclasses, using UML style. Methods and attributes are listed in the classes where they are defined. If type information is available about attributes (via the
@typefield), then those types are displayed as separate classes, and the attributes are displayed as associations.
For a complete description of the command line usage for epydoc,
The following command will generate
HTML documentation for the
sys module, and write it to
[epydoc]$epydoc --html sys -o sys_docs
The following commands are used to produce the API documentation
for epydoc itself. The first command writes html output to the
epydoc as the
project name and
http://epydoc.sourcforge.net as the
project URL. The
white CSS style is used; inheritance is
displayed using the
listed style; and all graphs are
included in the output. The second command writes pdf output to the
api.pdf in the directory
Epydoc as the project name.
[epydoc]$epydoc -v -o html/api --name epydoc --css white \ --url http://epydoc.sourceforge.net \ --inheritance listed --graph all src/epydoc
[epydoc]$epydoc -v -o latex/api --pdf --name "Epydoc" src/epydoc
--configoption, 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 is a simple example of a configuration file.
[epydoc] # Epydoc section marker (required by ConfigParser) # Information about the project. name: My Cool Project url: http://cool.project/ # The list of modules to document. Modules can be named using # dotted names, module filenames, or package directory names. # This option may be repeated. modules: sys, os.path, re modules: my/project/driver.py # Write html output to the directory "apidocs" output: html target: apidocs/ # Include all automatically generated graphs. These graphs are # generated using Graphviz dot. graph: all dotpath: /usr/local/bin/dot
A more complete example, including all of the supported options, is also available.
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
command, or with
epydoc.pyw in the
subdirectory of the Python installation directory under Windows.
Currently, the graphical interface can only generate HTML output.
Use the "Add" box to specify what objects you wish to document.
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. Once you have added all of the modules
that you wish to document, press the "Start" button. Epydoc's
progress will be displayed on the progress bar.
To customize the output, 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.
(These project files do not currently use the same format as the
configuration files used by the command line interface.)
For more information, see the
epydocgui(1) man page.
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]
epydoc/epytext.py") or module names (such as "
os.path"). The filename for a package is its "
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
Every Python module and class is documented in its own file. Index files, tree files, 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.htmlThe standard entry point for the documentation. Normally,
index.htmlis a copy of the frames file (
frames.html). But if the
--no-framesoption is used, then
index.htmlis 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).
The API documentation for a module. module is the complete dotted name of the module, such as sys or epydoc.epytext.
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.
A page with the module colourized source code, with links back to the objects main documentation pages. The creation of the colourized source pages can be controlled using the options
module-tree.htmlThe documented module hierarchy.
class-tree.htmlThe documented classes hierarchy.
identifier-index.htmlThe index of all the identifiers found in the documented items.
term-index.htmlThe index of all the term definition found in the docstrings. Term definitions are created using the Indexed Term markup.
bug-index.htmlThe index of all the known bug in the documented sources. Bugs are marked using the
todo-index.htmlThe index of all the to-do items in the documented sources. They are marked using the
help.htmlThe help page for the project. This page explains how to use and navigate the webpage produced by epydoc.
epydoc-log.htmlA page with the log of the epydoc execution. It is available clicking on the timestamp below each page, if the documentation was created using the
--include-logoption. The page also contains the list of the options enabled when the documentation was created.
api-objects.txtA text file containing each available item and the URL where it is documented. Each item dotted name takes a file line and it is separated by the URL by a
tabcharecter. Such file can be used to create documents linkig to the API: see the
--external-apidocumentation for details.
redirect.html#epydoc.apidoc.DottedNamethe browser will be redirected to the page
frames.htmlThe 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.htmlThe 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.htmlThe 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-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.cssThe 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
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,
|Home||Installing Epydoc||Using Epydoc||Epytext|