.. _admin_docs:

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:

..  code-block:: bash

    pip install docutils


.. admonition:: 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```

..  code-block:: python

    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``

..  code-block:: python

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

..  code-block:: python

    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:

..  code-block:: python

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

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