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

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