javadoc equivalent?

[Thomas A. Bryan]

Michal Wallace wrote:
> 
> Hey All,
> 
> Is there a tool similar to javadoc in python? Something that would go
> through a .py file, read the doc strings (assuming they're in there),
> and then print the results in a nicely formatted HTML document?

Ask the DOC-SIG.  I think that they were looking into such a thing.

It wouldn't be too hard to write a basic thing in python...

Rough sketch

Import a module
elements = dir(modulename)
for each classOrMethod in elements:
   elementType = determineType(classOrMethod)  # for formatting purposes
   try:
       format(classOrMethod.__doc__, elementType)
   except AttributeError:
       pass
try:
    format(modulename.__doc__,'module')
except AttributeError:
   pass

> Could such a beast read docstrings in .pyc's, or do they get compiled out?

That's easy to test...

$ cat > somedocs.py 
class Foo:
    """This class exists simply to test whether
    docstrings are preserved in .pyc files."""
    pass

$ python -c 'import somedocs'
$ ls   
somedocs.py  somedocs.pyc
$ rm somedocs.py
$ ls
somedocs.pyc
$ python -c 'import somedocs; print somedocs.Foo.__doc__'
This class exists simply to test whether
    docstrings are preserved in .pyc files.


I've been working on a general-purpose documenatation tool that 
could be used for formatting Python documentation, but it's 
currently stalled.  I'll post again when it's usable.

---Tom