• 3.1
  • 3.2
  • 5.0
  • Версия документации: 6.1

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

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

Обзор

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

  • Добавьте django.contrib.admindocs в INSTALLED_APPS.

  • Добавьте path('admin/doc/', include('django.contrib.admindocs.urls')) в ваш urlpatterns. Убедитесь, что он включен перед записью 'admin/', чтобы запросы к /admin/doc/ не обрабатывались последней записью.

  • Установите пакет docutils 0.22+.

  • Необязательно: Для использования закладок admindocs требуется установка django.contrib.admindocs.middleware.XViewMiddleware.

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

Помощники по документации

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

Компонент Джанго

роли reStructuredText

Модели

:model:`app_label.ModelName`

Просмотры

:view:`app_label.view_name`

Шаблонные теги

:tag:`tagname`

Фильтры шаблонов

:filter:`имя_фильтра`

Шаблоны

:template:`path/to/template.html`

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

Changed in Django 5.2:

Добавлена ​​поддержка пользовательского текста ссылки.

Ссылка на модель

Раздел модели на странице 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."""
        ...
Changed in Django 5.2:

Доступ был ограничен и разрешен только пользователям с разрешениями на просмотр модели или изменение.

Посмотреть ссылку

Каждый 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)

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

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

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

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

Включенные букмарклеты

Один букмарклет доступен на странице «admindocs»:

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

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

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

Back to Top