Генератор административной документации Django ¶
Приложение admindocs
Django извлекает документацию из строк документации "docstrings" для моделей, представлений, тегов шаблонов и фильтров шаблонов для всех приложений в INSTALLED_APPS
и делает эту документацию доступной из .l'administration de Django
Предварительный просмотр ¶
admindocs
Вот что нужно сделать для активации :
- Добавить
admindocs
в настройкуINSTALLED_APPS
. - Добавить в шаблоны URL . Убедитесь, что это включение появляется перед строкой , чтобы запросы к линии не перехватывались.
path('admin/doc/', include('django.contrib.admindocs.urls'))
urlpatterns
'admin/'
/admin/doc/
- Установите модуль Python Docutils ( https://docutils.sourceforge.io/ ).
- Необязательно: для использования динамических закладок admindocs необходимо
django.contrib.admindocs.middleware.XViewMiddleware
установить его.
После выполнения этих шагов вы можете просмотреть документацию, перейдя в интерфейс администрирования и щелкнув ссылку «Документация» в правом верхнем углу страницы.
Мастера документации ¶
Следующая специальная разметка может использоваться в ваших строках документации «docstrings», чтобы легко ссылаться на другие компоненты:
Компонент Django | ReStructuredText роли |
---|---|
модели | :model:`étiquette_app.NomModèle` |
Просмотры | :view:`étiquette_app.nom_de_vue` |
Теги шаблона | :tag:`nom_balise` |
Фильтры шаблонов | :filter:`nom_filtre` |
Шаблоны | :template:`chemin/vers/gabarit.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 показывает соответствующее представление. Вот несколько примеров полезных вещей, которые вы можете задокументировать в строках документации «docstrings» ваших функций просмотра:
- Краткое описание того, что делает представление.
- Контекст или список переменных , доступных в шаблоне представления.
- Имя шаблона (ов), используемых для этого представления.
Например :
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:`chemin/vers/gabarit.html`
в строке «docstring», полученная страница проверит путь к этому шаблону с помощью механизма загрузчика шаблонов Django. Это может быть удобным способом проверить, существует ли шаблон, и показать, где этот шаблон хранится в файловой системе.
Включены динамические закладки ¶
Динамическая закладка доступна со страницы admindocs
:
- Документация для этой страницы
- Переход с любой страницы к документации для представления, которое создает эту страницу.
Использование этой динамической закладки требует, чтобы вы XViewMiddleware
были установлены и вошли в систему как с контейнером .l'administration de Django
User
is_staff
True