[pylucene-dev] Simple automated docs

David Fraser davidf at sjsoft.com
Thu Feb 17 07:03:19 PST 2005


David Fraser wrote:

> 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 

Has anybody tried this out? Any comments appreciated :-)

David


More information about the pylucene-dev mailing list