docs: Add Context API reference docs

docs/api/context.md

@@ -0,0 +1,11 @@
+# `Context` class
+
+This page documents the `Context` class of FluxQueue.
+
+You can import the `Context` class from `fluxqueue`:
+
+```python
+from fluxqueue import Context
+```
+
+::: fluxqueue.Context

docs/api/fluxqueue.md

@@ -10,5 +10,3 @@ from fluxqueue import FluxQueue
 ```
 
 ::: fluxqueue.FluxQueue
-options:
-members: - task

docs/api/models.md

@@ -0,0 +1,5 @@
+# Models
+
+This page documents the models of FluxQueue.
+
+::: fluxqueue.TaskMetadata

docs/index.md

@@ -15,6 +15,7 @@ Welcome to FluxQueue documentation. FluxQueue is a lightweight, resource-efficie
 - [Worker Setup](tutorial/worker.md) - Deploy and run workers
 - [How it Works](how-it-works/index.md) - Learn more about how FluxQueue actually works
 - [Examples](examples/index.md) - FluxQueue examples with **Flask**, **Django**, **FastAPI**
+- [Features](features/index.md) - Features of FluxQueue
 - [API Reference](api/index.md) - Complete API documentation
 
 ## What is FluxQueue?

mkdocs.yml

@@ -81,6 +81,8 @@ nav:
   - API Reference:
       - api/index.md
       - api/fluxqueue.md
+      - api/context.md
+      - api/models.md
       - api/environment.md
   - About: about.md
   - Release Notes: release-notes.md

python/fluxqueue/client.py

@@ -108,7 +108,7 @@ def task_with_context(
         part of the function's public signature - users calling the function do not need to provide it.
 
         Parameters
-        ----------
+        ---
         `name`:
             Optional explicit task name. If not set, a name is derived from the
             function name.
@@ -120,10 +120,20 @@ def task_with_context(
             Maximum number of retries the worker will attempt for this task
             before treating it as dead.
 
-        Example
+        Example: Subclassing Context for Database Resource Pooling
         ---
+        This example demonstrates how to use `thread_storage` to persist a
+        SQLAlchemy engine across the lifetime of a worker thread. This pattern
+        prevents the overhead of recreating database connection pools for
+        every individual task execution.
 
         ```py
+        from fluxqueue import FluxQueue, Context
+        from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
+        from contextlib import asynccontextmanager
+
+        fluxqueue = FluxQueue()
+
         class DbContext(Context):
             def __init__(self) -> None:
                 super().__init__()
@@ -148,15 +158,13 @@ async def session_context(self):
                         await session.rollback()
                         raise
 
-
         @fluxqueue.task_with_context()
         async def create_user_task(ctx: DbContext, email: str, username: str):
             async with ctx.session_context() as db_session:
                 user = User(email=email, username=username)
                 db_session.add(user)
 
-
-        await create_user_task
+        await create_user_task(email, username)
         ```
         """