What tools are used to write and generate Python Library documentation.

[Kenneth McDonald]

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
>