← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal

« back to all changes in this revision

Viewing changes to docs/intro/whatsnext.txt

  • Committer: Bazaar Package Importer
  • Author(s): Scott James Remnant, Eddy Mulyono
  • Date: 2008-09-16 12:18:47 UTC
  • mfrom: (1.1.5 upstream) (4.1.1 lenny)
  • Revision ID: james.westby@ubuntu.com-20080916121847-mg225rg5mnsdqzr0
Tags: 1.0-1ubuntu1
https://launchpad.net/bugs/264191
* Merge from Debian (LP: #264191), remaining changes:
  - Run test suite on build.

[Eddy Mulyono]
* Update patch to workaround network test case failures.

Show diffs side-by-side

added added

removed removed

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