We place high importance on the consistency and readability of documentation.\nAfter all, Django was created in a journalism environment! So we treat our\ndocumentation like we treat our code: we aim to improve it as often as\npossible.
\nDocumentation changes generally come in two forms:
\nGeneral improvements: typo corrections, error fixes and better\nexplanations through clearer writing and more examples.
New features: documentation of features that have been added to the\nframework since the last release.
This section explains how writers can craft their documentation changes\nin the most useful and least error-prone ways.
\nThough Django’s documentation is intended to be read as HTML at\nhttps://docs.djangoproject.com/, we edit it as a collection of plain text files\nwritten in the reStructuredText markup language for maximum flexibility.
\nWe work from the development version of the repository because it has the\nlatest-and-greatest documentation, just as it has the latest-and-greatest code.
\nWe also backport documentation fixes and improvements, at the discretion of the\nmerger, to the last release branch. This is because it’s advantageous to\nhave the docs for the last release be up-to-date and correct (see\nDiferencias entre versiones).
\nDjango’s documentation uses the Sphinx documentation system, which in turn\nis based on docutils. The basic idea is that lightly-formatted plain-text\ndocumentation is transformed into HTML, PDF, and any other output format.
\nSphinx includes a sphinx-build command for turning reStructuredText into\nother formats, e.g., HTML and PDF. This command is configurable, but the Django\ndocumentation includes a Makefile that provides a shorter make html\ncommand.
The documentation is organized into several categories:
\nTutorials take the reader by the hand through a series\nof steps to create something.
\nThe important thing in a tutorial is to help the reader achieve something\nuseful, preferably as early as possible, in order to give them confidence.
\nExplain the nature of the problem we’re solving, so that the reader\nunderstands what we’re trying to achieve. Don’t feel that you need to begin\nwith explanations of how things work - what matters is what the reader does,\nnot what you explain. It can be helpful to refer back to what you’ve done and\nexplain afterward.
\nTopic guides trata de explicar un concepto o tema a bastante alto nivel.
\nLink to reference material rather than repeat it. Use examples and don’t be\nreluctant to explain things that seem very basic to you - it might be the\nexplanation someone else needs.
\nProviding background context helps a newcomer connect the topic to things\nthat they already know.
\nReference guides contain technical references for APIs.\nThey describe the functioning of Django’s internal machinery and instruct in\nits use.
\nKeep reference material tightly focused on the subject. Assume that the\nreader already understands the basic concepts involved but needs to know or\nbe reminded of how Django does it.
\nReference guides aren’t the place for general explanation. If you find\nyourself explaining basic concepts, you may want to move that material to a\ntopic guide.
\nHow-to guides are recipes that take the reader through\nsteps in key subjects.
\nWhat matters most in a how-to guide is what a user wants to achieve.\nA how-to should always be result-oriented rather than focused on internal\ndetails of how Django implements whatever is being discussed.
\nThese guides are more advanced than tutorials and assume some knowledge about\nhow Django works. Assume that the reader has followed the tutorials and don’t\nhesitate to refer the reader back to the appropriate tutorial rather than\nrepeat the same material.
\nIf you’d like to start contributing to our docs, get the development version of\nDjango from the source code repository (see\nInstalling the development version):
\nLinux / macOS
$ git clone https://github.com/django/django.git\nWindows
...\\> git clone https://github.com/django/django.git\nIf you’re planning to submit these changes, you might find it useful to make a\nfork of the Django repository and clone this fork instead.
\nCreate and activate a virtual environment, then install the dependencies:
\n$ python -m venv .venv\n$ source .venv/bin/activate\n$ python -m pip install -r docs/requirements.txt\nWe can build HTML output from the docs directory:
Linux / macOS
$ cd docs\n$ make html\nWindows
...\\> cd docs\n...\\> make.bat html\nYour locally-built documentation will be accessible at\n_build/html/index.html and it can be viewed in any web browser, though it\nwill be themed differently than the documentation at\ndocs.djangoproject.com. This is OK! If\nyour changes look good on your local machine, they’ll look good on the website.
sphinx-autobuild can be used to automatically rebuild the documentation\nand reload the documentation page in the browser whenever a file changes. To\nenable auto-reloading:
\nInstall the package:
\nLinux / macOS
$ python -m pip install sphinx-autobuild\nWindows
...\\> py -m pip install sphinx-autobuild\nFrom the docs directory, run one of the following commands:
On Linux and macOS:
\n$ SPHINXBUILD=sphinx-autobuild SPHINXOPTS="--open-browser --delay 0" make html\nOn Windows (Command Prompt):
\n...\\> set SPHINXBUILD=sphinx-autobuild\n...\\> set SPHINXOPTS=--open-browser --delay 0\n...\\> make html\nOn Windows (PowerShell):
\nPS> $env:SPHINXBUILD="sphinx-autobuild"\nPS> $env:SPHINXOPTS="--open-browser --delay 0"\nPS> make html\nAlternatively, sphinx-autobuild can be invoked directly:
Linux / macOS
$ sphinx-autobuild . _build/html --open-browser --delay 0\nWindows
...\\> sphinx-autobuild . _build\\html --open-browser --delay 0\nThe auto-reloader can be stopped with Ctrl+C.
The source files are .txt files located in the docs/ directory.
These files are written in the reStructuredText markup language. To learn the\nmarkup, see the reStructuredText reference.
\nTo edit this page, for example, we would edit the file\ndocs/internals/contributing/writing-documentation.txt and rebuild the\nHTML with make html.
Several checks help maintain Django’s documentation quality, including\nspelling,\ncode block formatting, and\ndocumentation style.
\nThese checks are run automatically in CI and must pass before documentation\nchanges can be merged. They can also be run locally with a single command:
\nLinux / macOS
$ make check\nWindows
...\\> make.bat check\nThis command runs all current checks and will include any new checks added in\nthe future.
\nBefore you commit your docs, it’s a good idea to run the spelling checker.\nYou’ll need to install sphinxcontrib-spelling first. The spell checker\nalso requires a system-level spell checking backend such as Aspell. Then from the docs directory, run:
Linux / macOS
$ make spelling\nWindows
...\\> make.bat spelling\nWrong words (if any) along with the file and line number where they occur will\nbe saved to _build/spelling/output.txt.
If you encounter false-positives (error output that actually is correct), do\none of the following:
\nSurround inline code or brand/technology names with double grave accents\n(``)
Find synonyms that the spell checker recognizes.
If, and only if, you are sure the word you are using is correct - add it\nto docs/spelling_wordlist (please keep the list in alphabetical order).
All Python code blocks should be formatted using the blacken-docs\nauto-formatter. This is automatically run by the pre-commit hook if configured.
\nThe check can also be run manually: provided that blacken-docs is\ninstalled, run the following command from the docs directory:
Linux / macOS
$ make black\nWindows
...\\> make.bat black\nThe formatter will report any issues by printing them to the terminal and will\nreformat code blocks where possible.
\nDjango’s documentation is checked for reStructuredText style and formal issues\nusing sphinx-lint. This helps catch problems like stray tabs, trailing\nwhitespace, excessive line length, and similar formatting problems.
\nOnce sphinx-lint is installed, the check can be run with the following\ncommand from the docs directory:
Linux / macOS
$ make lint\nWindows
...\\> make.bat lint\nThe command prints any violations to the terminal in the form\npath:line: message. If problems are encountered:
Read the message and fix the indicated issue (for example, remove trailing\nwhitespace, adjust backticks, or replace tabs with spaces).
For long lines consider wrapping text onto new lines or breaking long inline\nlinks into named references. The custom line length check should already skip\ncommon false positives such as headings, tables and long links.
Links in documentation can become broken or changed such that they are no\nlonger the canonical link. Sphinx provides a builder that can check whether the\nlinks in the documentation are working. From the docs directory, run:
Linux / macOS
$ make linkcheck\nWindows
...\\> make.bat linkcheck\nOutput is printed to the terminal, but can also be found in\n_build/linkcheck/output.txt and _build/linkcheck/output.json.
Entries that have a status of «working» are fine, those that are «unchecked» or\n«ignored» have been skipped because they either cannot be checked or have\nmatched ignore rules in the configuration.
\nEntries that have a status of «broken» need to be fixed. Those that have a\nstatus of «redirected» may need to be updated to point to the canonical\nlocation, e.g. the scheme has changed http:// → https://. In certain\ncases, we do not want to update a «redirected» link, e.g. a rewrite to always\npoint to the latest or stable version of the documentation, e.g.\n/en/stable/ → /en/3.2/.
When using pronouns in reference to a hypothetical person, such as «a user with\na session cookie», gender-neutral pronouns (they/their/them) should be used.\nInstead of:
\nhe or she… use they.
him or her… use them.
his or her… use their.
his or hers… use theirs.
himself or herself… use themselves.
Try to avoid using words that minimize the difficulty involved in a task or\noperation, such as «easily», «simply», «just», «merely», «straightforward», and\nso on. People’s experience may not match your expectations, and they may become\nfrustrated when they do not find a step as «straightforward» or «simple» as it\nis implied to be.
\nHere are some style guidelines on commonly used terms throughout the\ndocumentation:
\nDjango – when referring to the framework, capitalize Django. It is\nlowercase only in Python code and in the djangoproject.com logo.
email – no hyphen.
HTTP – the expected pronunciation is «Aitch Tee Tee Pee» and therefore\nshould be preceded by «an» and not «a».
MySQL, PostgreSQL, SQLite
SQL – when referring to SQL, the expected pronunciation should be\n«Ess Queue Ell» and not «sequel». Thus in a phrase like «Returns an\nSQL expression», «SQL» should be preceded by «an» and not «a».
Python – when referring to the language, capitalize Python.
realize, customize, initialize, etc. – use the American\n«ize» suffix, not «ise.»
subclass – it’s a single word without a hyphen, both as a verb\n(«subclass that model») and as a noun («create a subclass»).
the web, web framework – it’s not capitalized.
website – use one word, without capitalization.
model – it’s not capitalized.
template – it’s not capitalized.
URLconf – use three capitalized letters, with no space before\n«conf.»
view – it’s not capitalized.
These guidelines regulate the format of our reST (reStructuredText)\ndocumentation:
\nIn section titles, capitalize only initial words and proper nouns.
Wrap the documentation at 80 characters wide, unless a code example\nis significantly less readable when split over two lines, or for another\ngood reason.
The main thing to keep in mind as you write and edit docs is that the\nmore semantic markup you can add the better. So:
\nAdd ``django.contrib.auth`` to your ``INSTALLED_APPS``...\nIsn’t nearly as helpful as:
\nAdd :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...\nThis is because Sphinx will generate proper links for the latter, which\ngreatly helps readers.
\nYou can prefix the target with a ~ (that’s a tilde) to get only the\n«last bit» of that path. So :mod:`~django.contrib.auth` will\ndisplay a link with the title «auth».
Use intersphinx to reference Python’s and Sphinx”\ndocumentation.
Add .. code-block:: <lang> to literal blocks so that they get\nhighlighted. Prefer relying on automatic highlighting using ::\n(two colons). This has the benefit that if the code contains some invalid\nsyntax, it won’t be highlighted. Adding .. code-block:: python, for\nexample, will force highlighting despite invalid syntax.
To improve readability, use .. admonition:: Descriptive title rather than\n.. note::. Use these boxes sparingly.
Use these heading styles:
\n===\nOne\n===\n\nTwo\n===\n\nThree\n-----\n\nFour\n~~~~\n\nFive\n^^^^\nUse :rfc: to reference a Request for Comments (RFC) and\ntry to link to the relevant section if possible. For example, use\n:rfc:`2324#section-2.3.2` or\n:rfc:`Custom link text <2324#section-2.3.2>`.
Use :pep: to reference a Python Enhancement Proposal (PEP)\nand try to link to the relevant section if possible. For example, use\n:pep:`20#easter-egg` or :pep:`Easter Egg <20#easter-egg>`.
Use :mimetype: to refer to a MIME Type unless the value\nis quoted for a code example.
Use :envvar: to refer to an environment variable. You may\nalso need to define a reference to the documentation for that environment\nvariable using .. envvar::.
Use :cve: to reference a Common Vulnerabilities and\nExposures (CVE) identifier. For example, use :cve:`2019-14232`.
When documenting Python objects (classes, methods, attributes, etc.) using\nSphinx directives such as .. class::, .. method::, and\n.. attribute::, all content must be properly indented to ensure correct\nrendering and to support features like automatic table of contents\ngeneration.
Follow these rules:
\nThe directive itself remains flush with the left margin (no indentation).
All descriptive text under the directive must be indented by 4 spaces.
Multi-line descriptions must keep the same indentation level.
Nested directives (for example, methods inside a class) require an\nadditional 4 spaces of indentation to maintain hierarchy.
Field lists (such as :param:, :returns:, etc.) must align with the\ndirective’s content level.
Example:
\n.. class:: MyClass\n\n A brief description of the class.\n\n .. method:: my_method(arg1, arg2)\n\n Method description.\n\n :param arg1: Description of the first parameter\n :param arg2: Description of the second parameter\n\n .. attribute:: my_attribute\n\n Attribute description.\nBesides Sphinx’s built-in markup, Django’s docs\ndefine some extra description units:
\nSettings:
\n.. setting:: INSTALLED_APPS\nTo link to a setting, use :setting:`INSTALLED_APPS`.
Template tags:
\n.. templatetag:: regroup\nTo link, use :ttag:`regroup`.
Template filters:
\n.. templatefilter:: linebreaksbr\nTo link, use :tfilter:`linebreaksbr`.
Field lookups (i.e. Foo.objects.filter(bar__exact=whatever)):
.. fieldlookup:: exact\nTo link, use :lookup:`exact`.
django-admin commands:
.. django-admin:: migrate\nTo link, use :djadmin:`migrate`.
django-admin command-line options:
.. django-admin-option:: --traceback\nTo link, use :option:`command_name --traceback` (or omit command_name\nfor the options shared by all commands like --verbosity).
Links to Trac tickets (typically reserved for patch release notes):
\n:ticket:`12345`\nDjango’s documentation uses a custom console directive for documenting\ncommand-line examples involving django-admin, manage.py, python,\netc. In the HTML documentation, it renders a two-tab UI, with one tab showing\na Unix-style command prompt and a second tab showing a Windows prompt.
For example, you can replace this fragment:
\nuse this command:\n\n.. code-block:: console\n\n $ python manage.py shell\nwith this one:
\nuse this command:\n\n.. console::\n\n $ python manage.py shell\nNotice two things:
\nYou usually will replace occurrences of the .. code-block:: console\ndirective.
You don’t need to change the actual content of the code example. You still\nwrite it assuming a Unix-y environment (i.e. a '$' prompt symbol,\n'/' as filesystem path components separator, etc.)
The example above will render a code example block with two tabs. The first\none will show:
\n$ python manage.py shell\n(No changes from what .. code-block:: console would have rendered).
The second one will show:
\n...\\> py manage.py shell\nOur policy for new features is:
\n\n\nAll documentation of new features should be written in a way that\nclearly designates the features that are only available in the Django\ndevelopment version. Assume documentation readers are using the latest\nrelease, not the development version.
\n
Our preferred way for marking new features is by prefacing the features”\ndocumentation with: «.. versionadded:: X.Y», followed by a mandatory\nblank line and an optional description (indented).
General improvements or other changes to the APIs that should be emphasized\nshould use the «.. versionchanged:: X.Y» directive (with the same format\nas the versionadded mentioned above).
These versionadded and versionchanged blocks should be\n«self-contained.» In other words, since we only keep these annotations around\nfor two releases, it’s nice to be able to remove the annotation and its\ncontents without having to reflow, reindent, or edit the surrounding text. For\nexample, instead of putting the entire description of a new or changed feature\nin a block, do something like this:
.. class:: Author(first_name, last_name, middle_name=None)\n\n A person who writes books.\n\n ``first_name`` is ...\n\n ...\n\n ``middle_name`` is ...\n\n .. versionchanged:: A.B\n\n The ``middle_name`` argument was added.\nPut the changed annotation notes at the bottom of a section, not the top.
\nAlso, avoid referring to a specific version of Django outside a\nversionadded or versionchanged block. Even inside a block, it’s often\nredundant to do so as these annotations render as «New in Django A.B:» and\n«Changed in Django A.B», respectively.
If a function, attribute, etc. is added, it’s also okay to use a\nversionadded annotation like this:
.. attribute:: Author.middle_name\n\n .. versionadded:: A.B\n\n An author's middle name.\nWe can remove the .. versionadded:: A.B annotation without any indentation\nchanges when the time comes.
Optimize image compression where possible. For PNG files, use OptiPNG and\nAdvanceCOMP’s advpng:
Linux / macOS
$ cd docs\n$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`\n$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`\nWindows
...\\> cd docs\n...\\> optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path ".\\_build\\*" -name "*.png"`\n...\\> advpng -z4 `find . -type f -not -path ".\\_build\\*" -name "*.png"`\nThis is based on OptiPNG version 0.7.5. Older versions may complain about the\n-strip all option being lossy.
For a quick example of how it all fits together, consider this hypothetical\nexample:
\nFirst, the ref/settings.txt document could have an overall layout\nlike this:
========\nSettings\n========\n\n...\n\n.. _available-settings:\n\nAvailable settings\n==================\n\n...\n\n.. _deprecated-settings:\n\nDeprecated settings\n===================\n\n...\nNext, the topics/settings.txt document could contain something like\nthis:
You can access a :ref:`listing of all available settings\n<available-settings>`. For a list of deprecated settings see\n:ref:`deprecated-settings`.\n\nYou can find both in the :doc:`settings reference document\n</ref/settings>`.\nWe use the Sphinx doc cross-reference element when we want to\nlink to another document as a whole and the ref element when\nwe want to link to an arbitrary location in a document.
Next, notice how the settings are annotated:
\n.. setting:: ADMINS\n\nADMINS\n======\n\nDefault: ``[]`` (Empty list)\n\nA list of all the people who get code error notifications...\nThis marks up the following header as the «canonical» target for the\nsetting ADMINS. This means any time I talk about ADMINS,\nI can reference it using :setting:`ADMINS`.
That’s basically how everything fits together.
\nSee Localizing the Django documentation if\nyou’d like to help translate the documentation into another language.
\ndjango-admin man pageLink to this heading#Sphinx can generate a manual page for the django-admin command. This is configured in docs/conf.py. Unlike\nother documentation output, this man page should be included in the Django\nrepository and the releases as docs/man/django-admin.1. There isn’t a need\nto update this file when updating the documentation, as it’s updated once as\npart of the release process.
To generate an updated version of the man page, in the docs directory, run:
Linux / macOS
$ make man\nWindows
...\\> make.bat man\nThe new man page will be written in docs/_build/man/django-admin.1.