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/