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
.
Pour activer admindocs
, voici ce qu’il faut faire :
Ajoutez admindocs
au réglage 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.
Installez le paquet docutils 0.19+.
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.
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 |
|
Vues |
|
Balises de gabarit |
|
Filtres de gabarit |
|
Gabarits |
|
Each of these support custom link text with the format
:role:`link text <link>`
. For example, :tag:`block <built_in-block>`
.
Support for custom link text was added.
The models section of the admindocs
page describes each model that the
user has access to along with all the fields, properties, and methods available
on it. Relationships to other models appear as hyperlinks. Descriptions are
pulled from help_text
attributes on fields or from docstrings on model
methods.
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."""
...
Access was restricted to only allow users with model view or change permissions.
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)
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.
Un signet dynamique est disponible depuis la page admindocs
:
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
en tant que User
avec is_staff
contenant True
.
avr. 05, 2025