Generatorn för Django-administratörsdokumentation

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.

Översikt

För att aktivera admindocs måste du göra följande:

• Lägg till django.contrib.admindocs till din :inställning:`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.

• Installera paketet docutils 0.19+.

• 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.

Hjälp med dokumentation

Följande speciella markering kan användas i dina dokumentationer för att enkelt skapa hyperlänkar till andra komponenter:

Django-komponent	reStructuredText roller
Modeller	:modell:`app_label.modellnamn``
Vyer	:vy:`app_label.vy_namn``
Malltaggar	:tag:`taggnamn``
Mallfilter	:filter:`filternamn``
Mallar	:mall:`väg/till/ mall.html``

Var och en av dessa stöder anpassad länktext med formatet :role:`link text <link>`. Till exempel: :tag:`block <built_in-block>`.

Changed in Django 5.2:

Stöd för anpassad länktext har lagts till.

Referensmodell

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:

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."""
        ...

Changed in Django 5.2:

Åtkomsten begränsades till att endast tillåta användare med behörighet att visa eller ändra modellen.

Visa referens

Varje 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:

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)

Malltaggar och filterreferens

Avsnitten tags och filters admindocs beskriver alla taggar och filter som följer med Django (i själva verket kommer dokumentationen built-in tag reference och built-in filter reference direkt från dessa sidor). Alla taggar eller filter som du skapar eller som läggs till av en app från tredje part kommer också att visas i dessa avsnitt.

Mall för referens

Medan 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.

Inkluderade Bookmarklets

Ett bokmärke finns tillgängligt från sidan admindocs:

Dokumentation för denna sida

Förflyttar dig från valfri sida till dokumentationen för vyn som genererar den sidan.

Fö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.