# Django管理文檔生成器 # Django的`admindocs`應用從模型、視圖、模板標簽以及模板過濾器中，為任何`INSTALLED_APPS`中的應用獲取文檔。并且讓文檔可以在`Django admin`中使用。 在某種程度上，你可以使用`admindocs`來快為你自己的代碼生成文檔。這個應用的功能十分有限，然而它主要用于文檔模板、模板標簽和過濾器。例如，需要參數的模型方法在文檔中會有意地忽略，因為它們不能從模板中調用。這個應用仍舊有用，因為它并不需要你編寫任何額外的文檔（除了`docstrings`），并且在 `Django admin`中使用很方便。 ## 概覽 ## 要啟用`admindocs`，你需要執行以下步驟： + 向 `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`，來輕易創建到其他組件的超鏈接： 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`頁面的`models`部分描述了系統中每個模型，以及所有可用的字段和方法（不帶任何參數）。雖然模型的屬性沒有任何參數，但他們沒有列出。和其它模型的關聯以超鏈接形式出現。描述由字段上的`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會向你展示相應的視圖。有一些有用的東西，你可以在你的視圖函數的·中記錄： + 視圖所做工作的一個簡短的描述。 + 上下文，或者是視圖的模板中可用變量的列表。 + 用于當前視圖的模板的名稱。 例如： ``` 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自帶的所有標簽和過濾器（事實上，內建的標簽參考 和 內建的過濾器參考文檔直接來自于那些頁面）。你創建的，或者由三方應用添加的任何標簽或者過濾器，也會在這一部分中展示。 ## 模板參考 ## 雖然`admindocs` 并不包含一個地方來保存模板，但如果你在結果頁面中使用<code>:template:\`path/to/template.html\`</code>語法，會使用Django的模板加載器來驗證該模板的路徑。這是一個非常便捷的方法，來檢查是否存在特定的模板，以及展示模板在文件系統的何處存放。 ## 包含的書簽 ## `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` 設置為 `True`的`User`登錄`Django admin`，或者安裝了`XViewMiddleware`并且你通過 `INTERNAL_IPS`中的IP地址訪問站點。 > 譯者：[Django 文檔協作翻譯小組](http://python.usyiyi.cn/django/index.html)，原文：[Admin documentation generator](https://docs.djangoproject.com/en/1.8/ref/contrib/admin/admindocs/)。 > > 本文以 [CC BY-NC-SA 3.0](http://creativecommons.org/licenses/by-nc-sa/3.0/cn/) 協議發布，轉載請保留作者署名和文章出處。 > > [Django 文檔協作翻譯小組](http://python.usyiyi.cn/django/index.html)人手緊缺，有興趣的朋友可以加入我們，完全公益性質。交流群：467338606。