Faire des docs admin django

Django est un excellent framework pour le développement web en python. Et plus je travaille avec ça, plus j’aime ça. L’une des idées que j’adore est le fait que cela fournit une interface d’administration hautement configurable. En quelques lignes de code, vous pouvez configurer une interface d’administration pour votre application Web. Aujourd’hui nous parlerons de l’un des aspects de l’admin Django: les docs admin django.

Travailler sur un projet avec une équipe nécessite beaucoup de communication entre les membres pour que tout le monde ait le même niveau d’information. Django a déjà une solution clé en main pour afficher sur le web la documentation de toutes vos vues, filtres, templates, etc en utilisant docstring.

Commentaires docstring

Docstring est un moyen pratique de fournir de la documentation en python: pour les classes, les fonctions, les modules, etc.
Il doit être inséré en tant que première déclaration de l’objet. Il doit décrire l’objet:

• Quel est le but de l’objet
• Qu’est-ce que ça renvoie
• Indique s’il déclenche une exception

Un docstring doit être entouré par trois “.Il peut être sur plusieurs lignes et vous pouvez même y ajouter du code html.

class HClass(object):
    """
    Docstring pour la class 
    """

    def funct(param1, param2):
        """Docstring pour la fonction"""
        pass

Django va analyser la docstring dans votre code et générer une belle documentation html.

Django admin docs

Les documents d’administration sont créés en extrayant docstring des modèles, des vues, des balises de modèle et des filtres de modèle pour toutes les applications dans INSTALLED_APPS. Vous pouvez utiliser markdown dans votre docstring pour personnaliser l’affichage en html: Django le comprendra. Comme l’interface d’administration, ajoutez les docs admin est très simple.

Installation

Il est déjà présent dans django il suffit de l’activer. Pour ce faire, suivez les quelques étapes ci-dessous:

Tadaa !!! votre docs admin est activé et il sera disponible sur la page d’administration (en haut et à droite de la page)

Mettre du contenue dans votre docs

Comme déjà dit ci-dessus, admin docs est généré à partir de docstring extrait dans le code source. Ainsi, une fois activé, faites simplement de la docstring dans vos vues, modèles, filtres, etc. et vous l’aurez automatiquement dans vos docs.

Une chose intéressante ici est que vous pouvez lier des éléments de votre document en utilisant des références. Pour cela, Django fournit déjà des aides que vous pouvez simplement ajouter dans votre docstring.

Django Component	doctring text
Models	:model:`app_label.ModelName`
Views	:view:`app_label.view_name`
Template tags	:tag:`tagname`
Template filters	:filter:`filtername`
Templates	:template:`path/to/template.html`

Example:

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)

Merci d’avoir lu.

Sources: