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

Copyright ©2020 All rights reserved