English
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.
python152 B
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:
- Ajoutez django.contrib.admindocs à votre INSTALLED_APPS.
- Ajoutez l'URL (r '^admin/doc/', include ('django.contrib.admindocs.urls')) à vos URLs. Assurez-vous qu'il est inclus avant l'entrée r'^admin/', afin que les demandes adressées à /admin/doc/ ne soient pas traitées par cette dernière entrée.
- Installez le module Python docutils (http://docutils.sf.net/).
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:
python424 B
Merci d'avoir lu.
Sources:
