Debian Codegraph @

docs/internals/contributing/writing-documentation.txt

raw
1 =====================
2 Writing documentation
3 =====================
4
5 We place high importance on the consistency and readability of documentation.
6 After all, Django was created in a journalism environment! So we treat our
7 documentation like we treat our code: we aim to improve it as often as
8 possible.
9
10 Documentation changes generally come in two forms:
11
12 * General improvements: typo corrections, error fixes and better
13 explanations through clearer writing and more examples.
14
15 * New features: documentation of features that have been added to the
16 framework since the last release.
17
18 This section explains how writers can craft their documentation changes
19 in the most useful and least error-prone ways.
20
21 The Django documentation process
22 ================================
23
24 Though Django's documentation is intended to be read as HTML at
25 https://docs.djangoproject.com/, we edit it as a collection of plain text files
26 written in the reStructuredText markup language for maximum flexibility.
27
28 We work from the development version of the repository because it has the
29 latest-and-greatest documentation, just as it has the latest-and-greatest code.
30
31 We also backport documentation fixes and improvements, at the discretion of the
32 merger, to the last release branch. This is because it's advantageous to
33 have the docs for the last release be up-to-date and correct (see
34 :ref:`differences-between-doc-versions`).
35
36 Django's documentation uses the Sphinx__ documentation system, which in turn
37 is based on docutils__. The basic idea is that lightly-formatted plain-text
38 documentation is transformed into HTML, PDF, and any other output format.
39
40 __ https://www.sphinx-doc.org/
41 __ https://docutils.sourceforge.io/
42
43 Sphinx includes a ``sphinx-build`` command for turning reStructuredText into
44 other formats, e.g., HTML and PDF. This command is configurable, but the Django
45 documentation includes a ``Makefile`` that provides a shorter ``make html``
46 command.
47
48 How the documentation is organized
49 ==================================
50
51 The documentation is organized into several categories:
52
53 * :doc:`Tutorials </intro/index>` take the reader by the hand through a series
54 of steps to create something.
55
56 The important thing in a tutorial is to help the reader achieve something
57 useful, preferably as early as possible, in order to give them confidence.
58
59 Explain the nature of the problem we're solving, so that the reader
60 understands what we're trying to achieve. Don't feel that you need to begin
61 with explanations of how things work - what matters is what the reader does,
62 not what you explain. It can be helpful to refer back to what you've done and
63 explain afterward.
64
65 * :doc:`Topic guides </topics/index>` aim to explain a concept or subject at a
66 fairly high level.
67
68 Link to reference material rather than repeat it. Use examples and don't be
69 reluctant to explain things that seem very basic to you - it might be the
70 explanation someone else needs.
71
72 Providing background context helps a newcomer connect the topic to things
73 that they already know.
74
75 * :doc:`Reference guides </ref/index>` contain technical references for APIs.
76 They describe the functioning of Django's internal machinery and instruct in
77 its use.
78
79 Keep reference material tightly focused on the subject. Assume that the
80 reader already understands the basic concepts involved but needs to know or
81 be reminded of how Django does it.
82
83 Reference guides aren't the place for general explanation. If you find
84 yourself explaining basic concepts, you may want to move that material to a
85 topic guide.
86
87 * :doc:`How-to guides </howto/index>` are recipes that take the reader through
88 steps in key subjects.
89
90 What matters most in a how-to guide is what a user wants to achieve.
91 A how-to should always be result-oriented rather than focused on internal
92 details of how Django implements whatever is being discussed.
93
94 These guides are more advanced than tutorials and assume some knowledge about
95 how Django works. Assume that the reader has followed the tutorials and don't
96 hesitate to refer the reader back to the appropriate tutorial rather than
97 repeat the same material.
98
99 How to start contributing documentation
100 =======================================
101
102 Clone the Django repository to your local machine
103 -------------------------------------------------
104
105 If you'd like to start contributing to our docs, get the development version of
106 Django from the source code repository (see
107 :ref:`installing-development-version`):
108
109 .. console::
110
111 $ git clone https://github.com/django/django.git
112
113 If you're planning to submit these changes, you might find it useful to make a
114 fork of the Django repository and clone this fork instead.
115
116 Set up a virtual environment and install dependencies
117 -----------------------------------------------------
118
119 Create and activate a virtual environment, then install the dependencies:
120
121 .. code-block:: shell
122
123 $ python -m venv .venv
124 $ source .venv/bin/activate
125 $ python -m pip install -r docs/requirements.txt
126
127 Build the documentation locally
128 -------------------------------
129
130 We can build HTML output from the ``docs`` directory:
131
132 .. console::
133
134 $ cd docs
135 $ make html
136
137 Your locally-built documentation will be accessible at
138 ``_build/html/index.html`` and it can be viewed in any web browser, though it
139 will be themed differently than the documentation at
140 `docs.djangoproject.com <https://docs.djangoproject.com/>`_. This is OK! If
141 your changes look good on your local machine, they'll look good on the website.
142
143 Making edits to the documentation
144 ---------------------------------
145
146 The source files are ``.txt`` files located in the ``docs/`` directory.
147
148 These files are written in the reStructuredText markup language. To learn the
149 markup, see the :ref:`reStructuredText reference <sphinx:rst-index>`.
150
151 To edit this page, for example, we would edit the file
152 :source:`docs/internals/contributing/writing-documentation.txt` and rebuild the
153 HTML with ``make html``.
154
155 .. _documentation-checks:
156
157 Documentation quality checks
158 ----------------------------
159
160 Several checks help maintain Django's documentation quality, including
161 :ref:`spelling <documentation-spelling-check>` and
162 :ref:`code block formatting <documentation-code-block-format-check>`.
163
164 These checks are run automatically in CI and must pass before documentation
165 changes can be merged. They can also be run locally with a single command:
166
167 .. console::
168
169 $ make check
170
171 This command runs all current checks and will include any new checks added in
172 the future.
173
174 .. _documentation-spelling-check:
175
176 Spelling check
177 ~~~~~~~~~~~~~~
178
179 Before you commit your docs, it's a good idea to run the spelling checker.
180 You'll need to install :pypi:`sphinxcontrib-spelling` first. Then from the
181 ``docs`` directory, run:
182
183 .. console::
184
185 $ make spelling
186
187 Wrong words (if any) along with the file and line number where they occur will
188 be saved to ``_build/spelling/output.txt``.
189
190 If you encounter false-positives (error output that actually is correct), do
191 one of the following:
192
193 * Surround inline code or brand/technology names with double grave accents
194 (``).
195 * Find synonyms that the spell checker recognizes.
196 * If, and only if, you are sure the word you are using is correct - add it
197 to ``docs/spelling_wordlist`` (please keep the list in alphabetical order).
198
199 .. _documentation-code-block-format-check:
200
201 Code block format check
202 ~~~~~~~~~~~~~~~~~~~~~~~
203
204 All Python code blocks should be formatted using the :pypi:`blacken-docs`
205 auto-formatter. This is automatically run by the :ref:`pre-commit hook
206 <coding-style-pre-commit>` if configured.
207
208 The check can also be run manually: provided that ``blacken-docs`` is installed,
209 run the following command from the ``docs`` directory:
210
211 .. console::
212
213 $ make black
214
215 The formatter will report any issues by printing them to the terminal and will
216 reformat code blocks where possible.
217
218 .. _documentation-link-check:
219
220 Link check
221 ----------
222
223 Links in documentation can become broken or changed such that they are no
224 longer the canonical link. Sphinx provides a builder that can check whether the
225 links in the documentation are working. From the ``docs`` directory, run:
226
227 .. console::
228
229 $ make linkcheck
230
231 Output is printed to the terminal, but can also be found in
232 ``_build/linkcheck/output.txt`` and ``_build/linkcheck/output.json``.
233
234 .. warning::
235
236 The execution of the command requires an internet connection and takes
237 several minutes to complete, because the command tests all the links
238 that are found in the documentation.
239
240 Entries that have a status of "working" are fine, those that are "unchecked" or
241 "ignored" have been skipped because they either cannot be checked or have
242 matched ignore rules in the configuration.
243
244 Entries that have a status of "broken" need to be fixed. Those that have a
245 status of "redirected" may need to be updated to point to the canonical
246 location, e.g. the scheme has changed ``http://`` → ``https://``. In certain
247 cases, we do not want to update a "redirected" link, e.g. a rewrite to always
248 point to the latest or stable version of the documentation, e.g. ``/en/stable/`` →
249 ``/en/3.2/``.
250
251 Writing style
252 =============
253
254 When using pronouns in reference to a hypothetical person, such as "a user with
255 a session cookie", gender-neutral pronouns (they/their/them) should be used.
256 Instead of:
257
258 * he or she... use they.
259 * him or her... use them.
260 * his or her... use their.
261 * his or hers... use theirs.
262 * himself or herself... use themselves.
263
264 Try to avoid using words that minimize the difficulty involved in a task or
265 operation, such as "easily", "simply", "just", "merely", "straightforward", and
266 so on. People's experience may not match your expectations, and they may become
267 frustrated when they do not find a step as "straightforward" or "simple" as it
268 is implied to be.
269
270 Commonly used terms
271 ===================
272
273 Here are some style guidelines on commonly used terms throughout the
274 documentation:
275
276 * **Django** -- when referring to the framework, capitalize Django. It is
277 lowercase only in Python code and in the djangoproject.com logo.
278
279 * **email** -- no hyphen.
280
281 * **HTTP** -- the expected pronunciation is "Aitch Tee Tee Pee" and therefore
282 should be preceded by "an" and not "a".
283
284 * **MySQL**, **PostgreSQL**, **SQLite**
285
286 * **SQL** -- when referring to SQL, the expected pronunciation should be
287 "Ess Queue Ell" and not "sequel". Thus in a phrase like "Returns an
288 SQL expression", "SQL" should be preceded by "an" and not "a".
289
290 * **Python** -- when referring to the language, capitalize Python.
291
292 * **realize**, **customize**, **initialize**, etc. -- use the American
293 "ize" suffix, not "ise."
294
295 * **subclass** -- it's a single word without a hyphen, both as a verb
296 ("subclass that model") and as a noun ("create a subclass").
297
298 * **the web**, **web framework** -- it's not capitalized.
299
300 * **website** -- use one word, without capitalization.
301
302 Django-specific terminology
303 ===========================
304
305 * **model** -- it's not capitalized.
306
307 * **template** -- it's not capitalized.
308
309 * **URLconf** -- use three capitalized letters, with no space before
310 "conf."
311
312 * **view** -- it's not capitalized.
313
314 Guidelines for reStructuredText files
315 =====================================
316
317 These guidelines regulate the format of our reST (reStructuredText)
318 documentation:
319
320 * In section titles, capitalize only initial words and proper nouns.
321
322 * Wrap the documentation at 80 characters wide, unless a code example
323 is significantly less readable when split over two lines, or for another
324 good reason.
325
326 * The main thing to keep in mind as you write and edit docs is that the
327 more semantic markup you can add the better. So:
328
329 .. code-block:: rst
330
331 Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
332
333 Isn't nearly as helpful as:
334
335 .. code-block:: rst
336
337 Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
338
339 This is because Sphinx will generate proper links for the latter, which
340 greatly helps readers.
341
342 You can prefix the target with a ``~`` (that's a tilde) to get only the
343 "last bit" of that path. So ``:mod:`~django.contrib.auth``` will
344 display a link with the title "auth".
345
346 * Use :mod:`~sphinx.ext.intersphinx` to reference Python's and Sphinx'
347 documentation.
348
349 * Add ``.. code-block:: <lang>`` to literal blocks so that they get
350 highlighted. Prefer relying on automatic highlighting using ``::``
351 (two colons). This has the benefit that if the code contains some invalid
352 syntax, it won't be highlighted. Adding ``.. code-block:: python``, for
353 example, will force highlighting despite invalid syntax.
354
355 * To improve readability, use ``.. admonition:: Descriptive title`` rather than
356 ``.. note::``. Use these boxes sparingly.
357
358 * Use these heading styles:
359
360 .. code-block:: rst
361
362 ===
363 One
364 ===
365
366 Two
367 ===
368
369 Three
370 -----
371
372 Four
373 ~~~~
374
375 Five
376 ^^^^
377
378 * Use :rst:role:`:rfc:<rfc>` to reference a Request for Comments (RFC) and
379 try to link to the relevant section if possible. For example, use
380 ``:rfc:`2324#section-2.3.2``` or
381 ``:rfc:`Custom link text <2324#section-2.3.2>```.
382
383 * Use :rst:role:`:pep:<pep>` to reference a Python Enhancement Proposal (PEP)
384 and try to link to the relevant section if possible. For example, use
385 ``:pep:`20#easter-egg``` or ``:pep:`Easter Egg <20#easter-egg>```.
386
387 * Use :rst:role:`:mimetype:<mimetype>` to refer to a MIME Type unless the value
388 is quoted for a code example.
389
390 * Use :rst:role:`:envvar:<envvar>` to refer to an environment variable. You may
391 also need to define a reference to the documentation for that environment
392 variable using :rst:dir:`.. envvar:: <envvar>`.
393
394 * Use :rst:role:`:cve:<cve>` to reference a Common Vulnerabilities and
395 Exposures (CVE) identifier. For example, use ``:cve:`2019-14232```.
396
397 Django-specific markup
398 ======================
399
400 Besides :ref:`Sphinx's built-in markup <sphinx:rst-index>`, Django's docs
401 define some extra description units:
402
403 * Settings:
404
405 .. code-block:: rst
406
407 .. setting:: INSTALLED_APPS
408
409 To link to a setting, use ``:setting:`INSTALLED_APPS```.
410
411 * Template tags:
412
413 .. code-block:: rst
414
415 .. templatetag:: regroup
416
417 To link, use ``:ttag:`regroup```.
418
419 * Template filters:
420
421 .. code-block:: rst
422
423 .. templatefilter:: linebreaksbr
424
425 To link, use ``:tfilter:`linebreaksbr```.
426
427 * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``):
428
429 .. code-block:: rst
430
431 .. fieldlookup:: exact
432
433 To link, use ``:lookup:`exact```.
434
435 * ``django-admin`` commands:
436
437 .. code-block:: rst
438
439 .. django-admin:: migrate
440
441 To link, use ``:djadmin:`migrate```.
442
443 * ``django-admin`` command-line options:
444
445 .. code-block:: rst
446
447 .. django-admin-option:: --traceback
448
449 To link, use ``:option:`command_name --traceback``` (or omit ``command_name``
450 for the options shared by all commands like ``--verbosity``).
451
452 * Links to Trac tickets (typically reserved for patch release notes):
453
454 .. code-block:: rst
455
456 :ticket:`12345`
457
458 Django's documentation uses a custom ``console`` directive for documenting
459 command-line examples involving ``django-admin``, ``manage.py``, ``python``,
460 etc.). In the HTML documentation, it renders a two-tab UI, with one tab showing
461 a Unix-style command prompt and a second tab showing a Windows prompt.
462
463 For example, you can replace this fragment:
464
465 .. code-block:: rst
466
467 use this command:
468
469 .. code-block:: console
470
471 $ python manage.py shell
472
473 with this one:
474
475 .. code-block:: rst
476
477 use this command:
478
479 .. console::
480
481 $ python manage.py shell
482
483 Notice two things:
484
485 * You usually will replace occurrences of the ``.. code-block:: console``
486 directive.
487 * You don't need to change the actual content of the code example. You still
488 write it assuming a Unix-y environment (i.e. a ``'$'`` prompt symbol,
489 ``'/'`` as filesystem path components separator, etc.)
490
491 The example above will render a code example block with two tabs. The first
492 one will show:
493
494 .. code-block:: console
495
496 $ python manage.py shell
497
498 (No changes from what ``.. code-block:: console`` would have rendered).
499
500 The second one will show:
501
502 .. code-block:: doscon
503
504 ...\> py manage.py shell
505
506 .. _documenting-new-features:
507
508 Documenting new features
509 ========================
510
511 Our policy for new features is:
512
513 All documentation of new features should be written in a way that
514 clearly designates the features that are only available in the Django
515 development version. Assume documentation readers are using the latest
516 release, not the development version.
517
518 Our preferred way for marking new features is by prefacing the features'
519 documentation with: "``.. versionadded:: X.Y``", followed by a mandatory
520 blank line and an optional description (indented).
521
522 General improvements or other changes to the APIs that should be emphasized
523 should use the "``.. versionchanged:: X.Y``" directive (with the same format
524 as the ``versionadded`` mentioned above.
525
526 These ``versionadded`` and ``versionchanged`` blocks should be "self-contained."
527 In other words, since we only keep these annotations around for two releases,
528 it's nice to be able to remove the annotation and its contents without having
529 to reflow, reindent, or edit the surrounding text. For example, instead of
530 putting the entire description of a new or changed feature in a block, do
531 something like this:
532
533 .. code-block:: rst
534
535 .. class:: Author(first_name, last_name, middle_name=None)
536
537 A person who writes books.
538
539 ``first_name`` is ...
540
541 ...
542
543 ``middle_name`` is ...
544
545 .. versionchanged:: A.B
546
547 The ``middle_name`` argument was added.
548
549 Put the changed annotation notes at the bottom of a section, not the top.
550
551 Also, avoid referring to a specific version of Django outside a
552 ``versionadded`` or ``versionchanged`` block. Even inside a block, it's often
553 redundant to do so as these annotations render as "New in Django A.B:" and
554 "Changed in Django A.B", respectively.
555
556 If a function, attribute, etc. is added, it's also okay to use a
557 ``versionadded`` annotation like this:
558
559 .. code-block:: rst
560
561 .. attribute:: Author.middle_name
562
563 .. versionadded:: A.B
564
565 An author's middle name.
566
567 We can remove the ``.. versionadded:: A.B`` annotation without any indentation
568 changes when the time comes.
569
570 Minimizing images
571 =================
572
573 Optimize image compression where possible. For PNG files, use OptiPNG and
574 AdvanceCOMP's ``advpng``:
575
576 .. console::
577
578 $ cd docs
579 $ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
580 $ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`
581
582 This is based on OptiPNG version 0.7.5. Older versions may complain about the
583 ``-strip all`` option being lossy.
584
585 An example
586 ==========
587
588 For a quick example of how it all fits together, consider this hypothetical
589 example:
590
591 * First, the ``ref/settings.txt`` document could have an overall layout
592 like this:
593
594 .. code-block:: rst
595
596 ========
597 Settings
598 ========
599
600 ...
601
602 .. _available-settings:
603
604 Available settings
605 ==================
606
607 ...
608
609 .. _deprecated-settings:
610
611 Deprecated settings
612 ===================
613
614 ...
615
616 * Next, the ``topics/settings.txt`` document could contain something like
617 this:
618
619 .. code-block:: rst
620
621 You can access a :ref:`listing of all available settings
622 <available-settings>`. For a list of deprecated settings see
623 :ref:`deprecated-settings`.
624
625 You can find both in the :doc:`settings reference document
626 </ref/settings>`.
627
628 We use the Sphinx :rst:role:`doc` cross-reference element when we want to
629 link to another document as a whole and the :rst:role:`ref` element when
630 we want to link to an arbitrary location in a document.
631
632 * Next, notice how the settings are annotated:
633
634 .. code-block:: rst
635
636 .. setting:: ADMINS
637
638 ADMINS
639 ======
640
641 Default: ``[]`` (Empty list)
642
643 A list of all the people who get code error notifications. When
644 ``DEBUG=False`` and a view raises an exception, Django will email these people
645 with the full exception information. Each member of the list should be a tuple
646 of (Full name, email address). Example::
647
648 [("John", "[email protected]"), ("Mary", "[email protected]")]
649
650 Note that Django will email *all* of these people whenever an error happens.
651 See :doc:`/howto/error-reporting` for more information.
652
653 This marks up the following header as the "canonical" target for the
654 setting ``ADMINS``. This means any time I talk about ``ADMINS``,
655 I can reference it using ``:setting:`ADMINS```.
656
657 That's basically how everything fits together.
658
659 Translating documentation
660 =========================
661
662 See :ref:`Localizing the Django documentation <translating-documentation>` if
663 you'd like to help translate the documentation into another language.
664
665 .. _django-admin-manpage:
666
667 ``django-admin`` man page
668 =========================
669
670 Sphinx can generate a manual page for the
671 :doc:`django-admin </ref/django-admin>` command. This is configured in
672 ``docs/conf.py``. Unlike other documentation output, this man page should be
673 included in the Django repository and the releases as
674 ``docs/man/django-admin.1``. There isn't a need to update this file when
675 updating the documentation, as it's updated once as part of the release process.
676
677 To generate an updated version of the man page, in the ``docs`` directory, run:
678
679 .. console::
680
681 $ make man
682
683 The new man page will be written in ``docs/_build/man/django-admin.1``.