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`

モデルのリファレンス

admindocs ページの モデル セクションでは、システムの各モデルについて、そのモデルで利用可能なすべてのフィールド、プロパティ、メソッドとともに説明しています。他のモデルとのリレーションシップはハイパーリンクとして表示されます。説明はフィールドの 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,
        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に書いておくと便利な内容は以下のようなものです:

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

  • 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 に設定している必要があります。

Back to Top