Debian Codegraph @

docs/intro/whatsnext.txt

raw
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/