Python "header" files

[beliavsky at aol.com]

Timo Virkkala <a at a.invalid> wrote in message news:<9rqxc.493$0N1.397 at read3.inet.fi>...

> Probably the most convenient way is to write good docstrings which document 
> the return values as well, and then generate static documentation from them 
> with pydoc.
> 
> http://www.python.org/doc/current/lib/module-pydoc.html

Thanks to you and others for suggesting pydoc. It easily generates
nice HTML. I like the results for my modules that just define
functions and classes.

For the main programs it actually runs the Python code and does
calculations before producing HTML. (Pychecker seems to work the same
way). The "DATA" section contains not only the parameters I set but
the computed results, which can change every time the program is run,
especially for simulations. PyDoc does not seem too helpful to me for
documenting the main program.

I think the HTML documentation for a main program should have (in
addition to the docstrings) the list of modules imported with links to
specific functions and variables imported.