使用admindocs在Django项目中自动生成文档

这是有关Django自带的官方文档工具admindocs的介绍。

通过添加少量设置，Django管理站点可以自动生成关于部分代码的文档。

确认版本动作

• Python: 3.12.1

Django: 5.0

生成的页面示例

在页面的标题部分添加了一个名为“文档”的链接。通过这个链接，您可以从管理网站的每个页面访问文档页面。

如同截图所示，admindocs会为以下元素生成文档。

• テンプレートタグ

• テンプレートフィルタ

• モデル

ビュー

底部的书签是一个可以从Django应用程序的页面跳转到相应视图文档页面的书签工具。

模型文件页面示例

除了模型（Model）之外的三个部分（模板标签，模板过滤器，视图），会将每个定义的类和函数的文档字符串提取并汇总成列表。
而对于模型（Model），除了提取模型类的文档字符串之外，还会自动将每个字段的信息转换为表格形式。

以下是模型类的示例以及生成的文档。

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)

对于每个字段，它会获取名称、类型和help_text，并将它们整理在表中。
它还会包括使用@property定义的字段以及对Book模型进行反向引用的字段，它们引用了Author模型。

设置程序

在文件中有设置的说明。

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是一个用于语法分析的库，但即使安装了它，至少在默认情况下似乎不会进行语法高亮显示。
（取决于管理员页面的CSS设置，可能会进行语法高亮显示吗……？）

总结

由于admindocs被认为知名度较低，且能够以较少的工作量生成文档，因此我写了一篇介绍文章。尽管在文档齐全的项目中可能不会有太多好处，但在个人开发或小规模开发中，可能有时候可以使用admindocs来完成需求。