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

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:

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.

## 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:

- Epydoc does not support the Javadoc block tag `@serial`.
- Epydoc does not support the following Javadoc inline tags: `{@docroot}`, `{@inheritdoc}`, `{@value}`.
- Epydoc adds many field tags that Sun does not include, such as `@var`, `@type`, and `@group`.