Read the Docs

Over the last few months I’ve really started to love Read the Docs. Several of my favorite projects are hosted on there. Projects such as Fabric, Requests, and Celery are all hosted on there. The list keeps growing, which is great. Read the Docs is a fantastic project that is promoting and unifying documentation even across language boundaries, both human and programming.

I got involved with Read the Docs during the sprints of DjangoCon 2011 as I have mentioned before on my blog. So my opinion isn’t entirely unbiased, but I wouldn’t have gotten involved if I didn’t believe in it and what goals it is pressing towards. I strongly urge others to also contribute, which can come in many forms, such as spreading the word on using Read the Docs, writing docs and posting them on there, filing bug reports on things you find wrong or feature requests for things you think could be done better, or finally by contributing your coding or design skills.

Something that is pretty interesting is there have been a number of projects that aren’t software libraries that have found their way on to Read the Docs. There have been a few books written using Sphinx and then posted on Read the Docs. Notes from various talks and conferences. And recently I stumbled upon a resume that is hosted on there and it got me thinking that I should do the same.

My resume is now hosted on there, though a warning, it is a work in progress. It looks really nice though, and I have access to multiple file types of it that sphinx and Read the Docs have generated, including a PDF. I highly recommend it to anyone that wants to write their resume, have it stand out a bit, but still look really nice.

Basically, this post is just to talk about how much I have come to depend on Read the Docs and to also to encourage people to use and help out in various ways. I love this project and if have ever come across horrible documentation, so should you.

Django Generic Class Based View Tip

Those reading this via a feed reader will have to view the page on my blog as I am using embedded gists. I’ll find a solution for that in the future.

So say you have a base template that looks something like:

And a template that looks like either of these:

It used to be that you could write something like this:

But generic function based views are deprecated and the world is being strongly urged to move to generic class based views. If you would like to get extra_content working with the direct_to_template replacement TemplateView, you can use a view like the following:

And a urls.py like the following using it:

The code used in this blog post can be found in this gist.

Gut Reaction

I’ve always preferred working on the backend of applications, especially web apps. This stems from my lack of confidence in trying to make functional, and pretty, interfaces. This had lead to, by proxy, a strong dislike of JavaScript. Over time I had come to dislike it less, especially with things like jQuery to make the DOM less painful to work with.

This recently changed when I started using Node for little projects here and there. It gave me access to the reactor pattern without having to convolute the syntax of a language I like, such as what Twisted does to Python. It took me a couple weeks to find a project that I could start using Node for, the answer was an IRC bot that I have named ZenIRCBot.

The design of this bot takes the reactor pattern to heart. Using an asynchronous IRC library called node-irc to connect and manage its IRC session it connects and provides me with various events I can listen for and react to. But that is just the core bot, it just takes whatever messages it sees and puts them in a Redis pub/sub channel.

This allows the core bot to remain very simple and just implement a protocol that I have come up with. Then I have services that implement the protocol as well but run as separate processes. This allows me to add or remove functionality to the bot without ever having to log the bot out or restart it. This makes development of services rather rapid as I can write the service, start it, test it, edit it, restart it, and not have to wait for the time it takes the bot to do a full connection.

This also leads to the ability to write services (or in as Eric Holscher did, the core bot) in any language, as long as it implements the protocol. Letting anyone who knows at least one programing language that is listed on this list or can implement a Redis client for the language they are using, can use and contribute to this bot.

The end result of all of this is that I have a new found like for JavaScript, and got better at some skills like using the reactor pattern. If you haven’t tried Node out, I strongly suggest you go play with it, maybe write a service or two for my bot while you’re at it!