What documentation "standard" to use

[Kalle Anke]

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 ...

Could someone advice me on what format/tool I should use?

 

[Micah Elliott]

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.

 

[Kenneth McDonald]

This is, as far as I'm concerned, one of the great weaknesses of
Python. (One of a
relatively few, to be honest--I'm still an enthusiast after all!)

There are numerous docstring-oriented tools; in my opinion, none of
them are satisfactory,
because docstrings only apply to certain entities, and there are many
other entities one
might wish to document.

Fred Lundh pointed out just a day or two ago a program of his called
PythonDoc where
documentation is put into comments, and from the brief look I had at
it, I may start
using it, it looks pretty nice.

ReStructuredText (now called ReST, I believe) looks like it's finally
become a quite
good text markup language, and if there were a non-docstring system
that used it, I
think that also would be good.

But what I'd really like is for Guido et al to declare a standard
documentation system and
include in the standard Python distro. That way we would have _some_
standard, and
people could concentrate their energy on improving it, rather than on
continually
coming up with their own, non-interoperable, solutions.

Cheers,
Ken