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

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

Обзор

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

  • Добавьте django.contrib.admindocs к вашему INSTALLED_APPS.
  • Добавьте path('admin/doc/', include('django.contrib.admindocs.urls')) к вашему urlpatterns. Убедитесь, что он включен перед записью 'admin/', чтобы запросы к /admin/doc/ не обрабатывались последней записью.
  • Установите модуль docutils Python (http://docutils.sf.net/).
  • Опционально: Использование букмарклетов admindocs требует установки django.contrib.admindocs.middleware.XViewMiddleware.

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

Помощники в работе с документацией

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

Компонент Django роли reStructuredText
Модели :model:`app_label.ModelName`
Просмотры :view:`app_label.view_name`
Теги шаблона :tag:`tagname`
Шаблонные фильтры :filter:`filtername`
Шаблоны :template:`path/to/template.html`

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

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

Changed in Django 2.2:

Более старые версии не отображают свойства модели.

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

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)

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

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

Ссылка на шаблон

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

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

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

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

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

Действия администратора
Настройки JavaScript в админке
Вернуться на верх