What to read next

So you’ve read all the introductory material and havedecided you’d like to keep using Django. We’ve only just scratched the surfacewith this intro (in fact, if you’ve read every single word, you’ve read about5% of the overall documentation).

So what’s next?

Well, we’ve always been big fans of learning by doing. At this point you shouldknow enough to start a project of your own and start fooling around. As you needto learn new tricks, come back to the documentation.

We’ve put a lot of effort into making Django’s documentation useful, clear andas complete as possible. The rest of this document explains more about how thedocumentation works so that you can get the most out of it.

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

Finding documentation

Django’s got a lot of documentation – almost 450,000 words and counting –so finding what you need can sometimes be tricky. A few good places to startare the Search Page and the Index.

Or you can just browse around!

How the documentation is organized

Django’s main documentation is broken up into “chunks” designed to filldifferent needs:

  • The introductory material is designed for people newto Django – or to Web development in general. It doesn’t cover anythingin depth, but instead gives a high-level overview of how developing inDjango “feels”.

  • The topic guides, on the other hand, dive deep intoindividual parts of Django. There are complete guides to Django’smodel system, template engine, forms framework, and muchmore.

This is probably where you’ll want to spend most of your time; if you workyour way through these guides you should come out knowing pretty mucheverything there is to know about Django.

Answers to really common questions can also be found in the FAQ.

  • The guides and how-to’s don’t cover every single class, function, andmethod available in Django – that would be overwhelming when you’retrying to learn. Instead, details about individual classes, functions,methods, and modules are kept in the reference. This iswhere you’ll turn to find the details of a particular function orwhatever you need.

  • If you are interested in deploying a project for public use, our docs haveseveral guides for various deploymentsetups as well as a deployment checklistfor some things you’ll need to think about.

  • Finally, there’s some “specialized” documentation not usually relevant tomost developers. This includes the release notes andinternals documentation for those who want to addcode to Django itself, and a few other things that don’t fit elsewhere.

How documentation is updated

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

  • To make content fixes, such as grammar/typo corrections.
  • To add information and/or examples to existing sections that need to beexpanded.
  • To document Django features that aren’t yet documented. (The list ofsuch features is shrinking but exists nonetheless.)
  • To add documentation for new features as new features get added, or asDjango APIs or behaviors change.Django’s documentation is kept in the same source control system as its code. Itlives in the docs directory of our Git repository. Each documentonline is a separate text file in the repository.

Where to get it

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

On the Web

The most recent version of the Django documentation lives athttps://docs.djangoproject.com/en/dev/. These HTML pages are generatedautomatically from the text files in source control. That means they reflect the“latest and greatest” in Django – they include the very latest corrections andadditions, and they discuss the latest Django features, which may only beavailable to users of the Django development version. (SeeDifferences between versions below.)

We encourage you to help improve the docs by submitting changes, corrections andsuggestions in the ticket system. The Django developers actively monitor theticket 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 yourparticular Django setup, try the django-users mailing list or the #djangoIRC channel instead.

In plain text

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

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

If you’re using the development version of Django (aka the master branch), thedocs/ directory contains all of the documentation. You can update yourGit checkout to get the latest changes.

One low-tech way of taking advantage of the text documentation is by using theUnix grep utility to search for a phrase in all of the documentation. Forexample, this will show you each mention of the phrase “max_length” in anyDjango document:

  1. $ grep -r max_length /path/to/django/docs/
  1. ...\> grep -r max_length \path\to\django\docs\

As HTML, locally

You can get a local copy of the HTML documentation following a few steps:

  • Django’s documentation uses a system called Sphinx to convert fromplain text to HTML. You’ll need to install Sphinx by either downloadingand installing the package from the Sphinx website, or with pip:

/

  1. $ python -m pip install Sphinx
  1. ...\> py -m pip install Sphinx
  • Then, use the included Makefile to turn the documentation into HTML:
  1. $ cd path/to/django/docs
  2. $ make html

You’ll need GNU Make installed for this.

If you’re on Windows you can alternatively use the included batch file:

  1. cd path\to\django\docs
  2. make.bat html
  • The HTML documentation will be placed in docs/_build/html.

Differences between versions

The text documentation in the master branch of the Git repository contains the“latest and greatest” changes and additions. These changes includedocumentation of new features targeted for Django’s next featurerelease. For that reason, it’s worth pointing out our policy to highlightrecent changes and additions to Django.

We follow this policy:

  • The development documentation at https://docs.djangoproject.com/en/dev/ isfrom the master branch. These docs correspond to the latest feature release,plus whatever features have been added/changed in the framework since then.
  • As we add features to Django’s development version, we update thedocumentation in the same Git commit transaction.
  • To distinguish feature changes/additions in the docs, we use the phrase:“New in Django Development version” for the version of Django that hasn’tbeen released yet, or “New in version X.Y” for released versions.
  • Documentation fixes and improvements may be backported to the last releasebranch, at the discretion of the committer, however, once a version ofDjango is no longer supported, that versionof the docs won’t get any further updates.
  • The main documentation Web page includes links to documentation forprevious versions. Be sure you are using the version of the docscorresponding to the version of Django you are using!