Richard Bucker

pydoc - the anti-killer appp

Posted at — Sep 21, 2011

Some time ago I wrote about perldoc being perl’s killer app. I still think that’s true. Recently I’ve been going through my python code and attempting to add useful comments that could be picked up by some auto documenting mechanism. Clearly they exist… is full of doc and I’m certain it’s rendered.Included with python, since 2.1, is pydoc. At first glance it appears to be an analog to perldoc; and for the most part it isn’t. pydoc will generate text or html - perldoc will convert the poddoc to html, latex, man, text pydoc has a graphic UI embedded - but it requires TK (and x-windows) pydoc has an embedded http server - could leak important data if the pydoc is internal use only. perldoc generates static files - pydoc generates dynamic files pydoc recurses the class dependency tree - if the stack is deep the document is long (there is a lesson in this)In a way, it’s nice that pydoc scans your code looking for your comments in your classes etc. The format makes sense and it’s not all that terrible. There are even ways to comment individual functions instead of just one monster perldoc (as typically demonstrated)So perldoc is still the killer app.ref: perlpod -