Django管理文档生成器

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

概述¶ T0>

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

  • django.contrib.admindocs添加到您的INSTALLED_APPS中。
  • 路径('admin / doc /', include('django.contrib.admindocs.urls'))添加到您的urlpatterns 确保它包含'admin/'条目之前,这样对/admin/doc/的请求不会被后者处理条目。
  • 安装docutils Python模块(http://docutils.sf.net/)。
  • 可选的: 使用admindocs小书签需要安装django.contrib.admindocs.middleware.XViewMiddleware

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

文档助手

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

Django组件 reStructuredText角色
楷模 :型号:`app_label.ModelName`
查看 :视图:`app_label.view_name`
模板标签 :标签:`tagname`
模板过滤器 :过滤器:`filtername`
模板 :模板:'路径/要/ template.html`

模型参考

The models section of the admindocs page describes each model in the system along with all the fields and methods available on it. 与其他模型的关系显示为超链接。 描述从字段上的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."""
        ...

查看参考

您网站中的每个网址在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附带的所有标记和过滤器(实际上,built-in tag referencebuilt-in filter reference直接来自这些页面)。 您创建或由第三方应用程序添加的任何标签或过滤器也将显示在这些部分中。

模板参考

While admindocs does not include a place to document templates by themselves, if you use the :template:`path/to/template.html` syntax in a docstring the resulting page will verify the path of that template with Django’s template loaders. 这可以方便地检查指定模板是否存在,并显示存储模板的文件系统的位置。

包括Bookmarklets

一个小书签可以从admindocs页面找到:

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

Using this bookmarklet requires that XViewMiddleware is installed and that you are logged into the Django admin as a User with is_staff set to True.