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/