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.22+ パッケージをインストールします。
オプション: admindocs ブックマークレットを使うには django.contrib.admindocs.middleware.XViewMiddleware がインストールされている必要があります。
これらの手順が完了したら、管理インターフェイスに移動し、ページの右上にある "ドキュメント" リンクをクリックすれば、ドキュメントを読むことができます。
\n以下の特別なマークアップをdocstringで使用することで、他のコンポーネントへのハイパーリンクを簡単に作成できます:
\nDjango コンポーネント | \nreStructuredText のロール | \n
|---|---|
モデル | \n
| \n
ビュー | \n
| \n
テンプレートタグ | \n
| \n
テンプレートフィルタ | \n
| \n
テンプレート | \n
| \n
これらはすべて、 :role:`link text <link>` の形式でカスタムリンクテキストをサポートしています。たとえば、 :tag:`block <built_in-block>` のように記述します。
admindocs ページの models セクションでは、ユーザーがアクセス可能な各モデルについて、そのすべてのフィールド、プロパティ、メソッドとともに説明されます。他のモデルとのリレーションはハイパーリンクとして表示されます。説明文は、フィールドの help_text 属性や、モデルメソッドの docstring から取得されます。
役に立つドキュメントを持ったモデルは次のようなものです:
\nclass BlogEntry(models.Model):\n """\n Stores a single blog entry, related to :model:`blog.Blog` and\n :model:`auth.User`.\n """\n\n slug = models.SlugField(help_text="A short label, generally used in URLs.")\n author = models.ForeignKey(\n User,\n models.SET_NULL,\n blank=True,\n null=True,\n )\n blog = models.ForeignKey(Blog, models.CASCADE)\n ...\n\n def publish(self):\n """Makes the blog entry live on the site."""\n ...\nサイト内の各URLは admindocs ページに個別のエントリーがあり、指定したURLをクリックすると対応するビューが表示されます。ビュー関数のdocstringに書いておくと便利な内容は以下のようなものです:
ビューが何をするのかについての短い説明。
context 、あるいはビューのテンプレートで使用可能な変数のリスト。
そのビューで使用されるテンプレート名。
例:
\nfrom django.shortcuts import render\n\nfrom myapp.models import MyModel\n\n\ndef my_view(request, slug):\n """\n Display an individual :model:`myapp.MyModel`.\n\n **Context**\n\n ``mymodel``\n An instance of :model:`myapp.MyModel`.\n\n **Template:**\n\n :template:`myapp/my_template.html`\n """\n context = {"mymodel": MyModel.objects.get(slug=slug)}\n return render(request, "myapp/my_template.html", context)\nadmindocs にはテンプレートそのものをドキュメント化する場所はありませんが、 docstring の中で :template:`path/to/template.html` 構文を使うと、結果のページは Django の テンプレート ローダ を使ってテンプレートのパスを確認します。これは、指定されたテンプレートが存在するかどうかを確認し、そのテンプレートがファイルシステム上のどこに保存されているかを表示する便利な方法です。
1 つのブックマークレットが admindocs ページから利用できます:
各ページから、ページを生成したビューのドキュメントにジャンプします。
\nこのブックマークレットを使用するには、 XViewMiddleware がインストールされ、 User として Django admin にログインし、 is_staff を True に設定している必要があります。