Генератор документации 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 template loaders. Это может быть полезный способ проверить, существует ли указанный шаблон, и показать, где на файловой системе хранится этот шаблон.

Включённые Закладки

Одна закладка доступна со страницы admindocs:

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

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

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