<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html> <head>
<title>Alternate Markup Languages</title>
<link rel="stylesheet" href="epydoc.css" type="text/css"/>
</head>
<!-- $Id: othermarkup.html 1526 2007-02-17 04:30:49Z dvarrazzo $ -->
<body>
<div class="body">
<h1>Alternate Markup Languages</h1>
<p> Epydoc's default markup language is <a
href="epytext.html">epytext</a>, 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: </p>
<ul>
<li><b><a href="http://docutils.sourceforge.net/rst.html"
>reStructuredText</a></b> 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.</li>
<li><b><a href="http://java.sun.com/j2se/javadoc/"
>Javadoc</a></b> is a documentation markup language that was
developed for Java. It consists of HTML, augmented by a set of
special tagged fields. </li>
<li><b>Plaintext</b> docstrings are rendered verbatim (preserving
whitespace).</li>
</ul>
<p> To specify the markup language for a module, you should define a
module-level string variable <code>__docformat__</code>, 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
<code>en</code> for English). Conventionally, the definition of the
<code>__docformat__</code> variable immediately follows the module's
docstring: </p>
<div class="screen">
<pre>
<code class="comment"># widget.py</code>
<code class="string">"""
Graphical support for `gizmos` and `widgets`.
"""</code>
__docformat__ = <code class="string">"restructuredtext en"</code>
<i>[...]</i>
</pre></div>
<p> To change the default markup language from the command line, use
the <code>--docformat</code> option. For example, the following
command generates API documentation for the existing regular
expression package <code>re</code>, which uses plaintext markup: </p>
<div class="screen"><pre>
<code class="prompt">[epydoc]$</code> epydoc --docformat plaintext re
</pre></div>
<a name="restructuredtext">
<h2>reStructuredText</h2></a>
<p> reStructuredText is a markup language that was developed in
conjunction with <a
href="http://docutils.sourceforge.net">Docutils</a>. 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 <a
href="http://sourceforge.net/project/showfiles.php?group_id=38414">Docutils
SourceForge page</a>. </p>
<p> In addition to the <a href="fields.html#fields">standard set of
fields</a>, the reStructruedText parser also supports
<i>consolidated</i> fields, which combine the documentation for
several objects into a single field. For more information, see the
markup-specific notes for <a href="fields.html#rst">reStructuredText
fields</a>. </p>
<p> The epydoc reStructuredText reader also defines several custom <a
href="http://docutils.sourceforge.net/docs/user/rst/quickref.html#directives">directives</a>,
which can be used to automatically generate a variety of graphs. The
following custom directives are currently defined:</p>
<table border="1" cellspacing="0" cellpadding="3" width="95%">
<tr><th width="10%">Directive</th><th width="90%">Description</th></tr>
<tr valign="top"><td><pre>
.. classtree:: [<code class="user">classes...</code>]
:dir: <code class="user">up|down|left|right</code>
</pre></td>
<td>
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 <code>dir</code> option specifies
the orientation for the graph (default=<code>down</code>).
</td></tr>
<tr valign="top"><td><pre>
.. packagetree:: [<code class="user">modules...</code>]
:dir: <code class="user">up|down|left|right</code>
:style: <code class="user">uml|tree</code>
</pre></td>
<td>
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 <code>dir</code> option specifies
the orientation for the graph (default=<code>down</code>). The
<code>style</code> option specifies whether packages should be
displayed in a tree, or using nested UML symbols.
</td></tr>
<tr valign="top"><td><pre>
.. importgraph:: [<code class="user">modules...</code>]
:dir: <code class="user">up|down|left|right</code>
</pre></td>
<td>
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 <code>dir</code>
option specifies the orientation for the graph
(default=<code>left</code>).
</td></tr>
<tr valign="top"><td><pre>
.. callgraph:: [<code class="user">functions...</code>]
:dir: <code class="user">up|down|left|right</code>
</pre></td>
<td>
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
<code>dir</code> option specifies the orientation for the graph
(default=<code>right</code>).
</td></tr>
<tr valign="top"><td><pre>
.. dotgraph:: [<code class="user">title...</code>]
:caption: <code class="user">text...</code>
<code class="user">graph...</code>
</pre></td>
<td>
Display a custom Graphviz dot graph. The body of the directive
(<code>graph...</code>) should contain the body of a dot graph. The
optional <code>title</code> argument, if specified, is used as the
title of the graph. The optional <code>caption</code> option can be
used to provide a caption for the graph.
</td></tr>
</table>
<h2>Javadoc</h2>
<p><a href="http://java.sun.com/j2se/javadoc/"
>Javadoc</a> is a markup language developed by Sun Microsystems
for documenting Java APIs. The epydoc implementation of Javadoc is
based on the <a
href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/javadoc.html">Javadoc
1.4.2 reference documentation</a>. However, there are likely to be
some minor incompatibilities between Sun's implementation and
epydoc's. Known incompatibilities include: </p>
<ul>
<li> Epydoc does not support the Javadoc block tag
<code>@serial</code>.</li>
<li> Epydoc does not support the following Javadoc inline tags:
<code>{@docroot}</code>, <code>{@inheritdoc}</code>,
<code>{@value}</code>.
<li> Epydoc adds many field tags that Sun does not include, such as
<code>@var</code>, <code>@type</code>, and
<code>@group</code>. </li>
</ul>
</div>
<table width="100%" class="navbox" cellpadding="1" cellspacing="0">
<tr>
<a class="nav" href="index.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="index.html">
Home</a></td></a>
<a class="nav" href="installing.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="installing.html">
Installing Epydoc</a></td></a>
<a class="nav" href="using.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="using.html">
Using Epydoc</a></td></a>
<a class="nav" href="epytext.html">
<td align="center" width="20%" class="nav">
<a class="nav" href="epytext.html">
Epytext</a></td></a>
<td align="center" width="20%" class="nav">
<A href="http://sourceforge.net/projects/epydoc">
<IMG src="sflogo.png"
width="88" height="26" border="0" alt="SourceForge"
align="top"/></A></td>
</tr>
</table>
</body>
</html>
