| 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 read about |
| 8 |
5% 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. There's also a bigger |
| 15 |
`Django ecosystem`_ out there for you to explore that the community has |
| 16 |
created. |
| 17 |
|
| 18 |
We've put a lot of effort into making Django's documentation useful, clear and |
| 19 |
as complete as possible. The rest of this document explains more about how the |
| 20 |
documentation works so that you can get the most out of it. |
| 21 |
|
| 22 |
(Yes, this is documentation about documentation. Rest assured we have no plans |
| 23 |
to write a document about how to read the document about documentation.) |
| 24 |
|
| 25 |
.. _Django ecosystem: https://www.djangoproject.com/community/ecosystem/ |
| 26 |
|
| 27 |
Finding documentation |
| 28 |
===================== |
| 29 |
|
| 30 |
Django's got a *lot* of documentation -- almost 450,000 words and counting -- |
| 31 |
so finding what you need can sometimes be tricky. A good place to start |
| 32 |
is the :ref:`genindex`. We also recommend using the builtin search feature. |
| 33 |
|
| 34 |
Or you can just browse around! |
| 35 |
|
| 36 |
How the documentation is organized |
| 37 |
================================== |
| 38 |
|
| 39 |
Django's main documentation is broken up into "chunks" designed to fill |
| 40 |
different needs: |
| 41 |
|
| 42 |
* The :doc:`introductory material </intro/index>` is designed for people new |
| 43 |
to Django -- or to web development in general. It doesn't cover anything |
| 44 |
in depth, but instead gives a high-level overview of how developing in |
| 45 |
Django "feels". |
| 46 |
|
| 47 |
* The :doc:`topic guides </topics/index>`, on the other hand, dive deep into |
| 48 |
individual parts of Django. There are complete guides to Django's |
| 49 |
:doc:`model system </topics/db/index>`, :doc:`template engine |
| 50 |
</topics/templates>`, :doc:`forms framework </topics/forms/index>`, and much |
| 51 |
more. |
| 52 |
|
| 53 |
This is probably where you'll want to spend most of your time; if you work |
| 54 |
your way through these guides you should come out knowing pretty much |
| 55 |
everything there is to know about Django. |
| 56 |
|
| 57 |
* Web development is often broad, not deep -- problems span many domains. |
| 58 |
We've written a set of :doc:`how-to guides </howto/index>` that answer |
| 59 |
common "How do I ...?" questions. Here you'll find information about |
| 60 |
:doc:`generating PDFs with Django </howto/outputting-pdf>`, :doc:`writing |
| 61 |
custom template tags </howto/custom-template-tags>`, and more. |
| 62 |
|
| 63 |
Answers to really common questions can also be found in the :doc:`FAQ |
| 64 |
</faq/index>`. |
| 65 |
|
| 66 |
* The guides and how-to's don't cover every single class, function, and |
| 67 |
method available in Django -- that would be overwhelming when you're |
| 68 |
trying to learn. Instead, details about individual classes, functions, |
| 69 |
methods, and modules are kept in the :doc:`reference </ref/index>`. This is |
| 70 |
where you'll turn to find the details of a particular function or |
| 71 |
whatever you need. |
| 72 |
|
| 73 |
* If you are interested in deploying a project for public use, our docs have |
| 74 |
:doc:`several guides</howto/deployment/index>` for various deployment |
| 75 |
setups as well as a :doc:`deployment checklist</howto/deployment/checklist>` |
| 76 |
for some things you'll need to think about. |
| 77 |
|
| 78 |
* Finally, there's some "specialized" documentation not usually relevant to |
| 79 |
most developers. This includes the :doc:`release notes </releases/index>` and |
| 80 |
:doc:`internals documentation </internals/index>` for those who want to add |
| 81 |
code to Django itself, and a :doc:`few other things that don't fit elsewhere |
| 82 |
</misc/index>`. |
| 83 |
|
| 84 |
|
| 85 |
How documentation is updated |
| 86 |
============================ |
| 87 |
|
| 88 |
Just as the Django code base is developed and improved on a daily basis, our |
| 89 |
documentation is consistently improving. We improve documentation for several |
| 90 |
reasons: |
| 91 |
|
| 92 |
* To make content fixes, such as grammar/typo corrections. |
| 93 |
|
| 94 |
* To add information and/or examples to existing sections that need to be |
| 95 |
expanded. |
| 96 |
|
| 97 |
* To document Django features that aren't yet documented. (The list of |
| 98 |
such features is shrinking but exists nonetheless.) |
| 99 |
|
| 100 |
* To add documentation for new features as new features get added, or as |
| 101 |
Django APIs or behaviors change. |
| 102 |
|
| 103 |
Django's documentation is kept in the same source control system as its code. It |
| 104 |
lives in the :source:`docs` directory of our Git repository. Each document |
| 105 |
online is a separate text file in the repository. |
| 106 |
|
| 107 |
Where to get it |
| 108 |
=============== |
| 109 |
|
| 110 |
You can read Django documentation in several ways. They are, in order of |
| 111 |
preference: |
| 112 |
|
| 113 |
On the web |
| 114 |
---------- |
| 115 |
|
| 116 |
The most recent version of the Django documentation lives at |
| 117 |
https://docs.djangoproject.com/en/dev/. These HTML pages are generated |
| 118 |
automatically from the text files in source control. That means they reflect the |
| 119 |
"latest and greatest" in Django -- they include the very latest corrections and |
| 120 |
additions, and they discuss the latest Django features, which may only be |
| 121 |
available to users of the Django development version. (See |
| 122 |
:ref:`differences-between-doc-versions` below.) |
| 123 |
|
| 124 |
We encourage you to help improve the docs by submitting changes, corrections and |
| 125 |
suggestions in the `ticket system`_. The Django developers actively monitor the |
| 126 |
ticket system and use your feedback to improve the documentation for everybody. |
| 127 |
|
| 128 |
Note, however, that tickets should explicitly relate to the documentation, |
| 129 |
rather than asking broad tech-support questions. If you need help with your |
| 130 |
particular Django setup, try the `Django Forum`_ or the |
| 131 |
`Django Discord server`_ instead. |
| 132 |
|
| 133 |
.. _ticket system: https://code.djangoproject.com/ |
| 134 |
.. _Django Forum: https://forum.djangoproject.com/ |
| 135 |
.. _Django Discord server: https://chat.djangoproject.com |
| 136 |
|
| 137 |
In plain text |
| 138 |
------------- |
| 139 |
|
| 140 |
For offline reading, or just for convenience, you can read the Django |
| 141 |
documentation in plain text. |
| 142 |
|
| 143 |
If you're using an official release of Django, the zipped package (tarball) of |
| 144 |
the code includes a ``docs/`` directory, which contains all the documentation |
| 145 |
for that release. |
| 146 |
|
| 147 |
If you're using the development version of Django (aka the main branch), the |
| 148 |
``docs/`` directory contains all of the documentation. You can update your |
| 149 |
Git checkout to get the latest changes. |
| 150 |
|
| 151 |
One low-tech way of taking advantage of the text documentation is by using the |
| 152 |
Unix ``grep`` utility to search for a phrase in all of the documentation. For |
| 153 |
example, this will show you each mention of the phrase "max_length" in any |
| 154 |
Django document: |
| 155 |
|
| 156 |
.. console:: |
| 157 |
|
| 158 |
$ grep -r max_length /path/to/django/docs/ |
| 159 |
|
| 160 |
As HTML, locally |
| 161 |
---------------- |
| 162 |
|
| 163 |
You can get a local copy of the HTML documentation following a few steps: |
| 164 |
|
| 165 |
* Django's documentation uses a system called Sphinx__ to convert from |
| 166 |
plain text to HTML. You'll need to install Sphinx by either downloading |
| 167 |
and installing the package from the Sphinx website, or with ``pip``: |
| 168 |
|
| 169 |
.. console:: |
| 170 |
|
| 171 |
$ python -m pip install Sphinx |
| 172 |
|
| 173 |
* Then, use the included ``Makefile`` to turn the documentation into HTML: |
| 174 |
|
| 175 |
.. code-block:: console |
| 176 |
|
| 177 |
$ cd path/to/django/docs |
| 178 |
$ make html |
| 179 |
|
| 180 |
You'll need `GNU Make`__ installed for this. |
| 181 |
|
| 182 |
If you're on Windows you can alternatively use the included batch file: |
| 183 |
|
| 184 |
.. code-block:: bat |
| 185 |
|
| 186 |
cd path\to\django\docs |
| 187 |
make.bat html |
| 188 |
|
| 189 |
* The HTML documentation will be placed in ``docs/_build/html``. |
| 190 |
|
| 191 |
__ https://www.sphinx-doc.org/ |
| 192 |
__ https://www.gnu.org/software/make/ |
| 193 |
|
| 194 |
.. _differences-between-doc-versions: |
| 195 |
|
| 196 |
Differences between versions |
| 197 |
============================ |
| 198 |
|
| 199 |
The text documentation in the main branch of the Git repository contains the |
| 200 |
"latest and greatest" changes and additions. These changes include |
| 201 |
documentation of new features targeted for Django's next :term:`feature |
| 202 |
release <Feature release>`. For that reason, it's worth pointing out our policy |
| 203 |
to highlight recent changes and additions to Django. |
| 204 |
|
| 205 |
We follow this policy: |
| 206 |
|
| 207 |
* The development documentation at https://docs.djangoproject.com/en/dev/ is |
| 208 |
from the main branch. These docs correspond to the latest feature release, |
| 209 |
plus whatever features have been added/changed in the framework since then. |
| 210 |
|
| 211 |
* As we add features to Django's development version, we update the |
| 212 |
documentation in the same Git commit transaction. |
| 213 |
|
| 214 |
* To distinguish feature changes/additions in the docs, we use the phrase: |
| 215 |
"New in Django Development version" for the version of Django that hasn't |
| 216 |
been released yet, or "New in version X.Y" for released versions. |
| 217 |
|
| 218 |
* Documentation fixes and improvements may be backported to the last release |
| 219 |
branch, at the discretion of the merger, however, once a version of Django is |
| 220 |
:ref:`no longer supported<supported-versions-policy>`, that version of the |
| 221 |
docs won't get any further updates. |
| 222 |
|
| 223 |
* The `main documentation web page`_ includes links to documentation for |
| 224 |
previous versions. Be sure you are using the version of the docs |
| 225 |
corresponding to the version of Django you are using! |
| 226 |
|
| 227 |
.. _main documentation web page: https://docs.djangoproject.com/en/dev/ |