~ubuntu-branches/debian/lenny/epydoc/lenny

The <a class="reference external" href="http://web.lfw.org/python/pydoc.html">pydoc</a> module, which became part of <a class="reference external" href="http://www.python.org/doc/current/lib/module-pydoc.html">the standard library</a> in Python 2.1,

can be used to display information about a Python object, including its

docstring:

>>> from pydoc import help

>>> help(x_intercept)

Help on function x_intercept in module __main__:

x_intercept(m, b)

Return the x intercept of the line y=m*x+b. The x intercept of a

line is the point at which it crosses the x axis (y=0).</pre>

For more information about Python docstrings, see the <a class="reference external" href="http://www.python.org/doc/current/tut/node6.html#docstrings">Python Tutorial</a> or

the O'Reilly Network article <a class="reference external" href="http://www.onlamp.com/lpt/a/python/2001/05/17/docstrings.html">Python Documentation Tips and Tricks</a>.

<h1>Variable docstrings</h1>

Python don't support directly docstrings on variables: there is no attribute

that can be attached to variables and retrieved interactively like the

<tt class="docutils literal">__doc__</tt> attribute on modules, classes and functions.

While the language doesn't directly provides for them, Epydoc supports

variable docstrings: if a variable assignment statement is immediately

followed by a bare string literal, then that assignment is treated as a

docstring for that variable. In classes, variable assignments at the class

definition level are considered class variables; and assignments to instance

variables in the constructor (<tt class="docutils literal">__init__</tt>) are considered instance variables:

class A:

x = 22

"""Docstring for class variable A.x"""

def __init__(self, a):

self.y = a

"""Docstring for instance variable A.y</pre>

Variables may also be documented using comment docstrings. If a variable

assignment is immediately preceeded by a comment whose lines begin with the

special marker '<tt class="docutils literal">#:</tt>', or is followed on the same line by such a comment,

then it is treated as a docstring for that variable:

#: docstring for x

x = 22

x = 22 #: docstring for x</pre>

Notice that variable docstrings are only available for documentation when the

source code is available for parsing: it is not possible to retrieve variable

</div>

<h1>Items visibility</h1>

Any Python object (modules, classes, functions, variables...) can be public

or private. Usually the object name decides the object visibility: objects

whose name starts with an underscore and doesn't end with an underscore are

considered private. All the other objects (including the "magic functions" such

as <tt class="docutils literal">__add__</tt>) are public.

For each module and class, Epydoc generates pages with both public and private

methods. A Javascript snippet allows you to toggle the visibility of private

objects.

If a module wants to hide some of the objects it contains (either defined in

the module itself or imported from other modules), it can explicitly list the

names if its <a class="reference external" href="http://www.python.org/doc/2.4.3/ref/import.html">public names</a> in the <tt class="docutils literal">__all__</tt> variable.

If a module defines the <tt class="docutils literal">__all__</tt> variable, Epydoc uses its content to decide

if the module objects are public or private.

</div>

<tr>

100

Home</a></td></a>

101

102

103

104

Installing Epydoc</a></td></a>

105

106

107

108

Using Epydoc</a></td></a>

109

110

111

112

Epytext</a></td></a>

113

114

115

116

<IMG src="sflogo.png"

117

width="88" height="26" border="0" alt="SourceForge"

118

align="top"/></A></td>

119

</tr>

120

</table>

121

</body>

122

</html>

Older »