PageRenderTime 100ms CodeModel.GetById 93ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/intro/whatsnext.txt

https://code.google.com/p/mango-py/
Plain Text | 231 lines | 166 code | 65 blank | 0 comment | 0 complexity | ad720ee1677cdc0e3599cb1fb9a4b452 MD5 | raw file
  1=================
  2What to read next
  3=================
  4
  5So you've read all the :doc:`introductory material </intro/index>` and have
  6decided you'd like to keep using Django. We've only just scratched the surface
  7with this intro (in fact, if you've read every single word you've still read
  8less than 10% of the overall documentation).
  9
 10So what's next?
 11
 12Well, we've always been big fans of learning by doing. At this point you should
 13know enough to start a project of your own and start fooling around. As you need
 14to learn new tricks, come back to the documentation.
 15
 16We've put a lot of effort into making Django's documentation useful, easy to
 17read and as complete as possible. The rest of this document explains more about
 18how 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
 21to write a document about how to read the document about documentation.)
 22
 23Finding documentation
 24=====================
 25
 26Django's got a *lot* of documentation -- almost 200,000 words -- so finding what
 27you need can sometimes be tricky. A few good places to start are the :ref:`search`
 28and the :ref:`genindex`.
 29
 30Or you can just browse around!
 31
 32How the documentation is organized
 33==================================
 34
 35Django's main documentation is broken up into "chunks" designed to fill
 36different 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
 77How documentation is updated
 78============================
 79
 80Just as the Django code base is developed and improved on a daily basis, our
 81documentation is consistently improving. We improve documentation for several
 82reasons:
 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
 95Django's documentation is kept in the same source control system as its code. It
 96lives in the `django/trunk/docs`_ directory of our Subversion repository. Each
 97document online is a separate text file in the repository.
 98
 99.. _django/trunk/docs: http://code.djangoproject.com/browser/django/trunk/docs
100
101Where to get it
102===============
103
104You can read Django documentation in several ways. They are, in order of
105preference:
106
107On the Web
108----------
109
110The most recent version of the Django documentation lives at
111http://docs.djangoproject.com/en/dev/. These HTML pages are generated
112automatically 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
114additions, and they discuss the latest Django features, which may only be
115available to users of the Django development version. (See "Differences between
116versions" below.)
117
118We encourage you to help improve the docs by submitting changes, corrections and
119suggestions in the `ticket system`_. The Django developers actively monitor the
120ticket system and use your feedback to improve the documentation for everybody.
121
122Note, however, that tickets should explicitly relate to the documentation,
123rather than asking broad tech-support questions. If you need help with your
124particular Django setup, try the `django-users mailing list`_ or the `#django
125IRC 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
131In plain text
132-------------
133
134For offline reading, or just for convenience, you can read the Django
135documentation in plain text.
136
137If 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
139documentation for that release.
140
141If you're using the development version of Django (aka the Subversion "trunk"),
142note 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
144the latest changes.
145
146You can check out the latest Django documentation from Subversion using this
147shell command:
148
149.. code-block:: bash
150
151    $ svn co http://code.djangoproject.com/svn/django/trunk/docs/ django_docs
152
153One low-tech way of taking advantage of the text documentation is by using the
154Unix ``grep`` utility to search for a phrase in all of the documentation. For
155example, this will show you each mention of the phrase "max_length" in any
156Django document:
157
158.. code-block:: bash
159
160    $ grep -r max_length /path/to/django/docs/
161
162As HTML, locally
163----------------
164
165You 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
196Differences between versions
197============================
198
199As previously mentioned, the text documentation in our Subversion repository
200contains the "latest and greatest" changes and additions. These changes often
201include documentation of new features added in the Django development version
202-- the Subversion ("trunk") version of Django. For that reason, it's worth
203pointing out our policy on keeping straight the documentation for various
204versions of the framework.
205
206We 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/