在某種程度上，你可以使用admindocs來(lái)快為你自己的代碼生成文檔。這個(gè)應(yīng)用的功能十分有限，然而它主要用于文檔模板、模板標(biāo)簽和過濾器。例如，需要參數(shù)的模型方法在文檔中會(huì)有意地忽略，因?yàn)樗鼈儾荒軓哪０逯姓{(diào)用。這個(gè)應(yīng)用仍舊有用，因?yàn)樗⒉恍枰憔帉懭魏晤~外的文檔（除了docstrings），并且在 Django admin中使用很方便。

概覽

要啟用admindocs，你需要執(zhí)行以下步驟：

向 INSTALLED_APPS添加django.contrib.admindocs。
向你的urlpatterns添加(r'^admin/doc/', include('django.contrib.admindocs.urls'))。確保它在r'^admin/' 這一項(xiàng) 之前包含，以便/admin/doc/的請(qǐng)求不會(huì)被后面的項(xiàng)目處理。
安裝docutils Python 模塊 (http://docutils.sf.net/)。
可選的：使用admindocs的書簽功能需要安裝django.contrib.admindocs.middleware.XViewMiddleware。

一旦完成這些步驟，你可以開始通過你的admin接口和點(diǎn)擊在頁(yè)面右上方的“Documentation”鏈接來(lái)瀏覽文檔。

文檔助手

下列特定的標(biāo)記可以用于你的docstrings，來(lái)輕易創(chuàng)建到其他組件的超鏈接：

Django Component	reStructuredText roles
Models	:model:`app_label.ModelName`
Views	:view:`app_label.view_name`
Template tags	:tag:`tagname`
Template filters	:filter:`filtername`
Templates	:template:`path/to/template.html`

模型參考

admindocs頁(yè)面的models部分描述了系統(tǒng)中每個(gè)模型，以及所有可用的字段和方法（不帶任何參數(shù)）。雖然模型的屬性沒有任何參數(shù)，但他們沒有列出。和其它模型的關(guān)聯(lián)以超鏈接形式出現(xiàn)。描述由字段上的help_text屬性，或者從模型方法的docstrings導(dǎo)出。

帶有有用文檔的模型看起來(lái)像是這樣：

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)
    blog = models.ForeignKey(Blog)
    ...

    def publish(self):
        """Makes the blog entry live on the site."""
        ...

視圖參考

你站點(diǎn)中的每個(gè)URL都在·頁(yè)面中有一個(gè)單獨(dú)的記錄，點(diǎn)擊提供的URL會(huì)向你展示相應(yīng)的視圖。有一些有用的東西，你可以在你的視圖函數(shù)的·中記錄：

視圖所做工作的一個(gè)簡(jiǎn)短的描述。
上下文，或者是視圖的模板中可用變量的列表。
用于當(dāng)前視圖的模板的名稱。

例如：

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)

模板標(biāo)簽和過濾器參考

admindocs的tags 和filters部分描述了Django自帶的所有標(biāo)簽和過濾器（事實(shí)上，內(nèi)建的標(biāo)簽參考和內(nèi)建的過濾器參考文檔直接來(lái)自于那些頁(yè)面）。你創(chuàng)建的，或者由三方應(yīng)用添加的任何標(biāo)簽或者過濾器，也會(huì)在這一部分中展示。

模板參考

雖然admindocs 并不包含一個(gè)地方來(lái)保存模板，但如果你在結(jié)果頁(yè)面中使用:template:`path/to/template.html`語(yǔ)法，會(huì)使用Django的模板加載器來(lái)驗(yàn)證該模板的路徑。這是一個(gè)非常便捷的方法，來(lái)檢查是否存在特定的模板，以及展示模板在文件系統(tǒng)的何處存放。

包含的書簽

admindocs頁(yè)面上有一些很有用的書簽：

Documentation for this page

Jumps you from any page to the documentation for the view that generates that page.

Show object ID

Shows the content-type and unique ID for pages that represent a single object.

Edit this object

Jumps to the admin page for pages that represent a single object.

為使用這些書簽，你需要用帶有is_staff 設(shè)置為 True的User登錄Django admin，或者安裝了XViewMiddleware并且你通過 INTERNAL_IPS中的IP地址訪問站點(diǎn)。

譯者：Django 文檔協(xié)作翻譯小組，原文：Admin documentation generator。

本文以 CC BY-NC-SA 3.0 協(xié)議發(fā)布，轉(zhuǎn)載請(qǐng)保留作者署名和文章出處。

Django 文檔協(xié)作翻譯小組人手緊缺，有興趣的朋友可以加入我們，完全公益性質(zhì)。交流群：467338606。

上一篇：基于類的內(nèi)建通用視圖下一篇：管理文件