---
title: "Le générateur de documentation de l’administration de Django"
version: 4.2
locale: fr
source: https://docs.djangoproject.com/fr/4.2/ref/contrib/admin/admindocs/
canonical: https://djangodocs.dev/fr/4.2/ref/contrib/admin/admindocs/
---
# Le générateur de documentation de l’administration de Django

L’application [`admindocs`](#module-django.contrib.admindocs) de Django récupère la documentation depuis les chaînes de documentation « docstrings » des modèles, des vues, des balises de gabarit et des filtres de gabarit de toutes les applications figurant dans [`INSTALLED_APPS`](/fr/4.2/ref/settings/#std-setting-INSTALLED_APPS) et rend cette documentation disponible à partir de [`l'administration de Django`](/fr/4.2/ref/contrib/admin/#module-django.contrib.admin).

## Aperçu

Pour activer [`admindocs`](#module-django.contrib.admindocs), voici ce qu’il faut faire :

- Ajoutez [`admindocs`](#module-django.contrib.admindocs) au réglage [`INSTALLED_APPS`](/fr/4.2/ref/settings/#std-setting-INSTALLED_APPS).
- Ajoutez `path('admin/doc/', include('django.contrib.admindocs.urls'))` aux motifs d’URL `urlpatterns`. Assurez-vous que cette inclusion apparaisse *avant* la ligne `'admin/'`, de sorte que les requêtes vers `/admin/doc/` ne soient pas interceptées par cette dernière.
- Install the docutils Python module version \<0.22
  (<https://docutils.sourceforge.io/>).
- **Facultatif :** l’utilisation des signets dynamiques d’admindocs nécessite que `django.contrib.admindocs.middleware.XViewMiddleware` soit installé.

Une fois ces étapes terminées, vous pouvez parcourir la documentation en allant sur l’interface d’administration et en cliquant sur le lien « Documentation » dans le coin supérieur droit de la page.

## Assistants de documentation

Le balisage spécial suivant peut être utilisé dans vos chaînes de documentation « docstrings » afin de créer facilement des liens vers d’autres composants :

| Composant Django | Rôles reStructuredText |
| --- | --- |
| Modèles | `` :model:`étiquette_app.NomModèle` `` |
| Vues | `` :view:`étiquette_app.nom_de_vue` `` |
| Balises de gabarit | `` :tag:`nom_balise` `` |
| Filtres de gabarit | `` :filter:`nom_filtre` `` |
| Gabarits | `` :template:`chemin/vers/gabarit.html` `` |

## Référence des modèles

La section **modèles** de la page d”`admindocs` décrit chaque modèle du système avec tous les champs, propriétés et méthodes disponibles. Les relations avec les autres modèles apparaissent sous forme d’hyperliens. Les descriptions sont récupérées des attributs `help_text` pour les champs ou des chaîne de documentation « docstrings » pour les méthodes de modèle.

Un modèle avec une documentation utile pourrait ressembler à ceci :

```
class BlogEntry(models.Model):
    """
    Stores a single blog entry, related to :model:`blog.Blog` and
    :model:`auth.User`.
    """

    slug = models.SlugField(help_text="A short label, generally used in URLs.")
    author = models.ForeignKey(
        User,
        models.SET_NULL,
        blank=True,
        null=True,
    )
    blog = models.ForeignKey(Blog, models.CASCADE)
    ...

    def publish(self):
        """Makes the blog entry live on the site."""
        ...
```

## Référence des vues

Chaque URL de votre site possède une entrée séparée dans les pages `admindocs`; un clic sur une URL donnée montre la vue correspondante. Voici quelques exemples de choses utiles que vous pouvez documenter dans les chaînes de documentation « docstrings » de vos fonctions de vue :

- Une brève description de ce que la vue réalise.
- Le **contexte** ou une liste de variables disponibles dans le gabarit de la vue.
- Le nom du ou des gabarits utilisés pour cette vue.

Par exemple :

```
from django.shortcuts import render

from myapp.models import MyModel

def my_view(request, slug):
    """
    Display an individual :model:`myapp.MyModel`.

    **Context**

    ``mymodel``
        An instance of :model:`myapp.MyModel`.

    **Template:**

    :template:`myapp/my_template.html`
    """
    context = {"mymodel": MyModel.objects.get(slug=slug)}
    return render(request, "myapp/my_template.html", context)
```

## Référence des balises et filtres de gabarit

Les sections **balises** et **filtres** d”`admindocs` décrivent toutes les balises et les filtres livrés avec Django (en fait, la documentation de [référence des balises intégrées](/fr/4.2/ref/templates/builtins/#ref-templates-builtins-tags) et des [filtres intégrés](/fr/4.2/ref/templates/builtins/#ref-templates-builtins-filters) proviennent directement de ces pages). Toutes les balises ou les filtres que vous créez ou qui sont ajoutés par une application tierce apparaîtront aussi dans ces sections.

## Référence des gabarits

Bien qu”`admindocs` n’offre aucun moyen de documenter les gabarits eux-mêmes, si vous utilisez la syntaxe `` :template:`chemin/vers/gabarit.html` `` dans une chaîne « docstring », la page résultante vérifiera le chemin de ce gabarit avec le [moteur de chargement des gabarits](/fr/4.2/ref/templates/api/#template-loaders) de Django. Cela peut être un moyen pratique pour vérifier si le gabarit existe et de montrer où ce gabarit est stocké dans le système de fichiers.

## Signets dynamiques inclus

Un signet dynamique est disponible depuis la page `admindocs`:

**Documentation pour cette page**

  Vous renvoie depuis n’importe quelle page vers la documentation de la vue qui génère cette page.

L’utilisation de ce signet dynamique nécessite que `XViewMiddleware` soit installé et que vous soyez connecté à [`l'administration de Django`](/fr/4.2/ref/contrib/admin/#module-django.contrib.admin) en tant que  [`User`](/fr/4.2/ref/contrib/auth/#django.contrib.auth.models.User) avec [`is_staff`](/fr/4.2/ref/contrib/auth/#django.contrib.auth.models.User.is_staff) contenant `True`.