What tools are used to write and generate Python Library documentation.
kenneth.m.mcdonald at sbcglobal.net
Tue Sep 27 19:45:19 CEST 2005
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,
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.
More information about the Python-list