# Django 6.0.7 ドキュメント

# 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.22+ パッケージをインストールします。

- オプション: 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``

これらはすべて、 `:role:`link text <link>`` の形式でカスタムリンクテキストをサポートしています。たとえば、 `:tag:`block <built_in-block>`` のように記述します。

## モデルのリファレンス

`admindocs` ページの models セクションでは、ユーザーがアクセス可能な各モデルについて、そのすべてのフィールド、プロパティ、メソッドとともに説明されます。他のモデルとのリレーションはハイパーリンクとして表示されます。説明文は、フィールドの `help_text` 属性や、モデルメソッドの docstring から取得されます。

役に立つドキュメントを持ったモデルは次のようなものです:

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