django管理文档生成器

Django admindocs 应用程序从任何应用程序的模型、视图、模板标记和模板过滤器的文档字符串中提取文档 INSTALLED_APPS 并使该文档可从 Django admin .

概述

激活 admindocs ，您需要执行以下操作：

  • 添加 django.contrib.admindocs 对你 INSTALLED_APPS .

  • 添加 path('admin/doc/', include('django.contrib.admindocs.urls')) 对你 urlpatterns . 确保包括在内 之前 这个 'admin/' 输入，以便请求 /admin/doc/ 不要被后一个条目处理。

  • 安装 docutils 0.19+套餐。

  • 可选的： 使用AdminDocs书签需要 django.contrib.admindocs.middleware.XViewMiddleware 待安装。

完成这些步骤后，您可以进入管理界面并单击页面右上角的“文档”链接，开始浏览文档。

文档帮助程序

可以在docstrings中使用以下特殊标记轻松创建指向其他组件的超链接：

Django组件

重构文本角色

模型

:model:`app_label.ModelName`

意见

:view:`app_label.view_name`

模板标签

:tag:`tagname`

模板筛选器

:filter:`filtername`

模板

:template:`path/to/template.html`

模型参考

这个 模型 剖面图 admindocs 页面描述系统中的每个模型以及所有可用的字段、属性和方法。与其他模型的关系显示为超链接。描述来自 help_text 字段上的属性或来自模型方法上的DocStrings的属性。

包含有用文档的模型可能如下所示：

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中记录的有用内容包括：

  • 视图功能的简短描述。

  • 这个 context 或视图模板中可用的变量列表。

  • 用于该视图的一个或多个模板的名称。

例如：：

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)

模板标记和筛选器引用

这个 tags 和 过滤器 admindocs 章节描述了Django附带的所有标签和过滤器（实际上， built-in tag reference 和 built-in filter reference 文档直接来自这些页面）。您创建的或由第三方应用程序添加的任何标签或过滤器也将显示在这些部分中。

模板引用

同时 admindocs 如果使用 :template:`path/to/template.html 语法在docstring中，生成的页面将使用django验证该模板的路径 :ref:`template loaders <template-loaders> . 这是一种检查指定模板是否存在以及显示该模板在文件系统中存储位置的简便方法。

包括书签

一个书签可从 admindocs 页：

本页文档

将您从任何页面跳转到生成该页面的视图的文档。

使用这个书签需要 XViewMiddleware 已安装并且您已登录到 Django admin 作为一个 User 具有 is_staff 设置为 True .

« previous | up | next »