[pylucene-dev] Simple automated docs

[David Fraser]

Hi

I spoke to Andi on IRC about doing docs for pylucene.
I hacked together a system this afternoon that strips out the Java 
function declarations and javadoc comments, and tries to add them to the 
generated PyLucene.py as docstrings.
There are three python modules involved:
 - sparse.py which is a general tokenizer I use for other projects.
 - java2doc.py which parses a Java file and finds the class and function 
declarations, matching them to comments
 - redoc.py which takes a generated PyLucene.py file as input and uses 
the given java files (parsed with java2doc) to add docstrings to it, 
outputing the new file to stdout

To run it, place the three files in a PyLucene source directory, and go:
./redoc.py . < PyLucene.py > PyLucene_d.py
The generated PyLucene_d.py will have the docstrings in it.
It takes about 25 seconds to run on my machine.

I haven't yet done anything to strip off the /*  * * */ that you get in 
the comments.
You can now generate an HTML doc for PyLucene using pydoc, it ends up 
being a single 1.8MB html file though.
It may be nice to split up the generated PyLucene_d.py into different 
files to make doc browsing easier.

The only negative impact observed is that Python complains about having 
a docstring that has a non-ASCII character in it, since the encoding 
isn't specified. I haven't done extensive tests to make sure I haven't 
messed anything up but it looks OK to me.

David

-------------- next part --------------
A non-text attachment was scrubbed...
Name: sparse.py
Type: application/x-python
Size: 6991 bytes
Desc: not available
Url : http://lists.osafoundation.org/pipermail/pylucene-dev/attachments/20050211/b1fafc14/sparse-0001.bin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: java2doc.py
Type: application/x-python
Size: 3703 bytes
Desc: not available
Url : http://lists.osafoundation.org/pipermail/pylucene-dev/attachments/20050211/b1fafc14/java2doc-0001.bin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: redoc.py
Type: application/x-python
Size: 4782 bytes
Desc: not available
Url : http://lists.osafoundation.org/pipermail/pylucene-dev/attachments/20050211/b1fafc14/redoc-0001.bin