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 のロール |
|---|---|
モデル |
|
ビュー |
|
テンプレートタグ |
|
テンプレートフィルタ |
|
テンプレート |
|
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 にはテンプレートそのものをドキュメント化する場所はありませんが、 docstring の中で :template:`path/to/template.html` 構文を使うと、結果のページは Django の テンプレート ローダ を使ってテンプレートのパスを確認します。これは、指定されたテンプレートが存在するかどうかを確認し、そのテンプレートがファイルシステム上のどこに保存されているかを表示する便利な方法です。
1 つのブックマークレットが admindocs ページから利用できます:
各ページから、ページを生成したビューのドキュメントにジャンプします。
このブックマークレットを使用するには、 XViewMiddleware がインストールされ、 User として Django admin にログインし、 is_staff を True に設定している必要があります。
4月 02, 2025