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