Alternate Markup Languages

Epydoc's default markup language is epytext, a lightweight markup language that's easy to write and to understand. But if epytext is not powerful enough for you, or doesn't suit your needs, epydoc also supports three alternate markup languages:

To specify the markup language for a module, you should define a module-level string variable __docformat__, containing the name of the module's markup language. The name of the markup language may optionally be followed by a language code (such as en for English). Conventionally, the definition of the __docformat__ variable immediately follows the module's docstring:

# widget.py
"""
Graphical support for `gizmos` and `widgets`.
"""
__docformat__ = "restructuredtext en"
[...]

To change the default markup language from the command line, use the --docformat option. For example, the following command generates API documentation for the existing regular expression package re, which uses plaintext markup:

[epydoc]$ epydoc --docformat plaintext re

reStructuredText

reStructuredText is a markup language that was developed in conjunction with Docutils. In order to parse reStructuredText docstrings, Docutils 0.3 or higher must be installed. If Docutils is not installed, then reStructuredText docstrings will be rendered as plaintext. Docutils can be downloaded from the Docutils SourceForge page.

In addition to the standard set of fields, the reStructruedText parser also supports consolidated fields, which combine the documentation for several objects into a single field. For more information, see the markup-specific notes for reStructuredText fields.

The epydoc reStructuredText reader also defines several custom directives, which can be used to automatically generate a variety of graphs. The following custom directives are currently defined:

DirectiveDescription
.. classtree:: [classes...]
    :dir: up|down|left|right
Display a class hierarchy for the given class or classes (including all superclasses & subclasses). If no class is specified, and the directive is used in a class's docstring, then that class's class hierarchy will be displayed. The dir option specifies the orientation for the graph (default=down).
.. packagetree:: [modules...]
    :dir: up|down|left|right
    :style: uml|tree
Display a package hierarchy for the given module or modules (including all subpackages and submodules). If no module is specified, and the directive is used in a module's docstring, then that module's package hierarchy will be displayed. The dir option specifies the orientation for the graph (default=down). The style option specifies whether packages should be displayed in a tree, or using nested UML symbols.
.. importgraph:: [modules...]
    :dir: up|down|left|right
Display an import graph for the given module or modules. If no module is specified, and the directive is used in a module's docstring, then that module's import graph will be displayed. The dir option specifies the orientation for the graph (default=left).
.. callgraph:: [functions...]
    :dir: up|down|left|right
Display a call graph for the given function or functions. If no function is specified, and the directive is used in a function's docstring, then that function's call graph will be displayed. The dir option specifies the orientation for the graph (default=right).
.. dotgraph:: [title...]
    :caption: text...
    graph...
Display a custom Graphviz dot graph. The body of the directive (graph...) should contain the body of a dot graph. The optional title argument, if specified, is used as the title of the graph. The optional caption option can be used to provide a caption for the graph.

Javadoc

Javadoc is a markup language developed by Sun Microsystems for documenting Java APIs. The epydoc implementation of Javadoc is based on the Javadoc 1.4.2 reference documentation. However, there are likely to be some minor incompatibilities between Sun's implementation and epydoc's. Known incompatibilities include: