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
On 5-Oct-05, at 3:26 PM, 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 ...
Could someone advice me on what format/tool I should use?
--
http://mail.python.org/mailman/listinfo/python-list