Djangos app admindocs hämtar dokumentation från dokumentationerna av modeller, vyer, malltaggar och mallfilter för alla appar i INSTALLED_APPS och gör den dokumentationen tillgänglig från Django admin.
För att aktivera admindocs måste du göra följande:
Lägg till django.contrib.admindocs till din INSTALLED_APPS.
Lägg till path('admin/doc/', include('django.contrib.admindocs.urls')) till dina urlpatterns. Se till att den inkluderas före posten 'admin/', så att förfrågningar till /admin/doc/ inte hanteras av den senare posten.
Install the docutils 0.22+ package.
Optional: För att använda admindocs bokmärken krävs att django.contrib.admindocs.middleware.XViewMiddleware är installerat.
När dessa steg är slutförda kan du börja bläddra i dokumentationen genom att gå till ditt administratörsgränssnitt och klicka på länken ”Dokumentation” längst upp till höger på sidan.
\nFöljande speciella markering kan användas i dina dokumentationer för att enkelt skapa hyperlänkar till andra komponenter:
\nDjango-komponent | \nreStructuredText roller | \n
|---|---|
Modeller | \n
| \n
Vyer | \n
| \n
Malltaggar | \n
| \n
Mallfilter | \n
| \n
Mallar | \n
| \n
Var och en av dessa stöder anpassad länktext med formatet :role:`link text <link>. Till exempel: :tag:`block <built_in-block>.
Avsnittet models på sidan admindocs beskriver varje modell som användaren har tillgång till samt alla fält, egenskaper och metoder som är tillgängliga för den. Relationer till andra modeller visas som hyperlänkar. Beskrivningarna hämtas från help_text-attribut på fält eller från docstrings på modellmetoder.
En modell med användbar dokumentation kan se ut så här:
\nclass BlogEntry(models.Model):\n """\n Stores a single blog entry, related to :model:`blog.Blog` and\n :model:`auth.User`.\n """\n\n slug = models.SlugField(help_text="A short label, generally used in URLs.")\n author = models.ForeignKey(\n User,\n models.SET_NULL,\n blank=True,\n null=True,\n )\n blog = models.ForeignKey(Blog, models.CASCADE)\n ...\n\n def publish(self):\n """Makes the blog entry live on the site."""\n ...\nVarje URL på din webbplats har en separat post på sidan admindocs, och om du klickar på en viss URL visas motsvarande vy. Nyttiga saker som du kan dokumentera i dina vyfunktionsdokumentationer inkluderar:
En kort beskrivning av vad vyn gör.
kontext, eller en lista över variabler som är tillgängliga i vyns mall.
Namnet på den mall eller de mallar som används för den aktuella vyn.
Till exempel:
\nfrom django.shortcuts import render\n\nfrom myapp.models import MyModel\n\n\ndef my_view(request, slug):\n """\n Display an individual :model:`myapp.MyModel`.\n\n **Context**\n\n ``mymodel``\n An instance of :model:`myapp.MyModel`.\n\n **Template:**\n\n :template:`myapp/my_template.html`\n """\n context = {"mymodel": MyModel.objects.get(slug=slug)}\n return render(request, "myapp/my_template.html", context)\nMedan admindocs inte innehåller en plats för att dokumentera mallar i sig, om du använder syntaxen :template:`path/to/template.html i en dokumentsträng kommer den resulterande sidan att verifiera sökvägen till den mallen med Djangos template loaders. Detta kan vara ett praktiskt sätt att kontrollera om den angivna mallen finns och att visa var i filsystemet den mallen är lagrad.
Ett bokmärke finns tillgängligt från sidan admindocs:
Förflyttar dig från valfri sida till dokumentationen för vyn som genererar den sidan.
\nFör att använda detta bokmärke krävs att XViewMiddleware är installerat och att du är inloggad på Django admin som en User med is_staff satt till True.