create documentation with the comments present in the source code

[Tony J Ibbs (Tibs)]

SENEQUIER wrote:
> I just want to know if an utility as 'Javadoc' exists for Python.

Other people have (correctly) mentioned ``pydoc``, which is in the
standard distribution. It extracts lots of useful information from
Python code, but what it *doesn't* do is parse the text (well, not
much) - so it doesn't provide the equivalent of embedding HTML in the
documentation string, as one can do in Javadoc.

Happydoc is another alternative that already exists (also mentioned
before). It is a separate download (I normally use www.google.com to
find it!), but it *does* parse the docstring, and supports various
formats (definitely ST (notably used in the Zope world), and I don't
remember what else) for annotating the docstring text.

It's worth noting that HappyDoc will also look in *comments* for
documentation, if you so wish - that *is* what your subject line asked
for...

Meanwhile, across in the Doc-SIG, work is going on to develop support
for extracting information from Python code (including docstrings) and
parsing said docstrings (but with a better format for the text than ST).
This is still very much an ongoing project (i.e., it's not finished
yet!), but you can find out about it at:

	http://docstring.sourceforge.net/ and
	http://structuredtext.sourceforge.net/

Hope that isn't too much of a confusion of Good Things...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)