Add inline field docstrings to model doc

- Analyze model to get all attribute docstrings
- Append the inline docstring of fields to their param documentation of the model

Author: timobrembeck

CHANGES.rst

@@ -4,6 +4,7 @@ Changelog
 UNRELEASED
 ----------
 
+* Add inline docstrings of model fields to parameter documentation of models
 * Add support for Python 3.11
 * Add support for Django 4.1
 * Drop support for Django 2.2

sphinxcontrib_django2/docstrings/classes.py

@@ -4,6 +4,7 @@
 
 from django import forms
 from django.db import models
+from sphinx.pycode import ModuleAnalyzer
 
 from .field_utils import get_field_type, get_field_verbose_name
 
@@ -81,22 +82,30 @@ def improve_model_docstring(app, model, lines):
         if field not in related_fields + reverse_related_fields
     ]
 
+    # Analyze model to get inline field docstrings
+    analyzer = ModuleAnalyzer.for_module(model.__module__)
+    analyzer.analyze()
+    field_docs = {
+        field_name: ". " + " ".join(field_docstring).strip()
+        for (_, field_name), field_docstring in analyzer.attr_docs.items()
+    }
+
     # Add the normal fields to the docstring
-    add_model_parameters(non_related_fields, lines)
+    add_model_parameters(non_related_fields, lines, field_docs)
 
     # Add the related fields
     if related_fields:
         lines.append("")
         lines.append("Relationship fields:")
         lines.append("")
-        add_model_parameters(related_fields, lines)
+        add_model_parameters(related_fields, lines, field_docs)
 
     # Add the reverse related fields
     if reverse_related_fields:
         lines.append("")
         lines.append("Reverse relationships:")
         lines.append("")
-        add_model_parameters(reverse_related_fields, lines)
+        add_model_parameters(reverse_related_fields, lines, field_docs)
 
     # Add the inheritance diagram
     if (
@@ -107,7 +116,7 @@ def improve_model_docstring(app, model, lines):
         lines.append(".. inheritance-diagram::")  # pragma: no cover
 
 
-def add_model_parameters(fields, lines):
+def add_model_parameters(fields, lines, field_docs):
     """
     Add the given fields as model parameter with the ``:param:`` directive
 
@@ -116,10 +125,14 @@ def add_model_parameters(fields, lines):
 
     :param lines: The list of current docstring lines
     :type lines: list [ str ]
+
+    :param field_docs: The attribute docstrings of the model
+    :type field_docs: dict
     """
     for field in fields:
-        # Add verbose name
-        lines.append(f":param {field.name}: {get_field_verbose_name(field)}")
+        # Add docstrings if they are found
+        docstring = field_docs.get(field.name, "")
+        lines.append(f":param {field.name}: {get_field_verbose_name(field)}{docstring}")
 
         # Add type
         lines.append(f":type {field.name}: {get_field_type(field, include_role=False)}")

tests/test_class_docstrings.py

@@ -12,21 +12,25 @@ def test_simple_model(app, do_autodoc):
         "",
         "   :param id: Primary key: ID",
         "   :type id: ~django.db.models.AutoField",
-        "   :param dummy_field: Very verbose name of dummy field. This should help you",
+        "   :param dummy_field: Very verbose name of dummy field. "
+        "This should help you. Docstring of char field",
         "   :type dummy_field: ~django.db.models.CharField",
         "",
         "   Relationship fields:",
         "",
         "   :param file: File "
-        "(related name: :attr:`~dummy_django_app.models.FileModel.simple_models`)",
+        "(related name: :attr:`~dummy_django_app.models.FileModel.simple_models`). "
+        "Docstring of foreign key",
         "   :type file: :class:`~django.db.models.ForeignKey` to "
         ":class:`~dummy_django_app.models.FileModel`",
         "   :param childA: ChildA "
-        "(related name: :attr:`~dummy_django_app.models.ChildModelA.simple_model`)",
+        "(related name: :attr:`~dummy_django_app.models.ChildModelA.simple_model`). "
+        "Docstring of one to one field",
         "   :type childA: :class:`~django.db.models.OneToOneField` to "
         ":class:`~dummy_django_app.models.ChildModelA`",
         "   :param childrenB: ChildrenB "
-        "(related name: :attr:`~dummy_django_app.models.ChildModelB.simple_models`)",
+        "(related name: :attr:`~dummy_django_app.models.ChildModelB.simple_models`). "
+        "Docstring of many to many field",
         "   :type childrenB: :class:`~django.db.models.ManyToManyField` to "
         ":class:`~dummy_django_app.models.ChildModelB`",
         "",
@@ -59,21 +63,25 @@ def test_database_table(app, do_autodoc):
         "",
         "   :param id: Primary key: ID",
         "   :type id: ~django.db.models.AutoField",
-        "   :param dummy_field: Very verbose name of dummy field. This should help you",
+        "   :param dummy_field: Very verbose name of dummy field. "
+        "This should help you. Docstring of char field",
         "   :type dummy_field: ~django.db.models.CharField",
         "",
         "   Relationship fields:",
         "",
         "   :param file: File "
-        "(related name: :attr:`~dummy_django_app.models.FileModel.simple_models`)",
+        "(related name: :attr:`~dummy_django_app.models.FileModel.simple_models`). "
+        "Docstring of foreign key",
         "   :type file: :class:`~django.db.models.ForeignKey` to "
         ":class:`~dummy_django_app.models.FileModel`",
         "   :param childA: ChildA "
-        "(related name: :attr:`~dummy_django_app.models.ChildModelA.simple_model`)",
+        "(related name: :attr:`~dummy_django_app.models.ChildModelA.simple_model`). "
+        "Docstring of one to one field",
         "   :type childA: :class:`~django.db.models.OneToOneField` to "
         ":class:`~dummy_django_app.models.ChildModelA`",
         "   :param childrenB: ChildrenB "
-        "(related name: :attr:`~dummy_django_app.models.ChildModelB.simple_models`)",
+        "(related name: :attr:`~dummy_django_app.models.ChildModelB.simple_models`). "
+        "Docstring of many to many field",
         "   :type childrenB: :class:`~django.db.models.ManyToManyField` to "
         ":class:`~dummy_django_app.models.ChildModelB`",
         "",