adds sphinx module for handling pydantic models

aim/digifeeds/database/schemas.py

@@ -1,9 +1,16 @@
 """Digifeeds Pydantic Models"""
+
 from pydantic import BaseModel, Field, ConfigDict
 from datetime import datetime
 
 
 class ItemStatus(BaseModel):
+    """
+    Model of an individual ItemStatus. it includes the name,
+    description, and creation date of the status for a given item. It is used
+    for listing the statuses for a given Item.
+    """
+
     name: str = Field(alias="status_name")
     description: str = Field(alias="status_description")
     created_at: datetime
@@ -12,12 +19,23 @@ class ItemStatus(BaseModel):
 
 
 class ItemBase(BaseModel):
+    """
+    Model of the most basic Item. One that only has a barcode. It's
+    used as the base for a full Item listing, and for Item creation where
+    barcode is the only necessary attribute.
+    """
+
     model_config = ConfigDict(populate_by_name=True, from_attributes=True)
 
     barcode: str = Field(alias="item_barcode")
 
 
 class Item(ItemBase):
+    """
+    Model for the full listing of an item. It inherits from ItemBase
+    which only has a barcode.
+    """
+
     created_at: datetime
     statuses: list[ItemStatus] = []
     model_config = ConfigDict(
@@ -39,8 +57,12 @@ class Item(ItemBase):
     )
 
 
-
 class ItemCreate(ItemBase):
+    """
+    Model for Item creation. Only a Barcode is needed for creating an
+    item, so it is identical to ItemBase
+    """
+
     pass
 
 
@@ -67,6 +89,7 @@ class Response400(Response):
         }
     )
 
+
 class Response404(Response):
     model_config = ConfigDict(
         json_schema_extra={

docs/conf.py

@@ -22,9 +22,11 @@
     "myst_parser",
     "sphinxcontrib.mermaid",
     "sphinx_toolbox.more_autodoc.autonamedtuple",
+    "sphinxcontrib.autodoc_pydantic",
 ]
 autodoc_mock_imports = ["sqlalchemy"]
 autosummary_generate = True
+autodoc_pydantic_model_show_config_summary = False
 
 mermaid_d3_zoom = True
 mermaid_version = "11.3.0"

pyproject.toml

@@ -35,6 +35,7 @@ sphinx-autobuild = "^2024.10.3"
 myst-parser = "^4.0.0"
 sphinxcontrib-mermaid = "^0.9.2"
 sphinx-toolbox = "^3.8.1"
+autodoc-pydantic = "^2.2.0"
 
 
 [tool.pytest.ini_options]