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:

reStructuredText
is an "easy-to-read, what-you-see-is-what-you-get plaintext markup syntax". It is more powerful than epytext (e.g., it includes markup for tables and footnotes); but it is also more complex, and sometimes harder to read.
Javadoc
is a documentation markup language that was developed for Java. It consists of HTML, augmented by a set of special tagged fields.
Plaintext docstrings
are rendered verbatim (preserving whitespace).

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.

Default role

Epydoc replaces the Docutils' default interpreted text role with the creation of documentation crossreference links. If you want to create a crossreference link to the somemod.Example class, you can put backquotes around your test, typing:

`somemod.Example`

Consolidated Fields

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 example, a single :Parameters: field is often used to describe all of the parameters for a function or method:

def fox_speed(size, weight, age):
    """
    Return the maximum speed for a fox.

    :Parameters:
    - `size`: The size of the fox (in meters)
    - `weight`: The weight of the fox (in stones)
    - `age`: The age of the fox (in years)
    """
    #[...]

Epydoc will automatically extract information about each parameter from this list. These consolidated fields may be written using either a bulleted list or a definition list.

  • If a consolidated field is written as a bulleted list, then each list item must begin with the field's argument, marked as interpreted text, and followed by a colon or dash.
  • If a consolidated field is written as a definition list, then each definition item's term should contain the field's argument, (it is not mandatory for it being marked as interpreted text).

The term classifier, if present, is used to specify the associated type. The following example shows the use of a definition list to define a consolidated field (note that docutils requires a space before and after the ':' used to mark classifiers).

def fox_speed(size, weight, age):
    """
    Return the maximum speed for a fox.

    :Parameters:
      size
        The size of the fox (in meters)
      weight : float
        The weight of the fox (in stones)
      age : int
        The age of the fox (in years)
    """
    #[...]

The following consolidated fields are currently supported by epydoc:

Consolidated Field Tag Corresponding Base Field Tag
:Parameters: :param:
:Exceptions: :except:
:Groups: :group:
:Keywords: :keyword:
:Variables: :var:
:IVariables: :ivar:
:CVariables: :cvar:
:Types: :type:

Graph directives

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

Directive Description
.. 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.

Colorized snippets directive

Using reStructuredText markup it is possible to specify Python snippets in a doctest block. SUch block will be colorized as in epytext Doctest Blocks.

>>> def double(x):
...     return x * 2
...
>>> print double(8)
16

Doctest block are mostly useful to be run as a part of automatized test suite using the doctest module. If the Python prompt gets in your way when you try to copy and paste and you are not interested in self-testing docstrings, the python directive will let you obtain a simple block of colorized text:

Docstring Input Rendered Output
.. python::

    def fib(n):
        """Print a Fibonacci series."""
        a, b = 0, 1
        while b < n:
            print b,
            a, b = b, a+b
def fib(n):
    """Print a Fibonacci series."""
    a, b = 0, 1
    while b < n:
        print b,
        a, b = b, a+b

Indexed Terms in reStructuredText

Epydoc uses indexed terms to create a table of terms definitions. Indexed terms are created using the epytext markup X{...}.

If you want to create indexed terms in reStructuredText modules, you can use the term interpreted text role. For example:

Docstring Input Rendered Output
def example():
    """
    An :term:`index term` is a term that
    should be included in the index.
    """
    #[...]

An index term is a term that should be included in the index.

Index
index term example
x intercept x_intercept
y intercept x_intercept

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:

Javadoc Fields

For compatibility with Javadoc, every @see field is assumed to contain a single crossreference link, unless its body is quoted, or it starts with an HTML tag. See the Javadoc reference manual for more information about how the @see field is encoded in Javadoc.

Because Javadoc does not mark end of the optional argument, field arguments must contain exactly one word. Thus, multi-word arguments are not available in Javadoc. In particular, all group names must be single words.