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
|
<!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,v 1.2 2003/07/21 06:50:49 edloper Exp $ -->
<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>
<h2>ReStructuredText</h2>
<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 plaintet. Docutils can be downloaded
from the <a
href="http://sourceforge.net/project/showfiles.php?group_id=38414">Docutils
SourceForge page</a>. </p>
<p> Currently, epydoc only has proper support for HTML output for
ReStructuredText docstrings; other output formats will be rendered
using the Docutils <code>Document.astext()</code> method, and won't
look as good. (If someone wants to add proper LaTeX support, I'd be
happy to <a
href="http://sourceforge.net/tracker/?func=add&group_id=32455&atid=405620">accept
patches</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>
<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>
<table width="100%" class="navbox" cellpadding="1" cellspacing="0">
<tr>
<td align="center" width="16.6%">
<a class="nav" href="index.html">[Epydoc]</a></td>
<td align="center" width="16.6%">
<a class="nav" href="installing.html">[Installing]</a></td>
<td align="center" width="16.6%">
<a class="nav" href="using.html">[Using]</a></td>
<td align="center" width="16.6%">
<a class="nav" href="epytext.html">[Epytext]</a></td>
<td align="center" width="16.6%">
<a class="nav" href="http://www.cis.upenn.edu/~edloper/">[Author]</a></td>
<td align="center" width="16.6%">
<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>
<font size="-1">
<!-- hhmts start --> Last modified: Sat Jul 19 12:06:58 EDT 2003 <!-- hhmts end -->
</font>
</body>
</html>
|
