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 > -- http://mail.python.org/mailman/listinfo/python-list
