So you’ve read all the introductory material and have\ndecided you’d like to keep using Django. We’ve only just scratched the surface\nwith this intro (in fact, if you’ve read every single word, you’ve read about\n5% of the overall documentation).
\nSo what’s next?
\nWell, we’ve always been big fans of learning by doing. At this point you should\nknow enough to start a project of your own and start fooling around. As you need\nto learn new tricks, come back to the documentation.
\nWe’ve put a lot of effort into making Django’s documentation useful, easy to\nread and as complete as possible. The rest of this document explains more about\nhow the documentation works so that you can get the most out of it.
\n(Yes, this is documentation about documentation. Rest assured we have no plans\nto write a document about how to read the document about documentation.)
\nDjango’s got a lot of documentation – almost 450,000 words and counting –\nso finding what you need can sometimes be tricky. A few good places to start\nare the search and the Index.
\nOr you can just browse around!
\nDjango’s main documentation is broken up into “chunks” designed to fill\ndifferent needs:
\nThe introductory material is designed for people new\nto Django – or to Web development in general. It doesn’t cover anything\nin depth, but instead gives a high-level overview of how developing in\nDjango “feels”.
The topic guides, on the other hand, dive deep into\nindividual parts of Django. There are complete guides to Django’s\nmodel system, template engine, forms framework, and much\nmore.
\nThis is probably where you’ll want to spend most of your time; if you work\nyour way through these guides you should come out knowing pretty much\neverything there is to know about Django.
\nWeb development is often broad, not deep – problems span many domains.\nWe’ve written a set of how-to guides that answer\ncommon “How do I …?” questions. Here you’ll find information about\ngenerating PDFs with Django, writing\ncustom template tags, and more.
\nAnswers to really common questions can also be found in the FAQ.
\nThe guides and how-to’s don’t cover every single class, function, and\nmethod available in Django – that would be overwhelming when you’re\ntrying to learn. Instead, details about individual classes, functions,\nmethods, and modules are kept in the reference. This is\nwhere you’ll turn to find the details of a particular function or\nwhatever you need.
If you are interested in deploying a project for public use, our docs have\nseveral guides for various deployment\nsetups as well as a deployment checklist\nfor some things you’ll need to think about.
Finally, there’s some “specialized” documentation not usually relevant to\nmost developers. This includes the release notes and\ninternals documentation for those who want to add\ncode to Django itself, and a few other things that simply don’t fit\nelsewhere.
Just as the Django code base is developed and improved on a daily basis, our\ndocumentation is consistently improving. We improve documentation for several\nreasons:
\nTo make content fixes, such as grammar/typo corrections.
To add information and/or examples to existing sections that need to be\nexpanded.
To document Django features that aren’t yet documented. (The list of\nsuch features is shrinking but exists nonetheless.)
To add documentation for new features as new features get added, or as\nDjango APIs or behaviors change.
Django’s documentation is kept in the same source control system as its code. It\nlives in the docs directory of our Git repository. Each document online is a\nseparate text file in the repository.
\nYou can read Django documentation in several ways. They are, in order of\npreference:
\nThe most recent version of the Django documentation lives at\nhttps://docs.djangoproject.com/en/dev/. These HTML pages are generated\nautomatically from the text files in source control. That means they reflect the\n“latest and greatest” in Django – they include the very latest corrections and\nadditions, and they discuss the latest Django features, which may only be\navailable to users of the Django development version. (See “Differences between\nversions” below.)
\nWe encourage you to help improve the docs by submitting changes, corrections and\nsuggestions in the ticket system. The Django developers actively monitor the\nticket system and use your feedback to improve the documentation for everybody.
\nNote, however, that tickets should explicitly relate to the documentation,\nrather than asking broad tech-support questions. If you need help with your\nparticular Django setup, try the django-users mailing list or the #django\nIRC channel instead.
\nFor offline reading, or just for convenience, you can read the Django\ndocumentation in plain text.
\nIf you’re using an official release of Django, note that the zipped package\n(tarball) of the code includes a docs/ directory, which contains all the\ndocumentation for that release.
If you’re using the development version of Django (aka “trunk”), note that the\ndocs/ directory contains all of the documentation. You can update your\nGit checkout to get the latest changes.
One low-tech way of taking advantage of the text documentation is by using the\nUnix grep utility to search for a phrase in all of the documentation. For\nexample, this will show you each mention of the phrase “max_length” in any\nDjango document:
$ grep -r max_length /path/to/django/docs/\nYou can get a local copy of the HTML documentation following a few easy steps:
\nDjango’s documentation uses a system called Sphinx to convert from\nplain text to HTML. You’ll need to install Sphinx by either downloading\nand installing the package from the Sphinx Web site, or with pip:
$ pip install Sphinx\nThen, just use the included Makefile to turn the documentation into\nHTML:
$ cd path/to/django/docs\n$ make html\nYou’ll need GNU Make installed for this.
\nIf you’re on Windows you can alternatively use the included batch file:
\ncd path\\to\\django\\docs\nmake.bat html\nThe HTML documentation will be placed in docs/_build/html.
As previously mentioned, the text documentation in our Git repository\ncontains the “latest and greatest” changes and additions. These changes often\ninclude documentation of new features added in the Django development version\n– the Git (“trunk”) version of Django. For that reason, it’s worth\npointing out our policy on keeping straight the documentation for various\nversions of the framework.
\nWe follow this policy:
\nThe primary documentation on djangoproject.com is an HTML version of the\nlatest docs in Git. These docs always correspond to the latest\nofficial Django release, plus whatever features we’ve added/changed in\nthe framework since the latest release.
As we add features to Django’s development version, we try to update the\ndocumentation in the same Git commit transaction.
To distinguish feature changes/additions in the docs, we use the phrase:\n“New in version X.Y”, being X.Y the next release version (hence, the one\nbeing developed).
Documentation fixes and improvements may be backported to the last release\nbranch, at the discretion of the committer, however, once a version of\nDjango is no longer supported, that\nversion of the docs won’t get any further updates.
The main documentation Web page includes links to documentation for\nall previous versions. Be sure you are using the version of the docs\ncorresponding to the version of Django you are using!