What's New in Epydoc

Epydoc 3.0 (alpha)

Support for Parsing & Introspection

In previous versions, epydoc extracted information about each module by importing it, and using introspection to examine its contents. Epydoc 3.0 still supports introspection, but is also capable of extracting information about python modules by parsing their source code. Furthermore, the new version of epydoc can combine these two sources of information (introspection & parsing). This is important because each source has its own advantages and disadvantages with respect to the other. See the FAQ for more information about the relative benefits of introspection and parsing, and why it's good to merge information from both sources.

Docstrings for variables

Epydoc now supports variable docstrings. If a variable assignment statement is immediately followed by a bare string literal, then that assignment is treated as a docstring for that variable. In classes, variable assignments at the class definition level are considered class variables; and assignments to instance variables in the constructor (__init__) are considered instance variables:

>>> class A:
...     x = 22
...     """Docstring for class variable A.x"""
...
...     def __init__(self, a):
...         self.y = a
...         """Docstring for instance variable A.y

Variables may also be documented using comment docstrings. If a variable assignment is immediately preceeded by a comment whose lines begin with the specail marker "#:", or is followed on the same line by such a comment, then it is treated as a docstring for that variable:

>>> #: docstring for x
... x = 22
>>> x = 22 #: docstring for x

Graphs & Diagrams

Epydoc can automatically generate a variety of graphs, including class tress, package trees, uml class graphs, and import graphs. These graphs may be included in the generated output in one of two ways:

• The --graph option causes epydoc to automatically generate a given type of graph for all applicable modules, classes, or functions. For example, using --graph classtree will replace the text-based class tree with a graphical class tree on all module pages. See the command line interface documentation for more information.
• Graphs may be explicitly created by docstrings, using appropriate markup. In epytext, graphs are created using the "G" colorization marker (i.e., "G{graphname}", or "G{graphname options...}" for graphs with options). In reStructuredText, graphs are created using custom directives. For more information, see the epytext manual or the notes on using reStructuredText with epydoc. .

For some examples of automatically generated graphs, see the API Documentation for epydoc (including the page for the epydoc.docwriter.dotgraph module.

Graph generation requires the Graphviz package [download].

Syntax Highlighted Source Code

The HTML output now includes source code listings with syntax higlighting, including links from identifiers back into the documentation. For examples of source code pages, see the API Documentation for epydoc (follow the show source link from any documented module, class, or function).

Improved Output

• Methods that are inherited from "external" base classes are listed, but no longer described in detail. E.g., if "object" is used as a base class, then the methods inherited from "object" will be listed at the bottom of the method summary table, but not described in detail.
• The HTML output no longer contains separate pages for including and excluding private variables. Instead, it uses CSS to dynamically hide or display private variables. A cookie is used to record the user's preference. (By default, private variables are hidden.)

Improved Documentation Extraction

• Proper support for nested classes.
• Full unicode support, including support for the encoding directive.
• Increased robustness in the face of a variety of "magic" manipulations of namespaces.

Epydoc 2.1

New Features

• Support for Zope ExtensionClasses
• Updated graphical user interface
• Added support for modules that define __path__.
• New documentation fields:
  • @include: Imports the documentation from another object.
  • @undocumented: Don't document the given object(s)
• Various bug fixes

Epydoc 2.0

New Features

• Support for ReStructuredText docstrings.
• Support for Javadoc docstrings.
• Many new documentation fields for docstrings.
• More robust crossreference link resolving.

• New output formats: LaTeX, DVI, PostScript, and PDF.
• Three new formats for displaying inherited methods and variables: listed, grouped, and included.

• Support for new Python 2.2+ objects, including class methods, static methods, properties, and metaclasses.
• Automatic detection of imported variables.
• Documentation inheritance for inherited methods and variables.

• Epydoc 2.0 runs 50%-200% faster than epydoc 1.1. (e.g., it runs 160% faster when documenting the Python standard library).

Changes

• Support for ReStructuredText docstrings.
• Support for Javadoc docstrings.
• Many new documentation fields for docstrings.
• More robust crossreference link resolving.
• New output formats: LaTeX, DVI, PostScript, and PDF.
• Three new formats for displaying inherited methods and variables: listed, grouped, and included.
• Support for new Python 2.2+ objects, including class methods, static methods, properties, and metaclasses.
• Automatic detection of imported variables.
• Documentation inheritance for inherited methods and variables.
• Epydoc 2.0 runs 50%-200% faster than epydoc 1.1. (e.g., it runs 160% faster when documenting the Python standard library).
• The new "markup" package provides a simple interface makes it easy to add support for additional markup languages.
• __extra_epydoc_fields__ and @newfield can be used to define new fields.
• If the directory for a package is specified, then automatically document all of its contents.
• Increased contrast of "blue" and "green" stylesheet
• Added --test option, to control what tests are run for --check.
• Consolidated error reporting for failed crossreference links and overridden parameter mismatches.
• Added --ignore-param-mismatch option, which supresses warnings about parameter mismatches
• Fixed bug in path magic for epydoc.py and epydoc.pyw scripts
• Replaced __epydoc_sort__ with @sort
• Changes to epytext:
• Epytext now supports symbols (S{...})
• Epydoc allows multi-word values for field arguments (eg for group names)
• Fixeded several minor bugs
• --show-imports now lists imported vars & modules
• Improvements to error reporting
• Improved sorting
• Many bug fixes
• General code clean-up
• Added preliminary and partial implementation for man-style output (like pydoc)
• Changed the definition of the --navlink parameter, to allow for more flexible encoding of the homepage link.
• Improvements to HTML output.
• Display variable values in variable summary table
• Added tooltips for variable values, that show a more complete value (up to 600 characters)
• Minor tweaks & improvements
• In the table of contents, only list objects from modules that were explicitly documented (don't list base classes from imported modules, etc)

Older Releases

See the Release Notes on SourceForge.