Add comprehensive documentation with mkdocs-material and GitHub Pages deployment

.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+      - staging
+      - develop
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # Fetch all history for mike versioning
+
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[docs]"
+
+      - name: Deploy documentation (main branch)
+        if: github.ref == 'refs/heads/main'
+        run: |
+          mike deploy --push --update-aliases latest stable
+          mike set-default --push latest
+
+      - name: Deploy documentation (staging branch)
+        if: github.ref == 'refs/heads/staging'
+        run: |
+          mike deploy --push staging
+
+      - name: Deploy documentation (develop branch)
+        if: github.ref == 'refs/heads/develop'
+        run: |
+          mike deploy --push dev
+
+      - name: Deploy documentation (version tag)
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          mike deploy --push --update-aliases $VERSION stable
+          mike set-default --push $VERSION

docs/api-reference/client.md

@@ -0,0 +1,58 @@
+# Client API Reference
+
+Complete API reference for the `TMOClient` class.
+
+## TMOClient
+
+```python
+class TMOClient:
+    def __init__(
+        self,
+        token: str,
+        database: str,
+        environment: Union[Environment, str] = Environment.US,
+        timeout: int = 30,
+        debug: bool = False
+    )
+```
+
+### Parameters
+
+- **token** (`str`): Your API token from The Mortgage Office  
+- **database** (`str`): Your database name
+- **environment** (`Union[Environment, str]`): API environment or custom URL (default: `Environment.US`)
+- **timeout** (`int`): Request timeout in seconds (default: 30)
+- **debug** (`bool`): Enable debug logging (default: False)
+
+### Shares Resource Attributes
+
+- **shares_pools**: `PoolsResource` - Shares pool operations
+- **shares_partners**: `PartnersResource` - Shares partner operations
+- **shares_distributions**: `DistributionsResource` - Shares distribution operations
+- **shares_certificates**: `CertificatesResource` - Shares certificate operations
+- **shares_history**: `HistoryResource` - Shares history operations
+
+### Capital Resource Attributes
+
+- **capital_pools**: `PoolsResource` - Capital pool operations
+- **capital_partners**: `PartnersResource` - Capital partner operations
+- **capital_distributions**: `DistributionsResource` - Capital distribution operations
+- **capital_history**: `HistoryResource` - Capital history operations
+
+### Methods
+
+#### get(endpoint: str, params: Optional[Dict[str, Any]] = None) → Dict[str, Any]
+
+Make a GET request.
+
+#### post(endpoint: str, json: Optional[Dict[str, Any]] = None) → Dict[str, Any]
+
+Make a POST request.
+
+#### put(endpoint: str, json: Optional[Dict[str, Any]] = None) → Dict[str, Any]
+
+Make a PUT request.
+
+#### delete(endpoint: str) → Dict[str, Any]
+
+Make a DELETE request.

docs/api-reference/exceptions.md

@@ -0,0 +1,123 @@
+# Exceptions API Reference
+
+## TMOException
+
+Base exception for all TMO API errors.
+
+```python
+class TMOException(Exception):
+    def __init__(
+        self,
+        message: str,
+        error_number: Optional[int] = None
+    )
+```
+
+**Attributes:**
+- `message` (str): The error message
+- `error_number` (Optional[int]): TMO API error number if available
+
+## AuthenticationError
+
+Raised for authentication failures (401/403).
+
+```python
+class AuthenticationError(TMOException):
+    pass
+```
+
+**Usage:**
+```python
+from tmo_api import TMOClient, AuthenticationError
+
+try:
+    client = TMOClient(token="invalid", database="test")
+    pools = client.shares_pools.list_all()
+except AuthenticationError as e:
+    print(f"Authentication failed: {e.message}")
+    if e.error_number:
+        print(f"Error number: {e.error_number}")
+```
+
+## APIError
+
+Raised when the API returns an error response.
+
+```python
+class APIError(TMOException):
+    pass
+```
+
+**Usage:**
+```python
+from tmo_api import TMOClient, APIError
+
+try:
+    client = TMOClient(token="token", database="db")
+    pool = client.shares_pools.get_pool("INVALID")
+except APIError as e:
+    print(f"API error: {e.message}")
+    if e.error_number:
+        print(f"Error number: {e.error_number}")
+```
+
+## ValidationError
+
+Raised for client-side validation errors before making API calls.
+
+```python
+class ValidationError(TMOException):
+    pass
+```
+
+**Usage:**
+```python
+from tmo_api import TMOClient, ValidationError
+
+try:
+    client = TMOClient(token="token", database="db")
+    pool = client.shares_pools.get_pool("")  # Empty account
+except ValidationError as e:
+    print(f"Validation error: {e.message}")
+```
+
+## NetworkError
+
+Raised for network/connection errors (timeouts, connection failures).
+
+```python
+class NetworkError(TMOException):
+    pass
+```
+
+**Usage:**
+```python
+from tmo_api import TMOClient, NetworkError
+
+try:
+    client = TMOClient(token="token", database="db", timeout=1)
+    pools = client.shares_pools.list_all()
+except NetworkError as e:
+    print(f"Network error: {e.message}")
+```
+
+## Catching All Exceptions
+
+You can catch all TMO API exceptions using the base class:
+
+```python
+import os
+from tmo_api import TMOClient, TMOException
+
+client = TMOClient(
+    token=os.environ["TMO_API_TOKEN"],
+    database=os.environ["TMO_DATABASE"]
+)
+
+try:
+    pools = client.shares_pools.list_all()
+except TMOException as e:
+    print(f"TMO API error: {e.message}")
+    if hasattr(e, 'error_number') and e.error_number:
+        print(f"Error number: {e.error_number}")
+```

docs/api-reference/models.md

@@ -0,0 +1,73 @@
+# Models API Reference
+
+## BaseModel
+
+Base class for all data models.
+
+```python
+class BaseModel:
+    rec_id: Optional[int]
+```
+
+## Pool
+
+Represents a mortgage pool.
+
+```python
+class Pool(BaseModel):
+    Account: Optional[str]
+    Name: Optional[str]
+    InceptionDate: Optional[datetime]
+    LastEvaluation: Optional[datetime]
+    SysTimeStamp: Optional[datetime]
+    OtherAssets: List[OtherAsset]
+    OtherLiabilities: List[OtherLiability]
+```
+
+## OtherAsset
+
+Represents an asset in a pool.
+
+```python
+class OtherAsset(BaseModel):
+    Description: Optional[str]
+    Value: Optional[float]
+    DateLastEvaluated: Optional[datetime]
+```
+
+## OtherLiability
+
+Represents a liability in a pool.
+
+```python
+class OtherLiability(BaseModel):
+    Description: Optional[str]
+    Amount: Optional[float]
+    MaturityDate: Optional[datetime]
+    PaymentNextDue: Optional[datetime]
+```
+
+## Response Models
+
+### BaseResponse
+
+```python
+class BaseResponse:
+    status: Optional[int]
+    message: Optional[str]
+    data: Any
+```
+
+### PoolResponse
+
+```python
+class PoolResponse(BaseResponse):
+    pool: Optional[Pool]
+```
+
+### PoolsResponse
+
+```python
+class PoolsResponse(BaseResponse):
+    pools: List[Pool]
+```

docs/api-reference/resources.md

@@ -0,0 +1,65 @@
+# Resources API Reference
+
+## PoolsResource
+
+```python
+class PoolsResource:
+    def get_pool(self, account: str) -> Pool
+    def list_all(self) -> List[Pool]
+    def get_pool_partners(self, account: str) -> list
+    def get_pool_loans(self, account: str) -> list
+    def get_pool_bank_accounts(self, account: str) -> list
+    def get_pool_attachments(self, account: str) -> list
+```
+
+## PartnersResource
+
+```python
+class PartnersResource:
+    def get_partner(self, account: str) -> dict
+    def get_partner_attachments(self, account: str) -> list
+    def list_all(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None
+    ) -> list
+```
+
+## DistributionsResource
+
+```python
+class DistributionsResource:
+    def get_distribution(self, rec_id: str) -> dict
+    def list_all(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        pool_account: Optional[str] = None
+    ) -> list
+```
+
+## CertificatesResource
+
+```python
+class CertificatesResource:
+    def get_certificates(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        partner_account: Optional[str] = None,
+        pool_account: Optional[str] = None
+    ) -> list
+```
+
+## HistoryResource
+
+```python
+class HistoryResource:
+    def get_history(
+        self,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        partner_account: Optional[str] = None,
+        pool_account: Optional[str] = None
+    ) -> list
+```