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

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

Обзор

Для активации admindocsвам потребуется сделать следующее:

  • Добавьте django.contrib.admindocsв свой INSTALLED_APPS.
  • Добавьте в свой . Убедитесь , что он включен , прежде чем в записи, так что просьбы не получить обрабатываются последней записи.path('admin/doc/', include('django.contrib.admindocs.urls'))urlpatterns'admin/'/admin/doc/
  • Установите модуль Python для документов ( https://docutils.sourceforge.io/ ).
  • Необязательно: для использования букмарклетов 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атрибутов в полях или из строк документации в методах модели.

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

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 adminUseris_staffTrue

Copyright ©2021 All rights reserved