What's New in Epydoc

Epydoc 3.0

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

Epydoc can also generate function call graphs, showing the callers and the callees for each function. To generate call graphs, Epydoc uses data produced by a Python profiler such Profile or hotshot.

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. Furthermore methods and variables not very detailed (with at most a short docstring) are only shown in the summary, while most detailed items also appear in a full detailed box.
• 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.)
• Additional pages are created, listing identifiers, documented definitions, bugs and to-do items. An optional log page can also be generated, reporting all the errors and warning raised during documentation generation.
• Improved variable values representation, using the parsed values if the standard representation is not informative (such as <Foo instance at 0x...>). Syntax highlighting is used for introspected values, including colorization for regular expressions.
• Improved support for adding links into the generated documentation. A new API, epydoc.docwriter.xlink, can be used to determine the correct URL for any object name; and a new redirect page named named "redirect.html" uses javascript to automatically redirect the user to the correct URL for any given object name. See the FAQ for more information.

Improved Documentation Extraction

• Proper support for nested classes.
• Full unicode support, including support for the encoding directive.
• Variables conventionally used for modules metadata such as __version__ are recognized as modules fields.
• The __all__ attribute is used to decide whether objects are public or private. If an object is listed in an __all__ list, it will appear defined in that module even if imported from elsewhere, keeping the API safe from implementation changes.
• Increased robustness in the face of a variety of "magic" manipulations of namespaces.
• Fine-grained control over exactly which modules should be parsed, introspected, or both.
• Support for Zope 3.x InterfaceClass and Zope 2.x ExtensionClass objects.

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.