Le générateur de documentation de l’administration de Django

L’application 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 et rend cette documentation disponible à partir de l'administration de Django.

Vous pouvez jusqu’à un certain point utiliser admindocs pour documenter rapidement votre propre code. Cet usage présente cependant des limites, car cette application est principalement destinée à documenter des gabarits, des balises de gabarit et des filtres. Par exemple, les méthodes de modèles qui acceptent des paramètres sont volontairement exclues de cette documentation parce qu’elles ne peuvent pas être appelées à partir des gabarits. Cette application peut tout de même être utile car elle ne demande aucune rédaction de documentation supplémentaire (en dehors des chaînes « docstring ») et peut être facilement accessible depuis l’administration de Django.

Aperçu

Pour activer admindocs, voici ce qu’il faut faire :

• Ajoutez admindocs au réglage INSTALLED_APPS.

• Ajoutez url(r'^admin/doc/', include('django.contrib.admindocs.urls')) aux motifs d’URL urlpatterns. Assurez-vous que cette inclusion apparaisse avant la ligne r'^admin/', de sorte que les requêtes vers /admin/doc/ ne soient pas interceptées par cette dernière.

• Installez le module Python docutils (http://docutils.sf.net/).

• 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 et les méthodes (sans paramètres) disponibles. Bien que les propriétés du modèle n’ont pas de paramètres, ils ne sont pas documentés. 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)
    blog = models.ForeignKey(Blog)
    ...

    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 et des filtres intégrés 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 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

Plusieurs signets dynamiques utiles sont disponibles 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.

Afficher l’identifiant de l’objet

Indique le type de contenu et l’identifiant unique pour les pages qui représentent un objet unique.

Modifier cet objet

Passe à la page d’administration des pages qui représentent un objet unique.

L’utilisation de ces signets dynamiques nécessite que vous soyez soit connecté à l'administration de Django en tant que User avec is_staff contenant True, soit que l’intergiciel XViewMiddleware soit installé et que vous accédiez au site à partir d’une adresse IP référencée dans INTERNAL_IPS.