Django的admindocs應用從模型、視圖、模板標簽以及模板過濾器中，為任何INSTALLED_APPS中的應用獲取文檔。并且讓文檔可以在Django admin中使用。

在某種程度上，你可以使用admindocs來快為你自己的代碼生成文檔。這個應用的功能十分有限，然而它主要用于文檔模板、模板標簽和過濾器。例如，需要參數(shù)的模型方法在文檔中會有意地忽略，因為它們不能從模板中調(diào)用。這個應用仍舊有用，因為它并不需要你編寫任何額外的文檔（除了docstrings），并且在 Django admin中使用很方便。

概覽

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

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

一旦完成這些步驟，你可以開始通過你的admin接口和點擊在頁面右上方的“Documentation”鏈接來瀏覽文檔。

文檔助手

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

模型參考

admindocs頁面的models部分描述了系統(tǒng)中每個模型，以及所有可用的字段和方法（不帶任何參數(shù)）。雖然模型的屬性沒有任何參數(shù)，但他們沒有列出。和其它模型的關(guān)聯(lián)以超鏈接形式出現(xiàn)。描述由字段上的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)
    blog = models.ForeignKey(Blog)
    ...

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

視圖參考

你站點中的每個URL都在·頁面中有一個單獨的記錄，點擊提供的URL會向你展示相應的視圖。有一些有用的東西，你可以在你的視圖函數(shù)的·中記錄：

• 視圖所做工作的一個簡短的描述。
• 上下文，或者是視圖的模板中可用變量的列表。
• 用于當前視圖的模板的名稱。

例如：

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的tags 和filters部分描述了Django自帶的所有標簽和過濾器（事實上，內(nèi)建的標簽參考 和 內(nèi)建的過濾器參考文檔直接來自于那些頁面）。你創(chuàng)建的，或者由三方應用添加的任何標簽或者過濾器，也會在這一部分中展示。

模板參考

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

包含的書簽

admindocs頁面上有一些很有用的書簽：

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地址訪問站點。

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

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

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