|
1 ================= |
|
2 What to read next |
|
3 ================= |
|
4 |
|
5 So you've read all the :doc:`introductory material </intro/index>` and have |
|
6 decided you'd like to keep using Django. We've only just scratched the surface |
|
7 with this intro (in fact, if you've read every single word you've still read |
|
8 less than 10% of the overall documentation). |
|
9 |
|
10 So what's next? |
|
11 |
|
12 Well, we've always been big fans of learning by doing. At this point you should |
|
13 know enough to start a project of your own and start fooling around. As you need |
|
14 to learn new tricks, come back to the documentation. |
|
15 |
|
16 We've put a lot of effort into making Django's documentation useful, easy to |
|
17 read and as complete as possible. The rest of this document explains more about |
|
18 how the documentation works so that you can get the most out of it. |
|
19 |
|
20 (Yes, this is documentation about documentation. Rest assured we have no plans |
|
21 to write a document about how to read the document about documentation.) |
|
22 |
|
23 Finding documentation |
|
24 ===================== |
|
25 |
|
26 Django's got a *lot* of documentation -- almost 200,000 words -- so finding what |
|
27 you need can sometimes be tricky. A few good places to start are the :ref:`search` |
|
28 and the :ref:`genindex`. |
|
29 |
|
30 Or you can just browse around! |
|
31 |
|
32 How the documentation is organized |
|
33 ================================== |
|
34 |
|
35 Django's main documentation is broken up into "chunks" designed to fill |
|
36 different needs: |
|
37 |
|
38 * The :doc:`introductory material </intro/index>` is designed for people new |
|
39 to Django -- or to Web development in general. It doesn't cover anything |
|
40 in depth, but instead gives a high-level overview of how developing in |
|
41 Django "feels". |
|
42 |
|
43 * The :doc:`topic guides </topics/index>`, on the other hand, dive deep into |
|
44 individual parts of Django. There are complete guides to Django's |
|
45 :doc:`model system </topics/db/index>`, :doc:`template engine |
|
46 </topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much |
|
47 more. |
|
48 |
|
49 This is probably where you'll want to spend most of your time; if you work |
|
50 your way through these guides you should come out knowing pretty much |
|
51 everything there is to know about Django. |
|
52 |
|
53 * Web development is often broad, not deep -- problems span many domains. |
|
54 We've written a set of :doc:`how-to guides </howto/index>` that answer |
|
55 common "How do I ...?" questions. Here you'll find information about |
|
56 :doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing |
|
57 custom template tags </howto/custom-template-tags>`, and more. |
|
58 |
|
59 Answers to really common questions can also be found in the :doc:`FAQ |
|
60 </faq/index>`. |
|
61 |
|
62 * The guides and how-to's don't cover every single class, function, and |
|
63 method available in Django -- that would be overwhelming when you're |
|
64 trying to learn. Instead, details about individual classes, functions, |
|
65 methods, and modules are kept in the :doc:`reference </ref/index>`. This is |
|
66 where you'll turn to find the details of a particular function or |
|
67 whathaveyou. |
|
68 |
|
69 * Finally, there's some "specialized" documentation not usually relevant to |
|
70 most developers. This includes the :doc:`release notes </releases/index>`, |
|
71 :doc:`documentation of obsolete features </obsolete/index>`, |
|
72 :doc:`internals documentation </internals/index>` for those who want to add |
|
73 code to Django itself, and a :doc:`few other things that simply don't fit |
|
74 elsewhere </misc/index>`. |
|
75 |
|
76 |
|
77 How documentation is updated |
|
78 ============================ |
|
79 |
|
80 Just as the Django code base is developed and improved on a daily basis, our |
|
81 documentation is consistently improving. We improve documentation for several |
|
82 reasons: |
|
83 |
|
84 * To make content fixes, such as grammar/typo corrections. |
|
85 |
|
86 * To add information and/or examples to existing sections that need to be |
|
87 expanded. |
|
88 |
|
89 * To document Django features that aren't yet documented. (The list of |
|
90 such features is shrinking but exists nonetheless.) |
|
91 |
|
92 * To add documentation for new features as new features get added, or as |
|
93 Django APIs or behaviors change. |
|
94 |
|
95 Django's documentation is kept in the same source control system as its code. It |
|
96 lives in the `django/trunk/docs`_ directory of our Subversion repository. Each |
|
97 document online is a separate text file in the repository. |
|
98 |
|
99 .. _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docs |
|
100 |
|
101 Where to get it |
|
102 =============== |
|
103 |
|
104 You can read Django documentation in several ways. They are, in order of |
|
105 preference: |
|
106 |
|
107 On the Web |
|
108 ---------- |
|
109 |
|
110 The most recent version of the Django documentation lives at |
|
111 http://docs.djangoproject.com/en/dev/. These HTML pages are generated |
|
112 automatically from the text files in source control. That means they reflect the |
|
113 "latest and greatest" in Django -- they include the very latest corrections and |
|
114 additions, and they discuss the latest Django features, which may only be |
|
115 available to users of the Django development version. (See "Differences between |
|
116 versions" below.) |
|
117 |
|
118 We encourage you to help improve the docs by submitting changes, corrections and |
|
119 suggestions in the `ticket system`_. The Django developers actively monitor the |
|
120 ticket system and use your feedback to improve the documentation for everybody. |
|
121 |
|
122 Note, however, that tickets should explicitly relate to the documentation, |
|
123 rather than asking broad tech-support questions. If you need help with your |
|
124 particular Django setup, try the `django-users mailing list`_ or the `#django |
|
125 IRC channel`_ instead. |
|
126 |
|
127 .. _ticket system: http://code.djangoproject.com/simpleticket?component=Documentation |
|
128 .. _django-users mailing list: http://groups.google.com/group/django-users |
|
129 .. _#django IRC channel: irc://irc.freenode.net/django |
|
130 |
|
131 In plain text |
|
132 ------------- |
|
133 |
|
134 For offline reading, or just for convenience, you can read the Django |
|
135 documentation in plain text. |
|
136 |
|
137 If you're using an official release of Django, note that the zipped package |
|
138 (tarball) of the code includes a ``docs/`` directory, which contains all the |
|
139 documentation for that release. |
|
140 |
|
141 If you're using the development version of Django (aka the Subversion "trunk"), |
|
142 note that the ``docs/`` directory contains all of the documentation. You can |
|
143 ``svn update`` it, just as you ``svn update`` the Python code, in order to get |
|
144 the latest changes. |
|
145 |
|
146 You can check out the latest Django documentation from Subversion using this |
|
147 shell command: |
|
148 |
|
149 .. code-block:: bash |
|
150 |
|
151 $ svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs |
|
152 |
|
153 One low-tech way of taking advantage of the text documentation is by using the |
|
154 Unix ``grep`` utility to search for a phrase in all of the documentation. For |
|
155 example, this will show you each mention of the phrase "max_length" in any |
|
156 Django document: |
|
157 |
|
158 .. code-block:: bash |
|
159 |
|
160 $ grep -r max_length /path/to/django/docs/ |
|
161 |
|
162 As HTML, locally |
|
163 ---------------- |
|
164 |
|
165 You can get a local copy of the HTML documentation following a few easy steps: |
|
166 |
|
167 * Django's documentation uses a system called Sphinx__ to convert from |
|
168 plain text to HTML. You'll need to install Sphinx by either downloading |
|
169 and installing the package from the Sphinx Web site, or by Python's |
|
170 ``easy_install``: |
|
171 |
|
172 .. code-block:: bash |
|
173 |
|
174 $ easy_install Sphinx |
|
175 |
|
176 * Then, just use the included ``Makefile`` to turn the documentation into |
|
177 HTML: |
|
178 |
|
179 .. code-block:: bash |
|
180 |
|
181 $ cd path/to/django/docs |
|
182 $ make html |
|
183 |
|
184 You'll need `GNU Make`__ installed for this. |
|
185 |
|
186 * The HTML documentation will be placed in ``docs/_build/html``. |
|
187 |
|
188 .. note:: |
|
189 |
|
190 Generation of the Django documentation will work with Sphinx version 0.6 |
|
191 or newer, but we recommend going straight to Sphinx 1.0.2 or newer. |
|
192 |
|
193 __ http://sphinx.pocoo.org/ |
|
194 __ http://www.gnu.org/software/make/ |
|
195 |
|
196 Differences between versions |
|
197 ============================ |
|
198 |
|
199 As previously mentioned, the text documentation in our Subversion repository |
|
200 contains the "latest and greatest" changes and additions. These changes often |
|
201 include documentation of new features added in the Django development version |
|
202 -- the Subversion ("trunk") version of Django. For that reason, it's worth |
|
203 pointing out our policy on keeping straight the documentation for various |
|
204 versions of the framework. |
|
205 |
|
206 We follow this policy: |
|
207 |
|
208 * The primary documentation on djangoproject.com is an HTML version of the |
|
209 latest docs in Subversion. These docs always correspond to the latest |
|
210 official Django release, plus whatever features we've added/changed in |
|
211 the framework *since* the latest release. |
|
212 |
|
213 * As we add features to Django's development version, we try to update the |
|
214 documentation in the same Subversion commit transaction. |
|
215 |
|
216 * To distinguish feature changes/additions in the docs, we use the phrase: |
|
217 "New in version X.Y", being X.Y the next release version (hence, the one |
|
218 being developed). |
|
219 |
|
220 * Documentation for a particular Django release is frozen once the version |
|
221 has been released officially. It remains a snapshot of the docs as of the |
|
222 moment of the release. We will make exceptions to this rule in |
|
223 the case of retroactive security updates or other such retroactive |
|
224 changes. Once documentation is frozen, we add a note to the top of each |
|
225 frozen document that says "These docs are frozen for Django version XXX" |
|
226 and links to the current version of that document. |
|
227 |
|
228 * The `main documentation Web page`_ includes links to documentation for |
|
229 all previous versions. |
|
230 |
|
231 .. _main documentation Web page: http://docs.djangoproject.com/en/dev/ |