Генератор документации административного сайта Django

Обзор

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

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

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

Вспомогательные средства для документации

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

Для каждого из них можно задать собственный текст ссылки в формате :role:`link text <link>`. Например, :tag:`block <built_in-block>`.

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

Раздел моделей страницы 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."""
        ...

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

Каждому URL-адресу вашего сайта соответствует отдельная запись на странице admindocs, и при нажатии на URL-адрес отображается соответствующее представление. В строках документации функции представления полезно описать:

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

Например:

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.