Djangoに標準で付属する、admindocsという公式のドキュメンテーションツールの紹介です。
少しの設定追加でDjangoの管理サイトに一部のコードに関するドキュメントを生成してくれます。
動作確認バージョン
- Python: 3.12.1
- Django: 5.0
※admindocsの機能自体は、Django1.x系の頃から存在しているようです。
少なくともDjango1.8のドキュメントには記載があります。
生成されるページ例
ページのヘッダー部分にドキュメントというリンクが追加されています。このリンクで、管理サイトの各ページからドキュメントページにアクセスできます。
スクショにある通り、admindocsでは以下の要素についてドキュメントを生成してくれます。
- テンプレートタグ
- テンプレートフィルタ
- モデル
- ビュー
一番下にあるブックマークレットは、Djangoアプリケーションのページから、対応するビューのドキュメントページに遷移できる機能を持つブックマークレットです。
モデルのドキュメントページ例
モデル以外の3つ（テンプレートタグ、テンプレートフィルタ、ビュー）に関しては、各定義クラスや関数のdocstringを抽出して一覧化してくれます。
モデルに関しては、モデルクラスのdocstringの他、各フィールドの情報を自動で表形式にしてくれます。
以下はモデルクラスのサンプルと、そこから生成されるドキュメントです。
class Author(models.Model):
""" 著者情報
.. reStructuredTextでdocstringを書くことで、admindocs上でレンダリングされます。
* この `Author` クラスは、著者情報を管理するモデルです。
* 説明~~~~~~~~~~~~
* 説明~~~~~~~~~~~~
"""
name = models.CharField(max_length=64, unique=True, help_text="名前")
country = models.ForeignKey(Country, on_delete=models.SET_NULL, help_text="国", null=True)
birthday = models.DateField(help_text="誕生日")
death_day = models.DateField(help_text="死亡日", null=True, blank=True)
@property
def is_alive(self):
"""存命かどうかを返す
::
author = Author(name="夏目漱石", birthday=date(1867, 2, 9), death_day=date(1916, 12, 9))
author.is_alive # False
"""
return self.death_day is None
class Book(models.Model):
"""書籍情報"""
name = models.CharField(max_length=64, unique=True, help_text="名前")
author = models.ForeignKey(Author, on_delete=models.SET_NULL, help_text="著者", null=True)
以下は、上記のAuthorモデルから生成されるドキュメントです。
各フィールドについて、名前、型、help_textを取得し、表にまとめてくれています。
@propertyで定義したフィールドや、またAuthorモデルを参照しているBookモデルへの逆参照のためのフィールドについても載せてくれています。
設定方法
設定方法はドキュメントに記載があります
-
settings.pyのINSTALLED_APPSに以下を追加"django.contrib.admindocs"
- urls.pyに以下を追加
path('admin/doc/', include('django.contrib.admindocs.urls'))-
/adminより前に定義する必要がある
- docutilsパッケージ（0.19以上）をインストール
ブックマークレット機能を使う場合はさらに以下を設定
-
settings.pyのMIDDLEWAREに以下を追加django.contrib.admindocs.middleware.XViewMiddleware
なお、ドキュメントには記載がないですが、コードブロック記法を使う場合はPygmentsのインストールが必要です。
Pygmentsは構文解析のライブラリですが、これを入れても少なくともデフォルトではシンタックスハイライトはされないようです。
(adminページのCSS設定次第ではシンタックスハイライトされるんだろうか……？)
まとめ
admindocsは少ない手間でドキュメント生成ができる便利なツールですが、そのわりに知名度が低そうなので、紹介の記事を書いてみました。
ドキュメンテーションがしっかりしているプロジェクトではあまり恩恵がないかもしれませんが、個人開発など小規模な開発ではadmindocsで済む場合もあるかもしれません。