What documentation "standard" to use

[Micah Elliott]

On Oct 05, Kalle Anke wrote:
> I'm confused of how I should document my code, I've always liked being
> able to document my code directly in my source file and then to use
> some tool to extract the documentation to some other format.

> My problem with Python is that there are so many tools and formats ...
> I don't know which one I should use. I've tried to figure out if there
> is one that is the "de-facto standard" but ...

You don't need to do any marking up to use pydoc -- just put your
comments in the right place so that they become docstrings.  Just try
"pydoc pydoc" for more info.  It is distributed with Python, and
generates nicely colored html or opens your PAGER.

Or you could install epydoc <http://epydoc.sourceforge.net/>, which has
similar features (and more).  It supports "reStructuredText"
<http://docutils.sourceforge.net/rst.html> and it's own markup (epytext,
I think).  RST is the de-facto Python markup, AFAICT.  You'll need
something like "__docformat__ = 'restructuredtext'" in your modules.
RST is great for non-Python-source code, too.

Those are the two I am aware of.

-- 
Micah Elliott
<mde at micah.elliott.name>