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`

Each of these support custom link text with the format :role:`link text <link>`. For example, :tag:`block <built_in-block>`.

Changed in Django 5.2:

Support for custom link text was added.

モデルのリファレンス

The models section of the admindocs page describes each model that the user has access to along with all the fields, properties, and methods available on it. Relationships to other models appear as hyperlinks. Descriptions are pulled from help_text attributes on fields or from docstrings on model methods.

役に立つドキュメントを持ったモデルは次のようなものです:

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:

Access was restricted to only allow users with model view or change permissions.

ビューのリファレンス

サイト内の各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 に設定している必要があります。