[pylucene-dev] Simple automated docs
davidf at sjsoft.com
Thu Feb 17 07:03:19 PST 2005
David Fraser wrote:
> 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.
Has anybody tried this out? Any comments appreciated :-)
More information about the pylucene-dev