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 plaintet. Docutils can be downloaded from the Docutils SourceForge page.

Currently, epydoc only has proper support for HTML output for ReStructuredText docstrings; other output formats will be rendered using the Docutils Document.astext() method, and won't look as good. (If someone wants to add proper LaTeX support, I'd be happy to accept patches.)

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.

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.

[Epydoc]

[Installing]

[Using]

[Epytext]

[Author]