Django 管理文件產生器

Django 的 admindocs 應用程式會從 INSTALLED_APPS 中任何應用程式的模型、視圖、樣板標籤和樣板過濾器的 docstring 中提取文件，並使這些文件可從 Django 管理介面 中存取。

總覽

要啟用 admindocs，您需要執行以下操作：

  • 將 django.contrib.admindocs 新增到您的 INSTALLED_APPS。

  • 將 path('admin/doc/', include('django.contrib.admindocs.urls')) 新增到您的 urlpatterns。請確保它包含在 'admin/' 條目之前，這樣對 /admin/doc/ 的請求才不會由後者處理。

  • 安裝 docutils 0.19+ 套件。

  • 選用：使用 admindocs 書籤小工具需要安裝 django.contrib.admindocs.middleware.XViewMiddleware。

完成這些步驟後，您可以開始瀏覽文件，方法是進入您的管理介面，然後點擊頁面右上角的「文件」連結。

文件輔助工具

以下特殊標記可在您的 docstring 中使用，以輕鬆建立到其他元件的超連結：

Django 元件

reStructuredText 角色

模型

:model:`app_label.ModelName`

視圖

:view:`app_label.view_name`

樣板標籤

:tag:`tagname`

樣板過濾器

:filter:`filtername`

樣板

:template:`path/to/template.html`

模型參考

admindocs 頁面的模型區段描述了系統中的每個模型，以及其上所有可用的欄位、屬性和方法。與其他模型的關係會顯示為超連結。描述會從欄位的 help_text 屬性或模型方法的 docstring 中提取。

具有實用文件的模型可能如下所示：

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)

樣板標籤和過濾器參考

admindocs 的 標籤 和 過濾器 區段描述了 Django 隨附的所有標籤和過濾器（事實上，內建標籤參考 和 內建過濾器參考 文件直接來自這些頁面）。您建立或由第三方應用程式新增的任何標籤或過濾器也會顯示在這些區段中。

樣板參考

雖然 admindocs 不包括單獨記錄樣板的位置，但如果您在 docstring 中使用 :template:`path/to/template.html` 語法，則產生的頁面將會使用 Django 的 樣板載入器 來驗證該樣板的路徑。這可以方便地檢查指定的樣板是否存在，並顯示該樣板在檔案系統中的儲存位置。

包含的書籤小工具

有一個書籤小工具可從 admindocs 頁面取得：

此頁面的文件

讓您從任何頁面跳到產生該頁面的視圖的文件。

使用此書籤小工具需要安裝 XViewMiddleware，並且您必須以 User 身分登入 Django 管理介面，並將 is_staff 設定為 True。

ModelAdmin 列表篩選器
管理介面中的 JavaScript 自訂
返回頂部