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

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

Вы можете, в некоторой степени, использовать admindocs для быстрого документирования собственного кода. Однако использование ограничено, так как приложение предназначено в первую очередь для документирования шаблонов, тегов шаблонов и фильтров. Например, методы модели, которые требуют аргументов, намеренно опущены из документации, поскольку их нельзя вызвать из шаблонов. Приложение по-прежнему может быть полезным, так как оно не требует написания дополнительной документации (кроме строк документации) и удобно доступно из Django admin.

Обзор

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

• Добавьте django.contrib.admindocs в свой INSTALLED_APPS.
• Добавьте url(r'^admin/doc/', include('django.contrib.admindocs.urls')) в свой urlpatterns. Убедитесь, что он включён до записи r'^admin/', чтобы запросы к /admin/doc/ не обрабатывались последней записью.
• Установите модуль Python docutils (http://docutils.sf.net/).
• Необязательно: Для использования закладок admindocs необходимо установить 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)
    blog = models.ForeignKey(Blog)
    ...

    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 доступны несколько полезных закладок:

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

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

Показать идентификатор объекта

Отображает тип содержимого и уникальный идентификатор для страниц, представляющих один объект.

Редактировать этот объект

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

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