Django管理文档生成器

Django的admindocs应用从模型、视图、模板标签以及模板过滤器中,为任何INSTALLED_APPS中的应用获取文档。并且让文档可以在Django admin中使用。

概述¶ T0>

要启用admindocs,你需要执行以下步骤:

  • INSTALLED_APPS添加django.contrib.admindocs
  • Add url(r'^admin/doc/', include('django.contrib.admindocs.urls')) to your urlpatterns. 确保它在/admin/doc/ 这一项 之前包含,以便r'^admin/' 的请求不会被后面的项目处理。
  • 安装docutils Python 模块 (http://docutils.sf.net/)。
  • 可选的: 使用admindocs的书签功能需要安装django.contrib.admindocs.middleware.XViewMiddleware

一旦完成这些步骤,你可以开始通过你的admin接口和点击在页面右上方的“Documentation”链接来浏览文档。

文档助手

下列特定的标记可以用于你的docstrings,来轻易创建到其他组件的超链接:

Django组件 reStructuredText角色
模型 :模型:`app_label.ModelName`
视图 :视图:`app_label.view_name`
模板标签 :标签:`tagname`
模板过滤器 :过滤器:`filtername`
模板 :模板:'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会向你展示相应的视图。 有一些有用的东西,你可以在你的视图函数的docstring中记录:

  • 视图所做工作的一个简短的描述。
  • 上下文,或者是视图的模板中可用变量的列表。
  • 用于当前视图的模板的名称。

像这样:

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)

模板标签和过滤器引用

admindocstagsfilters部分描述了Django自带的所有标签和过滤器(事实上,built-in tag referencebuilt-in filter reference文档直接来自于那些页面)。 你创建的,或者由三方应用添加的任何标签或者过滤器,也会在这一部分中展示。

模板参考

虽然:template:`path/to/template.html` 并不包含一个地方来保存模板,但如果你在结果页面中使用admindocs语法,会使用Django的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.