Генератор документации Django админ-панели

Приложение Django admindocs извлекает документацию из строковых представлений моделей, представлений, тегов шаблонов и фильтров шаблонов для любого приложения в INSTALLED_APPS и делает эту документацию доступной из Django admin.

Обзор

Чтобы активировать admindocs, необходимо выполнить следующие действия:

• Добавьте django.contrib.admindocs в свой INSTALLED_APPS.
• Добавьте path('admin/doc/', include('django.contrib.admindocs.urls')) в свой urlpatterns. Убедитесь, что оно включено перед записью 'admin/', чтобы запросы к /admin/doc/ не обрабатывались последним.
• Установите модуль Python docutils (https://docutils.sourceforge.io/).
• Необязательно: Для использования закладок админ-документации необходимо установить django.contrib.admindocs.middleware.XViewMiddleware.

После выполнения этих шагов можно начать просмотр документации, перейдя в интерфейс администрирования и нажав ссылку «Документация» в правом верхнем углу страницы.

Справочные инструменты документации

В строковых представлениях можно использовать следующие специальные теги, чтобы легко создавать гиперссылки на другие компоненты:

Справочник моделей

Раздел моделей на странице admindocs описывает каждую модель в системе вместе со всеми полями, свойствами и методами, доступными для неё. Связи с другими моделями отображаются как гиперссылки. Описания берутся из атрибутов help_text полей или из строковых представлений методов моделей.

Модель с полезной документацией может выглядеть так:

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

Справочник представлений

У каждой страницы на вашем сайте есть отдельная запись на странице admindocs, и клик по данной ссылке покажет соответствующее представление. Полезная информация, которую можно задокументировать в строковых представлениях функций представления, включает:

• Короткое описание того, что делает представление.
• Контекст, или список переменных, доступных в шаблоне представления.
• Имя шаблона или шаблонов, используемых для этого представления.

Например:

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)

Справочник тегов и фильтров шаблонов

Разделы тегов и фильтров admindocs описывают все теги и фильтры, которые поставляются с Django (на самом деле документация справочника встроенных тегов и справочника встроенных фильтров взята непосредственно с этих страниц). Любые теги или фильтры, которые вы создаёте или которые добавляются приложением сторонних разработчиков, также будут отображаться в этих разделах.

Справочник шаблонов

Хотя admindocs не содержит места для документирования шаблонов самих по себе, если вы используете синтаксис :template:`path/to/template.html`, результирующая страница проверит путь к этому шаблону с помощью загрузчиков шаблонов Django. Это может быть полезным способом проверить, существует ли указанный шаблон, и показать, где этот шаблон хранится в файловой системе.

Включенные Закладки

Одна закладка доступна с страницы admindocs:

Документация для этой страницы

Переносит вас с любой страницы к документации представления, генерирующего эту страницу.

Для использования этой закладки необходимо установить XViewMiddleware, и вы должны быть авторизованы на Django admin как User с is_staff установленным в значение True.