python/lib/django_1_4/docs/intro/whatsnext.txt

   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 `docs`_ directory of our Git repository. Each document online is a
  97 separate text file in the repository.
  98
  99 .. _docs: https://github.com/django/django/tree/master/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 https://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: https://code.djangoproject.com/newticket?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 "trunk"), note that the
 142 ``docs/`` directory contains all of the documentation. You can update your
 143 Git checkout to get the latest changes.
 144
 145 One low-tech way of taking advantage of the text documentation is by using the
 146 Unix ``grep`` utility to search for a phrase in all of the documentation. For
 147 example, this will show you each mention of the phrase "max_length" in any
 148 Django document:
 149
 150 .. code-block:: bash
 151
 152     $ grep -r max_length /path/to/django/docs/
 153
 154 As HTML, locally
 155 ----------------
 156
 157 You can get a local copy of the HTML documentation following a few easy steps:
 158
 159 * Django's documentation uses a system called Sphinx__ to convert from
 160   plain text to HTML. You'll need to install Sphinx by either downloading
 161   and installing the package from the Sphinx Web site, or with ``pip``:
 162
 163   .. code-block:: bash
 164
 165         $ sudo pip install Sphinx
 166
 167 * Then, just use the included ``Makefile`` to turn the documentation into
 168   HTML:
 169
 170   .. code-block:: bash
 171
 172         $ cd path/to/django/docs
 173         $ make html
 174
 175   You'll need `GNU Make`__ installed for this.
 176
 177   If you're on Windows you can alternatively use the included batch file:
 178
 179   .. code-block:: bat
 180
 181         cd path\to\django\docs
 182         make.bat html
 183
 184 * The HTML documentation will be placed in ``docs/_build/html``.
 185
 186 .. note::
 187
 188     Generation of the Django documentation will work with Sphinx version 0.6
 189     or newer, but we recommend going straight to Sphinx 1.0.2 or newer.
 190
 191 __ http://sphinx.pocoo.org/
 192 __ http://www.gnu.org/software/make/
 193
 194 .. _differences-between-doc-versions:
 195
 196 Differences between versions
 197 ============================
 198
 199 As previously mentioned, the text documentation in our Git 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 Git ("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 Git. 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 Git 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: https://docs.djangoproject.com/en/dev/