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:

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:

.. classtree:: [classes...]
    :dir: up|down|left|right

.. packagetree:: [modules...]
    :dir: up|down|left|right
    :style: uml|tree

.. importgraph:: [modules...]
    :dir: up|down|left|right

.. callgraph:: [functions...]
    :dir: up|down|left|right

.. dotgraph:: [title...]
    :caption: text...
    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:

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

External API links

Epydoc can be used to create hyperlinks from your package documentation towards objects defined in the API of other packages. Such links are similar to ordinary documentation crossreference links, but it is required to configure Epydoc setting up a new interpreted text role, binding it to an external API.

To create a new role, the command line option --external-api=NAME must be used. This option introduces a new interpreted text role called NAME, which can be used to refer to objects defined in an external API.

You can alternatively use a configuration file for this and all the other options: see the sample configuration file for a comprehensive example.

For example, if your program needs to programmatically use the Epydoc package itself, your docstrings may refer to functions described by Epydoc API:

If you want to print a value, you can use
the :epydoc:`apidoc.pp_apidoc()` function.

When you will generate the API documentation for such program, you will need the option --external-api=epydoc or you will get parsing errors due to the unknown role.

Of course this doesn't help to really create cross references: the --external-api option suffices to stop Epydoc complaining about unknown roles, but the text is simply rendered in a monotype font and no link is created.

What Epydoc requires to create external API links is a mapping from the names of the objects exposed by the API and the URL where such objects are actually described. Such mapping must be provided as a text file, with an object name and its URL on each line, separated by a tab character. For example the Epydoc API documentation may be represented by a file names api-objects.txt containing:

epydoc                          ->  epydoc-module.html
epydoc.apidoc                   ->  epydoc.apidoc-module.html
epydoc.apidoc.UNKNOWN           ->  epydoc.apidoc-module.html#UNKNOWN
epydoc.apidoc._pp_val           ->  epydoc.apidoc-module.html#_pp_val
epydoc.apidoc.py_src_filename   ->  epydoc.util-module.html#py_src_filename
epydoc.apidoc.pp_apidoc         ->  epydoc.apidoc-module.html#pp_apidoc
epydoc.apidoc._pp_list          ->  epydoc.apidoc-module.html#_pp_list
...                                 ...
...                                 ...

Epydoc's HTML writer indeed includes such file in its output: see HTML Files for details.

You can bind the definition file to the interpreted text role name using the command line option --external-api-file=NAME:FILENAME.In the previous example you can use:

--external-api-file=epydoc:api-objects.txt

This helps Epydoc to create relative urls: in the previous example the apidoc.pp_apidoc() label will be linked with the epydoc.apidoc-module.html#_pp_val URL.

You can specify a new root for the generated links using the last command line option: --external-api-root=NAME:STRING. STRING will be attached in front of any URL returned by the NAME text role. For example, to let your program refer to Epydoc API whose documentation is published at http://epydoc.sourceforge.net/api/ you can use the options:

--external-api-root=epydoc:http://epydoc.sourceforge.net/api/

this will let your reference apidoc.pp_apidoc() point at the right documentation.

The three options can be used any number of time, effectively allowing to link towards all the required external packages.

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:

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

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.