django Admin文檔生成器使用詳解

更新時(shí)間：2019年07月22日 14:40:49 作者：NAVYSUMMER

這篇文章主要介紹了django Admin文檔生成器,文中通過示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友可以參考下

前言

Django的admindocs應(yīng)用可以從模型、視圖、模板標(biāo)簽等地方獲得文檔內(nèi)容。

一、概覽

要激活admindocs，請(qǐng)按下面的步驟操作：

在INSTALLED_APPS內(nèi)添加django.contrib.admindocs
在urlpatterns內(nèi)添加url(r'^admin/doc/',include('django.contrib.admindocs.urls'))。確保它處于r'^admin/'條目之前，原因你懂的。
安裝Python的docutils模塊(http://docutils.sf.net/)(pip3 install docutils)
可選：想使用admindocs的書簽小工具，需要安裝django.contrib.admindocs.middleware.XViewMiddleware

如果上述步驟順利完成，那么你可以從admin界面訪問doc界面，也可以直接訪問/admin/doc，如下圖：

它看起來是下面的樣子：

下面的這些特殊標(biāo)記，可幫助你在文檔字符串中，快速創(chuàng)建指向其它組件的鏈接：

二、模型

在doc頁面的模型部分，列出了所有的模型，點(diǎn)擊可以查看具體的字段等細(xì)節(jié)信息。信息主要來自字段的help_txt部分和模型方法的docstring部分。如下面圖中展示：

有用的幫助信息看起來是這個(gè)樣子的：

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

三、視圖

站點(diǎn)內(nèi)的每個(gè)URL都會(huì)在doc內(nèi)享有一個(gè)頁面，點(diǎn)擊某個(gè)URL將會(huì)展示對(duì)應(yīng)的視圖信息。主要包括下面這些信息，請(qǐng)盡量豐富它們：

視圖功能的簡單描述
上下文環(huán)境，或者視圖模塊里的變量列表
視圖內(nèi)使用的模板

例如：

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)