Django 管理文档生成器

Django 的 admindocs 应用程序从 :setting:`INSTALLED_APPS` 中的任何应用程序的模型、视图、模板标签和模板过滤器的文档字符串中提取文档，并从中提供该文档]Django 管理员。

概览

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

将 django.contrib.admindocs 添加到您的 :setting:`INSTALLED_APPS`。
将 path('admin/doc/', include('django.contrib.admindocs.urls')) 添加到您的 urlpatterns。确保在 的 'admin/' 条目之前包含 ，以便对 /admin/doc/ 的请求不会被后一个条目处理。
安装 docutils Python 模块 (https://docutils.sourceforge.io/)。
可选： 使用 admindocs 书签需要安装 django.contrib.admindocs.middleware.XViewMiddleware。

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

文档助手

可以在您的文档字符串中使用以下特殊标记轻松创建指向其他组件的超链接：

Django 组件	重构文本角色
型号	:model:`app_label.ModelName`
观看次数	:view:`app_label.view_name`
模板标签	:tag:`tagname`
模板过滤器	:filter:`filtername`
模板	:template:`path/to/template.html`

型号参考

admindocs 页面的 models 部分描述了系统中的每个模型及其上可用的所有字段、属性和方法。与其他模型的关系显示为超链接。描述是从字段的 help_text 属性或模型方法的文档字符串中提取的。

2.2 版更改：旧版本不显示模型属性。

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

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 将显示相应的视图。您可以在视图函数文档字符串中记录的有用内容包括：

视图功能的简短描述。
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 和 filters admindocs 部分描述了 Django 附带的所有标签和过滤器（实际上，内置标签参考和内置过滤器参考文档直接来自这些页面）。您创建或由第三方应用程序添加的任何标签或过滤器也将显示在这些部分中。

模板参考

虽然 admindocs 不包含单独记录模板的位置，但如果您在文档字符串中使用 :template:`path/to/template.html` 语法，生成的页面将使用 Django 的模板加载器验证该模板的路径[ X216X]。这是检查指定模板是否存在以及显示模板存储在文件系统上的位置的一种方便的方法。

包括书签

admindocs 页面提供了一个书签：

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

使用此书签需要安装 XViewMiddleware 并且您以 User 的身份登录 Django admin，并将 is_staff 设置为 True。

Django 管理文档生成器 — Django 文档

目录