1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
<!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>
|
