Fix sqlalchemy and pydantic docs

aim/digifeeds/database/models.py

@@ -15,6 +15,10 @@ class Base(DeclarativeBase):
 
 
 class Item(Base):
+    """
+    A representation of a digifeeds item. It has a barcode and statuses.
+    """
+
     __tablename__ = "items"
 
     barcode: Mapped[str] = mapped_column(String(256), unique=True, primary_key=True)
@@ -25,6 +29,10 @@ class Item(Base):
 
 
 class Status(Base):
+    """
+    A representation of a digifeeds status. It has a name and a description.
+    """
+
     __tablename__ = "statuses"
     id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
     name: Mapped[str] = mapped_column(String(256))
@@ -36,10 +44,16 @@ def __repr__(self):
 
 
 class ItemStatus(Base):
+    """
+    An association table for items and statuses. It includes the timestamp at
+    which the status for an item was created.
+    """
+
     __tablename__ = "item_statuses"
     id: Mapped[int] = mapped_column(primary_key=True, autoincrement=True)
     item_barcode: Mapped[int] = mapped_column(ForeignKey("items.barcode"))
     status_id: Mapped[int] = mapped_column(ForeignKey("statuses.id"))
+
     # https://docs.sqlalchemy.org/en/20/core/functions.html#sqlalchemy.sql.functions.now Tell the db to set the date.
     created_at: Mapped[datetime.datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now()
@@ -56,6 +70,12 @@ class ItemStatus(Base):
 
 
 def load_statuses(session: Session):
+    """
+    Takes the list of statuses in the function and loads them into the digifeeds database.
+
+    Args:
+        session (Session): A SqlAlchemy session object
+    """
     statuses = [
         {"name": "in_zephir", "description": "Item is in zephir"},
         {

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

@@ -14,9 +14,19 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = ["sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinx.ext.autosummary",
-              "sphinx.ext.autodoc", 'myst_parser', 'sphinxcontrib.mermaid', "sphinx_toolbox.more_autodoc.autonamedtuple"]
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.autodoc",
+    "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"
@@ -33,5 +43,5 @@
 html_theme_options = {
     "navigation_depth": 5,
     "collapse_navigation": False,
-    "titles_only": True
+    "titles_only": True,
 }