How to read the Django documentation

This document is for Django's SVN release, which can be significantly different from previous releases. Get old docs here: 0.96, 0.95.

We’ve put a lot of effort into making Django’s documentation useful, easy to read and as complete as possible. Here are a few tips on how to make the best of it, along with some style guidelines.

(Yes, this is documentation about documentation. Rest assured we have no plans to write a document about how to read the document about documentation.)

How documentation is updated

Just as the Django code base is developed and improved on a daily basis, our documentation is consistently improving. We improve documentation for several reasons:

To make content fixes, such as grammar/typo corrections.
To add information and/or examples to existing sections that need to be expanded.
To document Django features that aren’t yet documented. (The list of such features is shrinking but exists nonetheless.)
To add documentation for new features as new features get added, or as Django APIs or behaviors change.

Django’s documentation is kept in the same source control system as its code. It lives in the django/trunk/docs directory of our Subversion repository. Each document is a separate text file that covers a narrowly focused topic, such as the “generic views” framework or how to construct a database model.

Where to get it

You can read Django documentation in several ways. They are, in order of preference:

On the Web

The most recent version of the Django documentation lives at http://www.djangoproject.com/documentation/ . These HTML pages are generated automatically from the text files in source control. That means they reflect the “latest and greatest” in Django — they include the very latest corrections and additions, and they discuss the latest Django features, which may only be available to users of the Django development version. (See “Differences between versions” below.)

We encourage you to help improve the docs by submitting changes, corrections and suggestions in the ticket system. The Django developers actively monitor the ticket system and use your feedback to improve the documentation for everybody.

Note, however, that tickets should explicitly relate to the documentation, rather than asking broad tech-support questions. If you need help with your particular Django setup, try the django-users mailing list or the #django IRC channel instead.

In plain text

For offline reading, or just for convenience, you can read the Django documentation in plain text.

If you’re using an official release of Django, note that the zipped package (tarball) of the code includes a docs/ directory, which contains all the documentation for that release.

If you’re using the development version of Django (aka the Subversion “trunk”), note that the docs/ directory contains all of the documentation. You can svn update it, just as you svn update the Python code, in order to get the latest changes.

You can check out the latest Django documentation from Subversion using this shell command:

svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs

One low-tech way of taking advantage of the text documentation is by using the Unix grep utility to search for a phrase in all of the documentation. For example, this will show you each mention of the phrase “edit_inline” in any Django document:

grep edit_inline /path/to/django/docs/*.txt

Formatting

The text documentation is written in ReST (ReStructured Text) format. That means it’s easy to read but is also formatted in a way that makes it easy to convert into other formats, such as HTML. If you have the reStructuredText library installed, you can use rst2html to generate your own HTML files.

Differences between versions

As previously mentioned, the text documentation in our Subversion repository contains the “latest and greatest” changes and additions. These changes often include documentation of new features added in the Django development version — the Subversion (“trunk”) version of Django. For that reason, it’s worth pointing out our policy on keeping straight the documentation for various versions of the framework.

We follow this policy:

The primary documentation on djangoproject.com is an HTML version of the latest docs in Subversion. These docs always correspond to the latest official Django release, plus whatever features we’ve added/changed in the framework since the latest release.
As we add features to Django’s development version, we try to update the documentation in the same Subversion commit transaction.
To distinguish feature changes/additions in the docs, we use the phrase New in Django development version. In practice, this means that the current documentation on djangoproject.com can be used by users of either the latest release or the development version.
Documentation for a particular Django release is frozen once the version has been released officially. It remains a snapshot of the docs as of the moment of the release. We will make exceptions to this rule in the case of retroactive security updates or other such retroactive changes. Once documentation is frozen, we add a note to the top of each frozen document that says “These docs are frozen for Django version XXX” and links to the current version of that document.
The main documentation Web page includes links to documentation for all previous versions.

Questions/Feedback

If you notice errors with this documentation, please open a ticket and let us know!

Please only use the ticket tracker for criticisms and improvements on the docs. For tech support, ask in the IRC channel or post to the django-users list.

Django documentation