Django tips: documentation and resources

September 4, 2006    Django

Django’s official documentation often draws praise for being well above average for an open-source project, but it’s far from being the only source of useful information for a developer using the framework. Also, articles and tutorials specific to Django aren’t the only useful documentation out there; the Python language in general tends to have tons of great resources. So let’s take a look at some resources you might not know about but should.

Python in general

For someone who’s new to programming in general, or for a programmer who’s new to Python, the official tutorial is quite good, but I personally don’t think there’s any better introduction to the language than Mark Pilgrim’s “Dive Into Python”, which is available for free online. However, the dead-tree edition can be quite nice to cuddle up with, and now it even earns Mark royalties.

The Python standard library is generally applauded for including tons of useful things, and is quite well-documented; if you find yourself wondering, “how would I do this in Python?”, odds are there’s a standard module which can help you out (real live example: tonight in IRC someone’s problem was partially solved by looking at the socket module).

For unofficial documentation and generally useful tips, ActiveState’s Python Cookbook can be pretty hard to beat — if you’ve got a problem the standard modules can’t entirely solve, do a search in the cookbook and you’ll probably find someone else who’s worked through it and posted their code.

And, finally, keep in mind that Python makes it easy for code to document itself, and actively encourages doing so; there’s even a andy trick for viewing that documentation directly. Pop open a Python interpreter, import a module you want to know more about, and type help(modulename) — you’ll get a nicely-formatted listing of all the classes and functions in the module, along with any documentation they include. You can narrow this down if you like, to read only the documentation on a specific class or function. For example, if you wanted to poke around in md5, Python’s module for creating and using MD5 hashes, you could do this:

>>> import md5
>>> help(md5)
... full documentation of the module will appear ...
>>> help(md5.new)
... this just gets the documentation of the 'md5.new' function ...

I use that all the time; it works on anything that has a docstring and it’s indispensible.

Django resources

The help function also lets you explore Django — most of the code has documentation included, and some of that goes into more detail than the official online docs. Often that’s because the extra information in the docstrings is really only useful for people who want to hack on Django instead of hacking with Django, but every now and again you’ll find a useful nugget in there.

Django also makes its documentation — and then some — available through the admin app. In the upper right of each page should be a link labeled “Documentation”, and if you click it (and if your server has the docutils module installed) you’ll see an index of what’s available. Django generates the following documentation automatically:

• A list of all available template tags, grouped by module. Any template tag with a docstring will have its docstring displayed here.
• A list of all available template filters, again grouped by module and including any docstrings.
• A list of all installed models, grouped by application. For each model you’ll see a list of all its fields and methods, along with short descriptions of them if available (for fields, this is the help_text attribute; for methods, it’s the docstring).
• A list of all the views that are actually in use, generated by inspecting your site’s URL configuration. Views are listed by the URLs they correspond to, and the detail page for each view includes its docstring if available.

Django also comes with a wide assortment of documentation, not all of which appears in the online documentation index — usually because it covers something that’s under development, and needs to change with the code. Look in the docs directory of your Django download, or in the online code repository, to browse through these files.

The Django wiki has an assortment of contributed documentation, tips and examples, but should be taken with a grain of salt — there are a lot of pages there which list code samples based on older versions of Django, and they may not work now. Also, occasionally wiki pages pop up with information on topics related to Django’s development, but they tend to get out-of-date extremely quickly; if you’re looking for information on where Django is going, the best place to check is always the archive of the django-developers mailing list.

Similarly, subscribing to the Django community aggregator can be a good way to catch useful things as they’re posted; anyone who writes about Django is free to submit their feed for inclusion in the aggregator (though not everyone who’s aggregated their uses a categorized feed, so you will see some completely non-Django-related posts go by).

The “django” tags on del.icio.us and on ma.gnolia are also good sources of Django-related information, and both of them are available as feeds. There’s also a “planet Django” which tries to aggregate sites that write about Django, and at least one roundup of Django tutorials and tips floating around.

What did I miss?

I know there are more places out there to get solid, useful info on Python and Django, so leave a comment and tell me about them.