| 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``. |