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 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:: [ |
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:: [ |
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:: [ |
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:: [ |
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:: [ |
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 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:
@serial.{@docroot}, {@inheritdoc},
{@value}.
@var, @type, and
@group. | Home | Installing Epydoc | Using Epydoc | Epytext |
|