---
title: "Écrire la documentation"
version: 6.1
locale: fr
source: https://docs.djangoproject.com/fr/6.1/internals/contributing/writing-documentation/
canonical: https://djangodocs.dev/fr/6.1/internals/contributing/writing-documentation/
---
# Écrire la documentation

Nous attribuons une grande importance à la cohérence et à la lisibilité de la documentation. Après tout, Django a été créé dans un environnement journalistique ! Nous traitons donc la documentation sur un pied d’égalité avec le code : nous visons à l’améliorer aussi souvent que possible.

Les modifications de documentation se présentent généralement sous deux formes :

- Des améliorations générales : corrections d’orthographe, résolutions d’erreurs et meilleures explications par une écriture plus claire et davantage d’exemples.
- Nouvelles fonctionnalités : documentation de fonctionnalités ajoutées au cadre logiciel depuis la version précédente.

Cette section explique comment les rédacteurs peuvent préparer les modifications de documentation de la manière la plus utile possible et qui évite au maximum les erreurs.

## Le processus de documentation de Django

Bien que la documentation de Django soit destinée à être lue au format HTML sur <https://docs.djangoproject.com/>, nous l’éditons dans un ensemble de fichiers textes écrits dans le langage de balisage reStructuredText pour une souplesse maximale.

Nous travaillons à partir de la version de développement du dépôt car celle-ci contient la documentation la plus à jour, comme c’est le cas pour le code.

Les corrections et améliorations de documentation sont aussi reportées dans la dernière branche publiée, en fonction de leur pertinence jugée par le fusionneur. Nous pensons qu’il est avantageux d’avoir la meilleure documentation possible en tout temps pour la dernière version publiée (voir [Différences entre versions](/fr/6.1/intro/whatsnext/#differences-between-doc-versions)).

La documentation de Django utilise le système de documentation [Sphinx](https://www.sphinx-doc.org/), qui se base lui-même sur [docutils](https://docutils.sourceforge.io/). L’idée de base est de transformer de la documentation en texte brut avec une mise en forme minimale en HTML, PDF ou tout autre format de sortie.

Sphinx contient une commande `sphinx-build` pour transformer le texte reStructuredText en d’autres formats, tels que HTML ou PDF. Cette commande est configurable, mais la documentation de Django contient un fichier `Makefile` qui permet d’utiliser une commande plus courte : `make html`.

## Organisation de la documentation

La documentation est scindée en plusieurs catégories :

- Les [tutoriels](/fr/6.1/intro/) prennent l’utilisateur par la main à travers une série d’étapes pour créer quelque chose.

  L’aspect important d’un tutoriel est d’aider le lecteur à accomplir quelque chose d’utile, de préférence aussi vite que possible, dans le but de lui donner confiance.

  Expliquez la nature du problème à résoudre afin que le lecteur comprenne ce que l’on est en train de faire. Ne pensez pas qu’il faille commencer par des explications sur le fonctionnement des choses ; ce qui compte est ce que le lecteur fait, et non pas ce que vous expliquez. Il peut être utile de faire référence à ce que l’on a fait dans des explications a posteriori.
- Les [guides thématiques](/fr/6.1/topics/) visent à expliquer un concept ou un sujet d’un point de vue assez général.

  Faites des liens vers le matériel de référence plutôt que de le répéter. Utilisez des exemples et n’hésitez pas à expliquer des choses qui vous semblent évidentes, il pourrait s’agir de l’explication dont quelqu’un a vraiment besoin.

  La mise à disposition de contexte sous-jacent aide les débutants à faire des liens entre le sujet et des éléments qu’ils connaissent déjà.
- Les [guides de référence](/fr/6.1/ref/) contiennent des références techniques pour les API. Ils présentent le fonctionnement de la machinerie interne de Django avec des instructions d’utilisation.

  Restez bien centré sur le sujet du matériel de référence. Vous pouvez compter sur la connaissance des concepts de base par le lecteur, mais celui-ci cherche à savoir ou à se rappeler comment Django les applique.

  Les guides de référence ne sont pas l’endroit pour des explications générales. Si vous êtes en train d’expliquer des concepts de base, il pourrait être nécessaire de déplacer ce contenu vers un guide thématique.
- Les [guides pratiques](/fr/6.1/howto/) sont des marches à suivre qui accompagnent le lecteur dans une suite d’étapes dans des sujets clés.

  Ce qui compte le plus dans un guide pratique est le résultat attendu par son lecteur. Un guide pratique doit toujours être orienté sur le résultat plutôt que sur des détails internes sur la manière dont Django implémente ce qui est en cours d’étude.

  Ces guides vont plus loin que les tutoriels et comptent sur un certaine connaissance du fonctionnement de Django. On part du principe que le lecteur a suivi les tutoriels. N’hésitez pas à réorienter le lecteur sur un tutoriel adéquat plutôt que de répéter un contenu existant.

## Comment débuter une contribution à la documentation

### Création d’une copie locale du dépôt Django

Si vous souhaitez commencer à contribuer à notre documentation, obtenez la version de développement de Django à partir de son dépôt de code source (voir [Installation de la version de développement](/fr/6.1/topics/install/#installing-development-version)) :

```console
$ git clone https://github.com/django/django.git
```

*Windows*

```doscon
...\> git clone https://github.com/django/django.git
```

Si vous pensez soumettre ces modifications, il est alors utile de créer une fourche du dépôt Django et de plutôt créer une copie locale de cette fourche.

### Configurer un environnement virtuel et installer les dépendances

Créez et activez un environnement virtuel, puis installez les dépendances :

```shell
$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install -r docs/requirements.txt
```

### Construction locale de la documentation

Il est possible de construire une version HTML à partir du répertoire `docs`:

```console
$ cd docs
$ make html
```

*Windows*

```doscon
...\> cd docs
...\> make.bat html
```

La documentation construite localement sera accessible à partir de `_build/html/index.html` et visible dans n’importe quel navigateur, même si le thème graphique sera différent de celui de la documentation sur [docs.djangoproject.com](https://docs.djangoproject.com/). Cela ne pose pas de problème. Si vos modifications apparaissent correctement sur votre machine locale, elles seront aussi correctes sur le site web.

#### Automating documentation rebuilds

[sphinx-autobuild](https://pypi.org/project/sphinx-autobuild/) can be used to automatically rebuild the documentation
and reload the documentation page in the browser whenever a file changes. To
enable auto-reloading:

1. Install the package:

   ```console
   $ python -m pip install sphinx-autobuild
   ```

   *Windows*

   ```doscon
   ...\> py -m pip install sphinx-autobuild
   ```
2. From the `docs` directory, run one of the following commands:

   - On Linux and macOS:

     ```shell
     $ SPHINXBUILD=sphinx-autobuild SPHINXOPTS="--open-browser --delay 0" make html
     ```
   - On Windows (Command Prompt):

     ```doscon
     ...\> set SPHINXBUILD=sphinx-autobuild
     ...\> set SPHINXOPTS=--open-browser --delay 0
     ...\> make html
     ```
   - On Windows (PowerShell):

     ```powershell
     PS> $env:SPHINXBUILD="sphinx-autobuild"
     PS> $env:SPHINXOPTS="--open-browser --delay 0"
     PS> make html
     ```

   Alternatively, `sphinx-autobuild` can be invoked directly:

   ```console
   $ sphinx-autobuild . _build/html --open-browser --delay 0
   ```

   *Windows*

   ```doscon
   ...\> sphinx-autobuild . _build\html --open-browser --delay 0
   ```

The auto-reloader can be stopped with `Ctrl+C`.

### Édition de la documentation

Les fichiers sources sont des fichiers `.txt` situés dans le répertoire `docs/`.

Ces fichiers sont écrits en langage de balisage reStructuredText. Pour apprendre ce balisage, consultez la ref:référence reStructuredText \<sphinx:rst-index\>.

Pour modifier cette page, par exemple, il s’agit d’éditer le fichier  [docs/internals/contributing/writing-documentation.txt](https://github.com/django/django/blob/stable/6.1.x/docs/internals/contributing/writing-documentation.txt) et de reconstruire la sortie HTML avec `make html`.

### Documentation quality checks

Several checks help maintain Django’s documentation quality, including
[spelling](#documentation-spelling-check),
[code block formatting](#documentation-code-block-format-check), and
[documentation style](#documentation-lint-check).

These checks are run automatically in CI and must pass before documentation
changes can be merged. They can also be run locally with a single command:

```console
$ make check
```

*Windows*

```doscon
...\> make.bat check
```

This command runs all current checks and will include any new checks added in
the future.

#### Correction orthographique

Before you commit your docs, it’s a good idea to run the spelling checker.
You’ll need to install [sphinxcontrib-spelling](https://pypi.org/project/sphinxcontrib-spelling/) first. The spell checker
also requires a system-level spell checking backend such as [Aspell](http://aspell.net/). Then from the `docs` directory, run:

```console
$ make spelling
```

*Windows*

```doscon
...\> make.bat spelling
```

Wrong words (if any) along with the file and line number where they occur will
be saved to `_build/spelling/output.txt`.

Si vous rencontrez des faux positifs (des erreurs signalées qui n’en sont pas), faites l’une des choses suivantes :

- Surround inline code or brand/technology names with double grave accents
  (\`\`)
- Cherchez des synonymes que le correcteur orthographique connaît.
- Si vous êtes certain-e que le mot utilisé est correct, ajoutez-le à la liste `docs/spelling_wordlist` (en prenant soin de respecter l’ordre alphabétique).

#### Code block format check

All Python code blocks should be formatted using the [blacken-docs](https://pypi.org/project/blacken-docs/)
auto-formatter. This is automatically run by the [pre-commit hook](/fr/6.1/internals/contributing/writing-code/coding-style/#coding-style-pre-commit) if configured.

The check can also be run manually: provided that `blacken-docs` is
installed, run the following command from the `docs` directory:

```console
$ make black
```

*Windows*

```doscon
...\> make.bat black
```

The formatter will report any issues by printing them to the terminal and will
reformat code blocks where possible.

#### Documentation lint check

Django’s documentation is checked for reStructuredText style and formal issues
using [sphinx-lint](https://pypi.org/project/sphinx-lint/). This helps catch problems like stray tabs, trailing
whitespace, excessive line length, and similar formatting problems.

Once `sphinx-lint` is installed, the check can be run with the following
command from the `docs` directory:

```console
$ make lint
```

*Windows*

```doscon
...\> make.bat lint
```

The command prints any violations to the terminal in the form
`path:line: message`. If problems are encountered:

- Read the message and fix the indicated issue (for example, remove trailing
  whitespace, adjust backticks, or replace tabs with spaces).
- For long lines consider wrapping text onto new lines or breaking long inline
  links into named references. The custom line length check should already skip
  common false positives such as headings, tables and long links.

### Contrôle des liens

Links in documentation can become broken or changed such that they are no
longer the canonical link. Sphinx provides a builder that can check whether the
links in the documentation are working. From the `docs` directory, run:

```console
$ make linkcheck
```

*Windows*

```doscon
...\> make.bat linkcheck
```

Output is printed to the terminal, but can also be found in
`_build/linkcheck/output.txt` and `_build/linkcheck/output.json`.

> **Warning**
>
> The execution of the command requires an internet connection and takes
> several minutes to complete, because the command tests all the links
> that are found in the documentation.

Les lignes qui ont un statut de  « working » sont bonnes, celles qui sont marquées comme « unchecked » ou « ignored » n’ont pas été contrôlées soit car il n’est pas possible de le faire, soit parce qu’elles correspondent à des règles à ignorer dans la configuration.

Les lignes qui sont dans l’état « broken » doivent être corrigées. Celles qui sont dans l’état « redirected » ont peut-être besoin d’être mises à jour pour pointer vers leur emplacement canonique, par exemple quand le protocole a passé de `http://` → `https://`. Dans certains cas, un lien redirigé n’a pas besoin d’être mis à jour, par exemple un alias qui pointe toujours vers la dernière version ou la version stable d’une documentation, comme `/en/stable/` → `/en/3.2/`.

## Style d’écriture (anglais)

Lors d’utilisation de pronoms en référence à une personne hypothétique, comme dans « a user with a session cookie », il est préférable d’utiliser des pronoms neutres. Au lieu de :

- he ou she… utilisez they.
- him ou her… utilisez them.
- his ou her… utilisez their.
- his ou hers… utilisez theirs.
- himself ou herself… utilisez themselves.

Essayez d’éviter des mots qui minimisent la difficulté impliquée par une tâche ou une opération, tels que « easily », « simply », « just », « merely », « straightforward », etc. L’expérience des gens ne correspond pas forcément à votre attente, et ceux-ci pourraient ressentir de la frustration lorsqu’ils ne trouvent pas qu’une étape est si simple ou évidente que le texte ne le laissait penser.

## Termes fréquemment utilisés

Voici quelques lignes directrices de style pour des termes fréquemment utilisés dans la documentation :

- **Django** – lorsque vous vous référez au cadriciel, toujours avec un D majuscule. Il n’est en minuscules que dans le code Python et dans le logo djangoproject.com.
- **email** – sans trait d’union.
- **HTTP** – la prononciation anglaise habituelle est « Éitch Ti Ti Pi », le terme doit donc être précédé de « an », et pas « a ».
- **MySQL**, **PostgreSQL**, **SQLite**
- **SQL** – lorsqu’on se réfère à SQL, la prononciation attendue est « èsquiouèl » et non pas « sicouèl ». Ainsi, dans une phrase comme « Returns an SQL expression », « SQL » doit être précédé d’un « an » et non pas de « a ».
- **Python** – mettre une majuscule quand c’est une référence au langage.
- **realize**, **customize**, **initialize**, etc. – utiliser le suffixe américain « ize » et non « ise ».
- **subclass** – en un mot sans trait d’union, que ce soit pour un verbe (« subclass that model ») ou un nom (« create a subclass »).
- **the web**, **web framework** – sans majuscule.
- **website** – en un seul mot, sans majuscule.

## Terminologie spécifique à Django

- **model** – sans majuscule.
- **template** – sans majuscule.
- **URLconf** – trois premières lettres en majuscules, sans espace avant « conf ».
- **view** – sans majuscule.

## Directives pour les fichiers reStructuredText

Ces lignes directrices régulent le format de notre documentation reST (reStructuredText) :

- Dans les titres de section, ne mettez en majuscules que les mots initiaux et les noms propres.
- Limitez les lignes de la documentation à 80 caractères, sauf si un exemple de code est manifestement moins lisible lorsqu’il est réparti sur deux lignes, ou pour une autre bonne raison.
- La chose principale à garder en tête lors de l’écriture et de l’édition de la documentation est que plus il y a de balisage sémantique, mieux c’est. Donc :

  ```rst
  Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...
  ```

  N’est pas aussi utile que :

  ```rst
  Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...
  ```

  La raison en est que Sphinx va générer des liens adéquats avec ce deuxième exemple, ce qui aide grandement les lecteurs.

  Il est possible de préfixer la cible par un `~` (caractère tilde) pour que seul le dernier composant du chemin soit affiché. Par exemple,  `` :mod:`~django.contrib.auth` `` affichera un lien sur le mot « auth » seul.
- Utilisez [`intersphinx`](https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#module-sphinx.ext.intersphinx) pour ajouter des références aux documentations de Python et de Sphinx.
- Ajoutez `.. code-block:: <lang>` aux blocs littéraux pour que leur syntaxe soit mise en évidence. Mais on préfère en général laisser agir la coloration syntaxique automatique en utilisant `::` (deux fois deux-points). L’avantage est que du code contenant de la syntaxe non valable ne sera pas coloré. Si par exemple on ajoute `.. code-block:: python`, la coloration syntaxique sera forcée même si la syntaxe n’est pas entièrement valable.
- Pour améliorer la lisibilité, utilisez `.. admonition:: Titre descriptif` plutôt que `.. note::`. Utilisez ces boîtes de manière parcimonieuse.
- Utilisez ces styles d’en-têtes :

  ```rst
  ===
  One
  ===

  Two
  ===

  Three
  -----

  Four
  ~~~~

  Five
  ^^^^
  ```
- Use [`:rfc:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-rfc) to reference a Request for Comments (RFC) and
  try to link to the relevant section if possible. For example, use
  `` :rfc:`2324#section-2.3.2` `` or
  `` :rfc:`Custom link text <2324#section-2.3.2>` ``.
- Utilisez [`:pep:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-pep) pour faire référence aux propositions d’amélioration de Python (PEP) et essayez de faire le lien vers la section adéquate si possible. Par exemple, écrivez `` :pep:`20#easter-egg` `` ou `` :pep:`Easter Egg <20#easter-egg>` ``.
- Utilisez [`:mimetype:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-mimetype) pour vous référer à un type MIME sauf si la valeur est entre guillemets pour un exemple de code.
- Utilisez [`:envvar:`](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-envvar) pour vous référer à une variable d’environnement. Il est parfois aussi nécessaire de définir une référence à la documentation pour cette variable d’environnement en utilisant [`.. envvar::`](https://www.sphinx-doc.org/en/master/usage/domains/standard.html#directive-envvar).
- Use [`:cve:`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-cve) to reference a Common Vulnerabilities and
  Exposures (CVE) identifier. For example, use `` :cve:`2019-14232` ``.
- When documenting Python objects (classes, methods, attributes, etc.) using
  [Sphinx directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) such as `.. class::`, `.. method::`, and
  `.. attribute::`, all content must be properly indented to ensure correct
  rendering and to support features like automatic table of contents
  generation.

  Follow these rules:

  - The 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
    additional 4 spaces of indentation to maintain hierarchy.
  - Field lists (such as `:param:`, `:returns:`, etc.) must align with the
    directive’s content level.

  Exemple :

  ```rst
  .. class:: MyClass

      A brief description of the class.

      .. method:: my_method(arg1, arg2)

          Method description.

          :param arg1: Description of the first parameter
          :param arg2: Description of the second parameter

      .. attribute:: my_attribute

          Attribute description.
  ```

## Balisage spécifique à Django

En plus du [balisage propre à Sphinx](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index), la documentation de Django définit quelques unités descriptives supplémentaires :

- Réglages :

  ```rst
  .. setting:: INSTALLED_APPS
  ```

  Pour faire un lien vers un réglage, utilisez `` :setting:`INSTALLED_APPS` ``.
- Balises de gabarit :

  ```rst
  .. templatetag:: regroup
  ```

  Pour faire le lien, utilisez `` :ttag:`regroup` ``.
- Filtres de gabarit :

  ```rst
  .. templatefilter:: linebreaksbr
  ```

  Pour faire le lien, utilisez `` :tfilter:`linebreaksbr` ``.
- Requêtes de champs (par ex. `Foo.objects.filter(bar__exact=qqchose)`):

  ```rst
  .. fieldlookup:: exact
  ```

  Pour faire le lien, utilisez `` :lookup:`exact` ``.
- Commandes `django-admin`:

  ```rst
  .. django-admin:: migrate
  ```

  Pour faire le lien, utilisez `` :djadmin:`migrate` ``.
- Options de ligne de commande `django-admin`:

  ```rst
  .. django-admin-option:: --traceback
  ```

  Pour faire le lien, utilisez `` :option:`nom_commande --traceback` `` (ou omettez `nom_commande` pour les options partagées par toutes les commandes comme `--verbosity`).
- Liens vers les tickets Trac (typiquement réservés pour les notes de publication des versions correctives) :

  ```rst
  :ticket:`12345`
  ```

Django’s documentation uses a custom `console` directive for documenting
command-line examples involving `django-admin`, `manage.py`, `python`,
etc. In the HTML documentation, it renders a two-tab UI, with one tab showing
a Unix-style command prompt and a second tab showing a Windows prompt.

Par exemple, vous pouvez remplacer ce fragment :

```rst
use this command:

.. code-block:: console

    $ python manage.py shell
```

par celui-ci :

```rst
use this command:

.. console::

    $ python manage.py shell
```

Remarquez deux choses :

- Vous allez généralement remplacer les occurrences de la directive `.. code-block:: console`.
- Vous n’avez pas besoin de modifier le contenu effectif de l’exemple de code. Vous l’écrivez toujours en imaginant un environnement de type Unix (c’est-à-dire un symbole d’invite `'$'`, `'/'` comme séparateur de chemins de systèmes de fichiers, etc.)

L’exemple ci-dessus va produire un bloc d’exemple de code avec deux onglets. Le premier contiendra :

```console
$ python manage.py shell
```

(aucun changement par rapport au rendu `.. code-block:: console` standard).

Le second contiendra :

```doscon
...\> py manage.py shell
```

## Documentation de nouvelles fonctionnalités

Notre politique pour les nouvelles fonctionnalités est la suivante :

> Toute documentation pour de nouvelles fonctionnalités doit être écrite de manière à ce que les fonctionnalités uniquement disponibles pour la version de développement de Django soient clairement identifiées. Nous partons du principe que les lecteurs de la documentation utilisent la dernière version publiée et non pas la version de développement.

La méthode préférée pour marquer les nouvelles fonctionnalités est de précéder leur documentation par « `.. versionadded:: X.Y` », suivi d’une ligne vierge obligatoire et d’une description facultative (avec indentation).

General improvements or other changes to the APIs that should be emphasized
should use the « `.. versionchanged:: X.Y` » directive (with the same format
as the `versionadded` mentioned above).

Ces blocs `versionadded` et `versionchanged` doivent être « autonomes », c’est-à-dire que dans la mesure où ces annotations ne sont conservées que dans deux versions principales, il est utile de pouvoir simplement les enlever sans devoir remettre en forme, changer l’indentation ou modifier le texte avoisinant. Par exemple, au lieu de placer toute la description d’une fonctionnalité nouvelle ou modifiée dans un bloc, faite quelque chose comme ceci :

```rst
.. class:: Author(first_name, last_name, middle_name=None)

    A person who writes books.

    ``first_name`` is ...

    ...

    ``middle_name`` is ...

    .. versionchanged:: A.B

        The ``middle_name`` argument was added.
```

Placez les annotations pour les modifications au bas de la section, et non pas au-dessus.

De même, évitez de faire référence à une version spécifique de Django en dehors des blocs `versionadded` et `versionchanged`. Même dans un bloc, il est souvent redondant de mentionner des versions puisque le rendu automatique de ces annotations produit respectivement « New in Django A.B » et « Changed in Django A.B ».

Si une fonction, un attribut, etc. a été ajouté, il est aussi admis d’utiliser une annotation `versionadded` comme ceci :

```rst
.. attribute:: Author.middle_name

    .. versionadded:: A.B

    An author's middle name.
```

Nous pouvons enlever l’annotation `.. versionadded:: A.B` sans aucun changement d’indentation lorsque ce sera le bon moment.

## Minimiser les images

Optimisez la taille de compression des images quand c’est possible, pour les fichiers PBG, utilisez OptiPNG et `advpng` de AdvanceCOMP :

```console
$ cd docs
$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`
```

*Windows*

```doscon
...\> cd docs
...\> optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path ".\_build\*" -name "*.png"`
...\> advpng -z4 `find . -type f -not -path ".\_build\*" -name "*.png"`
```

Cet exemple est basé sur la version 0.7.5 de OptiPNG. Les versions plus anciennes peuvent se plaindre que l’option `-strip all` perd des données.

## Un exemple

Pour un exemple rapide sur la manière dont tout s’enchaîne, considérez l’exemple hypothétique suivant :

- Tout d’abord, la disposition générale du document `ref/settings.txt` pourrait ressembler à ceci :

  ```rst
  ========
  Settings
  ========

  ...

  .. _available-settings:

  Available settings
  ==================

  ...

  .. _deprecated-settings:

  Deprecated settings
  ===================

  ...
  ```
- Ensuite, le document `topics/settings.txt` pourrait contenir quelque chose comme :

  ```rst
  You can access a :ref:`listing of all available settings
  <available-settings>`. For a list of deprecated settings see
  :ref:`deprecated-settings`.

  You can find both in the :doc:`settings reference document
  </ref/settings>`.
  ```

  Nous utilisons l’élément de référence croisée de Sphinx [`doc`](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-doc) lorsque nous ajoutons un lien vers un autre document dans son entier et l’élément [`ref`](https://www.sphinx-doc.org/en/master/usage/referencing.html#role-ref) lorsque nous ajoutons un lien vers un emplacement spécifique dans un document.
- Puis, voyez comment les réglages sont annotés :

  ```rst
  .. setting:: ADMINS

  ADMINS
  ======

  Default: ``[]`` (Empty list)

  A list of all the people who get code error notifications...
  ```

  Ceci balise l’en-tête suivante comme la cible « canonique » du réglage `ADMINS`. Cela signifie que lors de chaque mention de `ADMINS`, on peut y faire référence avec `` :setting:`ADMINS` ``.

C’est grosso modo ainsi que le tout fonctionne.

## Traduction de la documentation

Consultez [Traduction de la documentation de Django](/fr/6.1/internals/contributing/localizing/#translating-documentation) si vous souhaitez aider à traduire la documentation dans une autre langue.

## Page de manuel `django-admin`

Sphinx peut générer une page de manuel pour la commande [django-admin](/fr/6.1/ref/django-admin/). Ceci est configuré dans `docs/conf.py`. Au contraire d’autres productions de documentation, cette page de manuel devrait être contenue dans le dépôt de Django et dans ses publications comme `docs/man/django-admin.1`. Il n’est pas nécessaire de mettre à jour ce fichier lors de la mise à jour de la documentation, car sa mise est jour fait partie du processus de publication.

To generate an updated version of the man page, in the `docs` directory, run:

```console
$ make man
```

*Windows*

```doscon
...\> make.bat man
```

The new man page will be written in `docs/_build/man/django-admin.1`.