I’ve been working with turbogears for over a year now.     Over all,  working with turbogears has been good, and I like it a lot more than the custom php I was doing before.   However, with the custom stuff I knew *exactly* what was going on, and it was often able to find ways to do tricky things.

With turbogears – I’ve been able to do more off the bat because more tools were available to me, but I’ve had trouble doing tricky things.    I don’t think I knew enough about what was going on under the hood.

Recently, I’ve been trying to port my app to TG2 – which is based on pylons.   As I started, I read a lot of online docs about TG2, and tried to decided to begin porting my application from TG1 -> TG2.   Ye gods!   I know I did some tricky things – but this porting was far more effort than I imagined!

Lots of names changed – that was OK.   Not fun, but OK.   But some of it has been very difficult, particularly some of the cases where I extended tg library classes, like Form and RepeatingFormField to add my own custom templates and functionality.     I’m still working on the port – and have yet to decide what to use instead of RepeatingFormField – since this no longer exists in toscawidgets – the successor to turbogears widgets.

Part of my problem?   The documentation.   I commend the turbogears developers for the documentation they had created, but I kept going round and round in the online docs, never quite finding the answer I was looking for.   I wasn’t looking for some magic answer – I was just looking for a deeper understanding of how things worked.   The wonder of hyper-linked documentation – it seems I kept reading the same thing over and over.

Realising that turbogears 2 was based on pylons, I decided to start reading more of their docs – and although the pylons site seemed to offer pretty good documentation, it still posed the same problem:   round and round through the hyperlinks.   Tutorials inevitably didn’t get very in depth, and the recipes always seemed to be for something I didn’t find very appetizing right now.

Then I discovered the pylons book!    I’m only on chapter 6 right now, but I feel I have many more options in my toolbox, and am gaining a deeper understanding all the time.    Perhaps it is too long or daunting to get started with – but I think this is a treasure trove of information for turbogears 2 and pylons developers, and should be pointed to more quickly.    If you want a deeper understanding than a simple tutorial provides, I highly recommend it.    It is well written, and being online is great for working through the examples.     Most importantly, it gives you a deeper insight of how the parts are connected.  RTFM – Read The Fine Manual.