Django admin ドキュメントジェネレータ

Django の admindocs アプリは、 INSTALLED_APPS にある任意のアプリのモデル、ビュー、テンプレートタグ、 テンプレートフィルタの docstring からドキュメントを取り出し、 Django admin から利用できるようにします。

概要

admindocs を有効にするには、以下のようにします。

• INSTALLED_APPS に django.contrib.admindocs を追加します。

• urlpatterns に path('admin/doc/', include('django.contrib.admindocs.urls')) を追加します。これは 'admin/' の前にインクルードして、 /admin/doc/ へのリクエストが 'admin/' のエントリで処理されないようにします。

• 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`

これらはすべて、 :role:`link text <link>` の形式でカスタムリンクテキストをサポートしています。たとえば、 :tag:`block <built_in-block>` のように記述します。

Changed in Django 5.2:

カスタムリンクテキストをサポートするようになりました。

モデルのリファレンス

admindocs ページの models セクションでは、ユーザーがアクセス可能な各モデルについて、そのすべてのフィールド、プロパティ、メソッドとともに説明されます。他のモデルとのリレーションはハイパーリンクとして表示されます。説明文は、フィールドの 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."""
        ...

Changed in Django 5.2:

アクセス権はモデルの view または change の権限を持つユーザのみに制限されました。

ビューのリファレンス

サイト内の各URLは admindocs ページに個別のエントリーがあり、指定したURLをクリックすると対応するビューが表示されます。ビュー関数のdocstringに書いておくと便利な内容は以下のようなものです:

• ビューが何をするのかについての短い説明。

• context 、あるいはビューのテンプレートで使用可能な変数のリスト。

• そのビューで使用されるテンプレート名。

例:

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 の テンプレート ローダ を使ってテンプレートのパスを確認します。これは、指定されたテンプレートが存在するかどうかを確認し、そのテンプレートがファイルシステム上のどこに保存されているかを表示する便利な方法です。

付属のブックマークレット

1 つのブックマークレットが admindocs ページから利用できます:

このページのドキュメント

各ページから、ページを生成したビューのドキュメントにジャンプします。

このブックマークレットを使用するには、 XViewMiddleware がインストールされ、 User として Django admin にログインし、 is_staff を True に設定している必要があります。