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/' のエントリで処理されないようにします。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に書いておくと便利な内容は以下のようなものです:
例:
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 に設定している必要があります。
8月 06, 2024