Генератор административной документации 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 admin
User
is_staff
True