Python Documentation

I’ve recently been trying to reload the quantum mechanics that I learned during my stretch in the physics department at UT, and I ran across a rather cool python package called PyQuante, which contains a variety of useful tools for performing quantum chemistry calculations. It’s my first *significant* foray into python, and I have to say that I’m addicted.

The one huge drawback that I’ve found in dealing with python, though, is that even though there are a huge number of free packages out there for dealing with a wide range of complex tasks, their documentation universally *sucks* compared to similar offerings in other languages. This perception may be related to the fact that I’m a cheapskate and haven’t shelled out for a decent IDE, but the community *seems* to feel that using a commandline “help()” command (behaves similar to *nix ‘man’ feature) is enough to cut the butter. It ain’t. Typing anything besides the direct object of my query, particularly something that has to be syntactically correct in order to function properly, is a huge waste of my time, when compared to the online help systems offered by many other commercial compilers and their packages. Yeah, I’m talking about .NET. Yeah, I’m talking about Borland’s compilers and components. If I remember correctly, I can get it out of eclipse with a php plug-in. Cold Fusion, for all of its flaws, has a decent help system (compared to what I’ve encountered in python).

SO here’s the best solution I’ve found so far (on Win7x64):

- grab nssm so you don’t break a sweat on the next step

- run the PyDoc web server as a windows service. this will get you an html interface to your code library.

- then get a copy of NetGrabber 4.1. you’ll have to obtain a registered version in order to do the next step.

- point NetGrabber at your local web server (e.g. http://localhost:8000), and grab a coffee. note: make sure you drop the thread count down to 1 or 2 during the project setup – the pydoc web server choked hard when I set the thread count to 8.

- after about 20 minutes, NetGrabber will ask you if you want to create a CHM file, to which you answer ‘Yep’.

Open up your new CHM file, and you’ll see that you now have a nice *fast*, *searchable*, cross-linked snapshot of all documentation that your python packages have natively available.

Rock the house.

I should mention here that my copy of python actually came with a fairly extensive help file (in .chm format), to temper my bad-mouthing of python documentation. It does not cover the modules I’ve installed, however, like PyQuante, scipy, numpy, and mdp, which (as I’ve been discovering the hard way) contain many modules that reference one another.

What I really need is something that will resolve references within a source file and make *that* clickable back to the proper *.py module & object definition, though the answer to this might be in my earlier comment about forking out for a decent IDE. Perhaps a static code analyzer.

Cheers!

:-)