Django管理ドキュメントジェネレーター—Djangoドキュメント
Django管理ドキュメントジェネレータ
Djangoの admindocs アプリは、:setting: `INSTALLED_APPS` 内の任意のアプリのモデル、ビュー、テンプレートタグ、テンプレートフィルターのドキュメント文字列からドキュメントを取得し、そのドキュメントを[X224X ] Django admin 。
概要
admindocs をアクティブ化するには、次の手順を実行する必要があります。
- django.contrib.admindocs を:setting: `INSTALLED_APPS` に追加します。
path('admin/doc/', include('django.contrib.admindocs.urls'))
をurlpatterns
に追加します。 before'admin/'
エントリが含まれていることを確認して、/admin/doc/
へのリクエストが後者のエントリによって処理されないようにします。- docutils Pythonモジュール( https://docutils.sourceforge.io/)をインストールします。
- オプション: 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
ページの models セクションでは、システム内の各モデルと、そのモデルで使用可能なすべてのフィールド、プロパティ、およびメソッドについて説明しています。 他のモデルとの関係はハイパーリンクとして表示されます。 説明は、フィールドのhelp_text
属性、またはモデルメソッドのdocstringから取得されます。
バージョン2.2で変更:古いバージョンではモデルのプロパティが表示されません。
有用なドキュメントを含むモデルは、次のようになります。
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 、またはビューのテンプレートで使用可能な変数のリスト。
- そのビューに使用される1つまたは複数のテンプレートの名前。
例えば:
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のテンプレートローダー[ X216X]。 これは、指定されたテンプレートが存在するかどうかを確認し、そのテンプレートがファイルシステムのどこに保存されているかを示すのに便利な方法です。
含まれているブックマークレット
admindocs
ページから1つのブックマークレットを入手できます。
- このページのドキュメント
- 任意のページから、そのページを生成するビューのドキュメントにジャンプします。
このブックマークレットを使用するには、XViewMiddleware
がインストールされ、 is_staff がTrue
。