|
1 ==================================== |
|
2 How to read the Django documentation |
|
3 ==================================== |
|
4 |
|
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. |
|
8 |
|
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.) |
|
11 |
|
12 How documentation is updated |
|
13 ============================ |
|
14 |
|
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 |
|
17 reasons: |
|
18 |
|
19 * To make content fixes, such as grammar/typo corrections. |
|
20 * To add information and/or examples to existing sections that need to be |
|
21 expanded. |
|
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. |
|
26 |
|
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. |
|
31 |
|
32 .. _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docs |
|
33 |
|
34 Where to get it |
|
35 =============== |
|
36 |
|
37 You can read Django documentation in several ways. They are, in order of |
|
38 preference: |
|
39 |
|
40 On the Web |
|
41 ---------- |
|
42 |
|
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.) |
|
50 |
|
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 |
|
55 for everybody. |
|
56 |
|
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 |
|
61 documentation. |
|
62 |
|
63 .. _django-users mailing list: http://groups.google.com/group/django-users |
|
64 |
|
65 In plain text |
|
66 ------------- |
|
67 |
|
68 For offline reading, or just for convenience, you can read the Django |
|
69 documentation in plain text. |
|
70 |
|
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. |
|
74 |
|
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 |
|
78 the latest changes. |
|
79 |
|
80 You can check out the latest Django documentation from Subversion using this |
|
81 shell command:: |
|
82 |
|
83 svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs |
|
84 |
|
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 |
|
88 Django document:: |
|
89 |
|
90 grep edit_inline /path/to/django/docs/*.txt |
|
91 |
|
92 Formatting |
|
93 ~~~~~~~~~~ |
|
94 |
|
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. |
|
101 |
|
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 |
|
103 |
|
104 Differences between versions |
|
105 ============================ |
|
106 |
|
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. |
|
113 |
|
114 We follow this policy: |
|
115 |
|
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. |
|
120 |
|
121 * As we add features to Django's development version, we try to update the |
|
122 documentation in the same Subversion commit transaction. |
|
123 |
|
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. |
|
128 |
|
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. |
|
136 |
|
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. |
|
144 |
|
145 * The `main documentation Web page`_ includes links to documentation for |
|
146 all previous versions. |
|
147 |
|
148 .. _main documentation Web page: http://www.djangoproject.com/documentation/ |