What documentation "standard" to use

[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

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
>