February 9th, 2007 by Mark Ramm
I’ve been meaning to blog about WSGI more lately. I still find Pythonistas who don’t know what WSGI is, and others who think it is some big scary J2EE like specification which should be avoided at all costs.
I don’t think theres any good reason to be scared, it’s actually pretty simple to understand and use. But, that post will have to wait for another day. For now, I just wanted to mention that I caught wind of an interesting mod_ project for Apache which should interest WSGI users.
That’s right, now there’s a mod_wsgi project, being written by Graham Dumpleton.
I reciently caught wind of mod_wsgi, on the Hex Dump blog, and the turbogears mailing list It’s not released yet, but it seems like a good idea to me.
Oh, and the “performance estimates” comparing cgi, mod_python and mod_wsgi look nice too.
Here’s hoping that it actually gets released in next month as planned. If we could actually get ISP’s to load this module, it would make the “commodity hosting” deployment options for modern python web apps much better. Graham’s original post to the mod_python list about how he sees mod_wsgi fitting in with commodity apache hosting is actually well worth the read.
So, here’s hoping that it’s a success.
February 9th, 2007 by Mark Ramm
Recently there has been quite a bit of lively discussion about the current state of the online TurboGears documentation on the mailing list. And it’s pretty clear that our users are telling us that we need to improve the docs, and I want to assure people that this is a message we’ve heard loud and clear, and I agree that it is a message we really need to hear clearly.
The good news, is that it’s not a new message. We know that writing good documentation is one of the most important tasks for developing a project like TurboGears, which brings together lots of existing Python libraries into a single “framework.” And we’re working hard on building the best documentation we can. In fact we’ve already planned a DocSprint for this weekend.
There’s definitely a gap between where we are, and where we should be.
So, I thought I’d write up a bit of perspective about how we got here, how we’re doing right now, and where I think we need to focus our efforts in the short term. In another post I’ll talk about our long term goals.
How did we get here?
As of last PyCon, we planned to migrate all of our documentation work to Docudo, and some time was spent waiting for that project to get ready for prime time rather than writing docs, since we didn’t really have system in place yet. Eventually we found out that Docudo was going to take longer than we had, and found a way to make MoinMoin do most of what we needed, and we transitioned to that.
All that waiting, and the complexities of migrating docs from the Trac to the Wiki slowed our momentum, which was trouble since we were already behind.
How are we doing now?
Given the delays we had, there’s been a surprisingly large amount of work put into the Docs. But there are a couple of issues with some of that documentaiotn. Some of it is written against old versions of TurboGears and needs to be tested against 1.0. And other docs were written up quickly by a user, and need a little love and care before they can become official.
But really, there are a lot of good docs out there. They just need organizing, cleanup and someone to fill in the gaps.
We can’t get back the months that we lost, but we’re definitely moving in the right direction.
According to a rough count I did the other day, I think there are over 250 edits to the Docs in the last month. Which indicates that we are doing better.
You could even say we’re catching up! But as always, we have some way to go, and we could certainly use more help.
What do we still need to do?
I’d like to focus our efforts over the next week or two on four areas:
- Widget Documentation
- Overview Documentation
- Generated API Documentation
- Widget Browser updates
Widgets are still not thoroughly documented, but we’ve come a long way in improving the docs over the last month. There are a number of widget docs in RoughDocs awaiting review, cleanup, and promotion to the official docs.
And we still need a couple of good Overview docs, one for the beginner, and another for people wanting to get involved in development on the TurboGears core.
Jorge Vargas has started the process of getting epydoc generated API documentation ready for the site. Now we just need to get that posted to the website, get a few remaining glitches worked out of the widget API generation, and make generating a new set of API docs part of the release process.
Once we have API generation going well, I’m pretty sure that it will tell us that need to start improving the docstrings in the code in some places.
If we can get these things done, we’ll be in a lot better shape than we are now.
Of course there’s more to do in the longer term.
For example, it would be great to have really comprehensive tutorials for SQLObject and Mochikit. And we could use a lot more Diagrams, and better Documentation for developers who want to get started hacking on TurboGears itself.
And of course, we need to keep our eye on the TurboGears 1.1 development process.
So there’s lots to do, but we have a team of people who are committed to making all of this happen. But it will definitely happen faster if we have help.
There are tasks like verifying that documentation code that was written 8 months ago, still works on TurboGears 1.0, that anybody can do, and that provide a good way to learn more about TurboGears. And we have some docs to convert in to the new reST wiki format.
February 5th, 2007 by Mark Ramm
Christopher Arndt just announced a brand new version of the TurboGears FAQ. Chris has been doing a lot of great work recently on the TurboGears docs, and this is yet another helpful step forward. Thanks Chris!
You can find the new FAQ at:
http://docs.turbogears.org/FAQ
Basically this is an attempt to codify questions that actually are asked frequently on the mailing list, and bring the answers together in one place. There’s already some good information there, but Chris needs help moving answers from the links to the mailing list into the FAQ page itself.
Here’s the request directly from the horse’s mouth.
The FAQ contains (or better: hopefully will contain) answers to questions that
are raised regularly on the mailing list. The document is in draft status for
now, since many answers only consist of a link to a mailing list post. You can
help out by extracting the relevant information from these posts and turn them
into a clear, brief and accurate answer.
If you want to contribute to the FAQ or make requests for new questions with
answers to be added, you are welcome to do so; the page is freely editable by
all. But please read question “How do I add new questions to the FAQ list?”
before you edit the FAQ page.”
I am still in the process of adding references to useful posts in the mailing
list archive, so please check back from time to time, to see if your question
has been added yet or add it yourself.
If you don’t feel comfortable editing the FAQ directly, please feel free to raise questions on the mailing list.