概述¶

要激活 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。

完成这些步骤后，您可以通过访问管理员界面并在页面右上角点击“文档”链接开始浏览文档。

文档助手¶

以下特殊标记可用于您的文档字符串中，以轻松创建到其他组件的超链接

模型参考¶

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，并且您需要以 User 身份登录 Django admin，并且 is_staff 设置为 True。