Die Admin Doku einrichten

Die Admindocs-App von Django ruft die Dokumentation aus den Docstrings von Models, Views, Template-Tags und filtern für jede App in INSTALLED_APPS ab und stellt diese Dokumentation über den Django-Administrator zur Verfügung.

Einrichten der Admin Dokumentation

Installieren von docutils

Um den Code rendern zu können, benötigt die Admindocs-App das Tool docutils. Es kann einfach installiert werden:

pip install docutils

Docutils

Docutils ist ein Open-Source-Textverarbeitungssystem zur Verarbeitung von Textdokumentation in nützliche Formate wie HTML, LaTeX, Manpages, OpenDocument oder XML. Es enthält reStructuredText, die einfach zu lesende, einfach zu verwendende Markup-Sprache.

Mehr zu Docutils hier: https://docutils.sourceforge.io/

Installed Apps

Hinzufügen zu den INSTALLED_APPS in den settings.base.py`

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "django.contrib.admindocs",  # hier hinzufügen
    "crispy_forms",
]

Urls

in den urlpatterns des Projekts unter event_manager/urls.py

urlpatters = [
    # andere Einträge
    path("admin/doc/", include("django.contrib.admindocs.urls")),
]

Mehr Infos: https://docs.djangoproject.com/en/stable/contrib/admin/admindocs/

Dann die URL http://127.0.0.1:8000/admin/doc/ besuchen und staunen!

Code pimpen

Mit einfachen Mitteln lässt sich Code mit Meta-Angaben versehen, der in der Admin Doc gerendet wird.

dazu öffnen wir die Datei event_manager/events/models.py und ändern den DocString des Models Event wie folgt ab.

class Event(DateMixin):
    """Stores a single blog entry, related to :model:`events.Category` and
    :model:`user.User`."""

    class Group(models.IntegerChoices):
        BIG = 20
        SMALL = 5
        MEDIUM = 10

Wir öffnen ebenfalls die Datei event_manager/events/views.py und ändern den Docstring der EventCreateView ab:

class EventCreateView(LoginRequiredMixin, CreateView):
    """
    create an event :model:`events.Event`.
    events/event/create/3

    **Template:**
    :template:`events/event_form.html`
    """