mirror of
https://github.com/django/django.git
synced 2024-12-24 10:05:46 +00:00
31ee120787
Forward-port of 3493f18d78
from master.
234 lines
9.0 KiB
Plaintext
234 lines
9.0 KiB
Plaintext
=================
|
|
What to read next
|
|
=================
|
|
|
|
So you've read all the :doc:`introductory material </intro/index>` and have
|
|
decided you'd like to keep using Django. We've only just scratched the surface
|
|
with this intro (in fact, if you've read every single word, you've read about
|
|
5% of the overall documentation).
|
|
|
|
So what's next?
|
|
|
|
Well, we've always been big fans of learning by doing. At this point you should
|
|
know enough to start a project of your own and start fooling around. As you need
|
|
to learn new tricks, come back to the documentation.
|
|
|
|
We've put a lot of effort into making Django's documentation useful, easy to
|
|
read and as complete as possible. The rest of this document explains more about
|
|
how the documentation works so that you can get the most out of it.
|
|
|
|
(Yes, this is documentation about documentation. Rest assured we have no plans
|
|
to write a document about how to read the document about documentation.)
|
|
|
|
Finding documentation
|
|
=====================
|
|
|
|
Django's got a *lot* of documentation -- almost 450,000 words and counting --
|
|
so finding what you need can sometimes be tricky. A few good places to start
|
|
are the :ref:`search` and the :ref:`genindex`.
|
|
|
|
Or you can just browse around!
|
|
|
|
How the documentation is organized
|
|
==================================
|
|
|
|
Django's main documentation is broken up into "chunks" designed to fill
|
|
different needs:
|
|
|
|
* The :doc:`introductory material </intro/index>` is designed for people new
|
|
to Django -- or to Web development in general. It doesn't cover anything
|
|
in depth, but instead gives a high-level overview of how developing in
|
|
Django "feels".
|
|
|
|
* The :doc:`topic guides </topics/index>`, on the other hand, dive deep into
|
|
individual parts of Django. There are complete guides to Django's
|
|
:doc:`model system </topics/db/index>`, :doc:`template engine
|
|
</topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much
|
|
more.
|
|
|
|
This is probably where you'll want to spend most of your time; if you work
|
|
your way through these guides you should come out knowing pretty much
|
|
everything there is to know about Django.
|
|
|
|
* Web development is often broad, not deep -- problems span many domains.
|
|
We've written a set of :doc:`how-to guides </howto/index>` that answer
|
|
common "How do I ...?" questions. Here you'll find information about
|
|
:doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing
|
|
custom template tags </howto/custom-template-tags>`, and more.
|
|
|
|
Answers to really common questions can also be found in the :doc:`FAQ
|
|
</faq/index>`.
|
|
|
|
* The guides and how-to's don't cover every single class, function, and
|
|
method available in Django -- that would be overwhelming when you're
|
|
trying to learn. Instead, details about individual classes, functions,
|
|
methods, and modules are kept in the :doc:`reference </ref/index>`. This is
|
|
where you'll turn to find the details of a particular function or
|
|
whathaveyou.
|
|
|
|
* If you are interested in deploying a project for public use, our docs have
|
|
:doc:`several guides</howto/deployment/index>` for various deployment
|
|
setups as well as a :doc:`deployment checklist</howto/deployment/checklist>`
|
|
for some things you'll need to think about.
|
|
|
|
* Finally, there's some "specialized" documentation not usually relevant to
|
|
most developers. This includes the :doc:`release notes </releases/index>` and
|
|
:doc:`internals documentation </internals/index>` for those who want to add
|
|
code to Django itself, and a :doc:`few other things that simply don't fit
|
|
elsewhere </misc/index>`.
|
|
|
|
|
|
How documentation is updated
|
|
============================
|
|
|
|
Just as the Django code base is developed and improved on a daily basis, our
|
|
documentation is consistently improving. We improve documentation for several
|
|
reasons:
|
|
|
|
* To make content fixes, such as grammar/typo corrections.
|
|
|
|
* To add information and/or examples to existing sections that need to be
|
|
expanded.
|
|
|
|
* To document Django features that aren't yet documented. (The list of
|
|
such features is shrinking but exists nonetheless.)
|
|
|
|
* To add documentation for new features as new features get added, or as
|
|
Django APIs or behaviors change.
|
|
|
|
Django's documentation is kept in the same source control system as its code. It
|
|
lives in the `docs`_ directory of our Git repository. Each document online is a
|
|
separate text file in the repository.
|
|
|
|
.. _docs: https://github.com/django/django/tree/master/docs
|
|
|
|
Where to get it
|
|
===============
|
|
|
|
You can read Django documentation in several ways. They are, in order of
|
|
preference:
|
|
|
|
On the Web
|
|
----------
|
|
|
|
The most recent version of the Django documentation lives at
|
|
https://docs.djangoproject.com/en/dev/. These HTML pages are generated
|
|
automatically from the text files in source control. That means they reflect the
|
|
"latest and greatest" in Django -- they include the very latest corrections and
|
|
additions, and they discuss the latest Django features, which may only be
|
|
available to users of the Django development version. (See "Differences between
|
|
versions" below.)
|
|
|
|
We encourage you to help improve the docs by submitting changes, corrections and
|
|
suggestions in the `ticket system`_. The Django developers actively monitor the
|
|
ticket system and use your feedback to improve the documentation for everybody.
|
|
|
|
Note, however, that tickets should explicitly relate to the documentation,
|
|
rather than asking broad tech-support questions. If you need help with your
|
|
particular Django setup, try the `django-users mailing list`_ or the `#django
|
|
IRC channel`_ instead.
|
|
|
|
.. _ticket system: https://code.djangoproject.com/newticket?component=Documentation
|
|
.. _django-users mailing list: http://groups.google.com/group/django-users
|
|
.. _#django IRC channel: irc://irc.freenode.net/django
|
|
|
|
In plain text
|
|
-------------
|
|
|
|
For offline reading, or just for convenience, you can read the Django
|
|
documentation in plain text.
|
|
|
|
If you're using an official release of Django, note that the zipped package
|
|
(tarball) of the code includes a ``docs/`` directory, which contains all the
|
|
documentation for that release.
|
|
|
|
If you're using the development version of Django (aka "trunk"), note that the
|
|
``docs/`` directory contains all of the documentation. You can update your
|
|
Git checkout to get the latest changes.
|
|
|
|
One low-tech way of taking advantage of the text documentation is by using the
|
|
Unix ``grep`` utility to search for a phrase in all of the documentation. For
|
|
example, this will show you each mention of the phrase "max_length" in any
|
|
Django document:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ grep -r max_length /path/to/django/docs/
|
|
|
|
As HTML, locally
|
|
----------------
|
|
|
|
You can get a local copy of the HTML documentation following a few easy steps:
|
|
|
|
* Django's documentation uses a system called Sphinx__ to convert from
|
|
plain text to HTML. You'll need to install Sphinx by either downloading
|
|
and installing the package from the Sphinx Web site, or with ``pip``:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ sudo pip install Sphinx
|
|
|
|
* Then, just use the included ``Makefile`` to turn the documentation into
|
|
HTML:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ cd path/to/django/docs
|
|
$ make html
|
|
|
|
You'll need `GNU Make`__ installed for this.
|
|
|
|
If you're on Windows you can alternatively use the included batch file:
|
|
|
|
.. code-block:: bat
|
|
|
|
cd path\to\django\docs
|
|
make.bat html
|
|
|
|
* The HTML documentation will be placed in ``docs/_build/html``.
|
|
|
|
.. note::
|
|
|
|
Generation of the Django documentation will work with Sphinx version 0.6
|
|
or newer, but we recommend going straight to Sphinx 1.0.2 or newer.
|
|
|
|
__ http://sphinx.pocoo.org/
|
|
__ http://www.gnu.org/software/make/
|
|
|
|
.. _differences-between-doc-versions:
|
|
|
|
Differences between versions
|
|
============================
|
|
|
|
As previously mentioned, the text documentation in our Git repository
|
|
contains the "latest and greatest" changes and additions. These changes often
|
|
include documentation of new features added in the Django development version
|
|
-- the Git ("trunk") version of Django. For that reason, it's worth
|
|
pointing out our policy on keeping straight the documentation for various
|
|
versions of the framework.
|
|
|
|
We follow this policy:
|
|
|
|
* The primary documentation on djangoproject.com is an HTML version of the
|
|
latest docs in Git. These docs always correspond to the latest
|
|
official Django release, plus whatever features we've added/changed in
|
|
the framework *since* the latest release.
|
|
|
|
* As we add features to Django's development version, we try to update the
|
|
documentation in the same Git commit transaction.
|
|
|
|
* To distinguish feature changes/additions in the docs, we use the phrase:
|
|
"New in version X.Y", being X.Y the next release version (hence, the one
|
|
being developed).
|
|
|
|
* Documentation fixes and improvements may be backported to the last release
|
|
branch, at the discretion of the committer, however, once a version of
|
|
Django is :ref:`no longer supported<backwards-compatibility-policy>`, that
|
|
version of the docs won't get any further updates.
|
|
|
|
* The `main documentation Web page`_ includes links to documentation for
|
|
all previous versions. Be sure you are using the version of the docs
|
|
corresponding to the version of Django you are using!
|
|
|
|
.. _main documentation Web page: https://docs.djangoproject.com/en/dev/
|