1 ====================================
2 How to read the Django documentation
3 ====================================
5 We've put a lot of effort into making Django's documentation useful, easy to
6 read and as complete as possible. Here are a few tips on how to make the best
7 of it, along with some style guidelines.
9 (Yes, this is documentation about documentation. Rest assured we have no plans
10 to write a document about how to read the document about documentation.)
12 How documentation is updated
13 ============================
15 Just as the Django code base is developed and improved on a daily basis, our
16 documentation is consistently improving. We improve documentation for several
19 * To make content fixes, such as grammar/typo corrections.
20 * To add information and/or examples to existing sections that need to be
22 * To document Django features that aren't yet documented. (The list of
23 such features is shrinking but exists nonetheless.)
24 * To add documentation for new features as new features get added, or as
25 Django APIs or behaviors change.
27 Django's documentation is kept in the same source control system as its code.
28 It lives in the `django/trunk/docs`_ directory of our Subversion repository.
29 Each document is a separate text file that covers a narrowly focused topic,
30 such as the "generic views" framework or how to construct a database model.
32 .. _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docs
37 You can read Django documentation in several ways. They are, in order of
43 The most recent version of the Django documentation lives at
44 http://www.djangoproject.com/documentation/ . These HTML pages are generated
45 automatically from the text files in source control every 15 minutes. That
46 means they reflect the "latest and greatest" in Django -- they include the very
47 latest corrections and additions, and they discuss the latest Django features,
48 which may only be available to users of the Django development version. (See
49 "Differences between versions" below.)
51 A key advantage of the Web-based documentation is the comment section at the
52 bottom of each document. This is an area for anybody to submit changes,
53 corrections and suggestions about the given document. The Django developers
54 frequently monitor the comments there and use them to improve the documentation
57 We encourage you to help improve the docs: it's easy! Note, however, that
58 comments should explicitly relate to the documentation, rather than asking
59 broad tech-support questions. If you need help with your particular Django
60 setup, try the `django-users mailing list`_ instead of posting a comment to the
63 .. _django-users mailing list: http://groups.google.com/group/django-users
68 For offline reading, or just for convenience, you can read the Django
69 documentation in plain text.
71 If you're using an official release of Django, note that the zipped package
72 (tarball) of the code includes a ``docs/`` directory, which contains all the
73 documentation for that release.
75 If you're using the development version of Django (aka the Subversion "trunk"),
76 note that the ``docs/`` directory contains all of the documentation. You can
77 ``svn update`` it, just as you ``svn update`` the Python code, in order to get
80 You can check out the latest Django documentation from Subversion using this
83 svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs
85 One low-tech way of taking advantage of the text documentation is by using the
86 Unix ``grep`` utility to search for a phrase in all of the documentation. For
87 example, this will show you each mention of the phrase "edit_inline" in any
90 grep edit_inline /path/to/django/docs/*.txt
95 The text documentation is written in ReST (ReStructured Text) format. That
96 means it's easy to read but is also formatted in a way that makes it easy to
97 convert into other formats, such as HTML. If you're interested, the script that
98 converts the ReST text docs into djangoproject.com's HTML lives at
99 `djangoproject.com/django_website/apps/docs/parts/build_documentation.py`_ in
100 the Django Subversion repository.
102 .. _djangoproject.com/django_website/apps/docs/parts/build_documentation.py: http://code.djangoproject.com/browser/djangoproject.com/django_website/apps/docs/parts/build_documentation.py
104 Differences between versions
105 ============================
107 As previously mentioned, the text documentation in our Subversion repository
108 contains the "latest and greatest" changes and additions. These changes often
109 include documentation of new features added in the Django development version
110 -- the Subversion ("trunk") version of Django. For that reason, it's worth
111 pointing out our policy on keeping straight the documentation for various
112 versions of the framework.
114 We follow this policy:
116 * The primary documentation on djangoproject.com is an HTML version of the
117 latest docs in Subversion. These docs always correspond to the latest
118 official Django release, plus whatever features we've added/changed in
119 the framework *since* the latest release.
121 * As we add features to Django's development version, we try to update the
122 documentation in the same Subversion commit transaction.
124 * To distinguish feature changes/additions in the docs, we use the phrase
125 **New in Django development version**. In practice, this means that the
126 current documentation on djangoproject.com can be used by users of either
127 the latest release *or* the development version.
129 * Documentation for a particular Django release is frozen once the version
130 has been released officially. It remains a snapshot of the docs as of the
131 moment of the release. We will make exceptions to this rule in
132 the case of retroactive security updates or other such retroactive
133 changes. Once documentation is frozen, we add a note to the top of each
134 frozen document that says "These docs are frozen for Django version XXX"
135 and links to the current version of that document.
137 * Once a document is frozen for a Django release, we remove comments from
138 that page, in favor of having comments on the latest version of that
139 document. This is for the sake of maintainability and usability, so that
140 users have one, and only one, place to leave comments on a particular
141 document. We realize that some people may be stuck on a previous version
142 of Django, but we believe the usability problems with multiple versions
143 of a document the outweigh the benefits.
145 * The `main documentation Web page`_ includes links to documentation for
146 all previous versions.
148 .. _main documentation Web page: http://www.djangoproject.com/documentation/