Unfortunately, none of the documentation tools that use documentation strings are suitable for full, serious documentation. There are a number of reasons for this, and I'll touch on a few.
The obvious one is that there is no standard format for docstrings, and this creates problems when trying to achieve a uniform look across python documentation. More seriously, there is a major problem with docstrings in that they can only document something that has a docstring; classes, functions, methods, and modules. But what if I have constants that are important? The only place to document them is in the module docstring, and everything else--examples, concepts, and so on--must be thrown in there as well. But there are no agreed on formats and processing pipelines that then allow such a large module docstring, plus other docstrings, to produce a good final document. I do tech writing for a living, so I have some idea of what I'm talking about, I think :-) It's too bad that there is no equivalent of d'oxygen for Python. That is a _nice_ program. Thanks for the advice, Ken On Sep 27, 2005, at 1:21 AM, beza1e1 wrote: > Do you think of pydoc? Just make comments in your code this way: > > def add10(x): > """this function adds ten to the given variable""" > > Then save this into add.py and now (in the same directory): > > pydoc add > > Voila, your documentation. > > -- > http://mail.python.org/mailman/listinfo/python-list > -- http://mail.python.org/mailman/listinfo/python-list
