Djangoフレームワーク組込みのドキュメントジェネレータ(django.contrib.admindocs)の紹介

この記事は Django Advent Calendar 2017 の6日目の記事です。

tell-kさんの記事 を読んでいて、「そういえばDjangoには組込みのドキュメントジェネレータがあるんで紹介しておこう」と思ったので書くことにしました。

タイトルの通り、 django.contrib.admindocs の紹介です。

Djangoフレームワークの黎明期からこの機能は存在してます。ドキュメントもあります。

The Django admin documentation generator | Django documentation | Django

使い方

  1. settings.pyのINSTALLED_APPSに django.contrib.admindocs を追加する。(django.contrib.adminも必要です)
  2. ROOT_URLCONFで指定されているurls.pyに url(r'^admin/doc/', include('django.contrib.admindocs.urls')), を追加する。(このとき url(r'^admin/', admin.site.urls) よりも前に書いておくことに注意する)
  3. 依存モジュールのdocutilsをインストールしておく。
  4. runserverを起動して、Djangoの管理サイトにログインし、右上のメニューに『ドキュメント』リンクがあるのでクリックで移動

動作例

admindocsでは、有効になっているDjangoのタグやフィルター、モデル、ビュー定義が一覧され、docstringなどの説明を参照できます。

f:id:nullpobug:20171206030638p:plain
ドキュメントのトップ

たとえば以下のモデルだとこんな感じ。Django2.0で試しました。

django-example-todo/models.py at master · tokibito/django-example-todo · GitHub

from django.db import models

# Create your models here.
class Todo(models.Model):
    """
    TODOのデータを扱うモデルクラス
    このクラスのインスタンス1つが、データベース上の1レコードに相当します
    """
    name = models.CharField("名称", max_length=50)
    done = models.BooleanField("完了")
    created_at = models.DateTimeField("作成日時", auto_now_add=True)

    def __str__(self):
        return self.name

f:id:nullpobug:20171206025819p:plain
モデルのドキュメント詳細

簡易なものですが、使える場面があるかもしれません。