Skip to main content

Django管理文档生成器

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

概述

要激活 admindocs,您需要执行以下操作:

  • django.contrib.admindocs 添加到您的 INSTALLED_APPS

  • url(r'^admin/doc/', include('django.contrib.admindocs.urls')) 添加到您的 urlpatterns。确保它包含 before r'^admin/' 条目,因此对 /admin/doc/ 的请求不会由后一条目处理。

  • 安装docutils Python模块(http://docutils.sf.net/)。

  • 可选的: 使用admindocs bookmarklets需要安装 django.contrib.admindocs.middleware.XViewMiddleware

完成这些步骤后,您可以转到管理界面并点击页面右上方的“文档”链接,开始浏览文档。

文档助手

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

Django组件

reStructuredText角色

楷模

:model:`app_label.ModelName`

视图

:view:`app_label.view_name`

模板标签

:tag:`tagname`

模板过滤器

:filter:`filtername`

模板

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

模型参考

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

Changed in Django 1.9:

admindocs楷模 部分现在描述了接受参数的方法。在以前的版本中,它仅限于没有参数的方法。

具有有用文档的模型可能如下所示:

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."""
        ...

查看参考

您网站中的每个网址在 admindocs 页面中都有一个单独的条目,点击给定的网址会显示相应的视图。有用的东西,你可以在你的视图文档中记录文档包括:

  • 视图的作用的简短描述。

  • 上下文,或视图模板中可用的变量列表。

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

例如:

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 不包括自己记录模板的地方,但如果在docstring中使用 :template:`path/to/template.html` 语法,则生成的页面将使用Django的 模板加载器 验证该模板的路径。这可以是一种方便的方法来检查指定的模板是否存在,并显示文件系统上存储模板的位置。

包括书签

admindocs 页面提供了一个书签:

本页的文档

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

使用此书签需要安装 XViewMiddleware,并且您作为 User 登录 Django adminis_staff 设置为 True