Sire

I've bitten the bullet, and finally moved over to using Py++ to generate the python bindings for Sire. I've spent the last couple of years writing my python wrappers by hand. This was great, as I had complete control of the bindings, and was able to add neat overloads, e.g. turning a tuple of atom IDs into a bond. I've always steered clear of code generators as I have rarely been happy with the resulting code, and have never felt that I've had sufficient control over the generated bindings to achieve the result that I want. Py++ has the promise of allowing me to automate most of the binding process, while at the same time having control over additional binding code and achieving some of the neat effects that I can get with hand crafted code.

Py++ is pretty cool, and I did dive into the deep end and wrap up Sire.Mol using it (Sire.Mol is the largest module in the code). The hardest part has been trying to learn how Py++ works. Py++ does not have the greatest documentation, and I have to keep looking into the source code (thank goodness for ipython!). This isn't a complaint against the author of Py++ - writing documentation is hard and boring - especially when you are not writing in your native language (and to be honest, I can't throw stones as while Sire has pretty good API documentation, it is without a manual or any tutorials - though Sire is not finished or released yet, so a manual and tutorials would be premature). It has given me an insight into the importance of good documentation. API documentation is not good enough, and as I develop Sire further, I am going to have to write lots of tutorials and examples. However, users will always want to do special things - e.g. I am just a beginner user of Py++, but I want to now do some advanced things, e.g. turn off Python wrappers of virtual classes, add base classes that are not exposed to Python in one module, but are exposed in another, and including some manually wrapped Qt template classes. Doing these things is not easy in Py++, and has forced me to really look through the Py++ source code. While I like to think that I can program, I find it so difficult to read someone else's source code. The source level documentation in Py++ is not great, and it's quite a complicated code base. It is thus very difficult to work out what I need to change to achieve what I want. This really shows how important clear source code is - I am sure that someone else trying to learn Sire would experience the same problems that I have experienced while trying to learn Py++.