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
