docs: add mkdocs documentation site configuration

.github/workflows/deploy-docs.yml

@@ -0,0 +1,39 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches:
+      - master
+      - main
+    paths:
+      - 'README.md'
+      - '*/README.md'
+      - 'mkdocs.yml'
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yml'
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs mkdocs-material
+
+      - name: Build documentation
+        run: |
+          bash build-docs.sh
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

.gitignore

@@ -1 +1,3 @@
 *.pyc
+docs/
+site/

README.md

@@ -1,9 +1,143 @@
-django-htk
-==========
+# HTK: Django Hacktoolkit
 
-A set of apps, utilities, middlewares, etc for Django
+A comprehensive Django framework providing reusable apps, utilities, and third-party integrations for rapid development. Designed for hackathons and production applications.
 
-Used/embedded in <https://github.com/hacktoolkit/htk-django-skeleton
+## Overview
 
-Author: Jonathan Tsai <https://github.com/jontsai>
-License: MIT
+HTK includes:
+
+- **[Reusable Django Apps](./apps/)** - Pre-built apps for accounts, organizations, payments, messaging, and more
+- **[Third-Party Integrations](./lib/)** - Ready-to-use connectors for 45+ external services (Stripe, Google, AWS, Slack, etc.)
+- **[Utility Modules](./utils/)** - Common patterns for caching, text processing, APIs, and data handling
+- **[API Helpers](./api/)** - Tools for building REST APIs with DataTables support
+- **[Form Utilities](./forms/)** - Base form classes and validators
+- **[Decorators](./decorators/)** - Django and function decorators for common tasks
+- **[Models & Fields](./models/)** - Abstract models and custom Django fields
+- **[Middleware](./middleware/)** - Request/response processing utilities
+
+## Quick Start
+
+### Using HTK Apps
+
+HTK provides pre-built Django apps that can be installed and configured in your project:
+
+```python
+# settings.py
+INSTALLED_APPS = [
+    'htk.apps.accounts',
+    'htk.apps.organizations',
+    'htk.apps.stripe_lib',
+    # ... more apps
+]
+```
+
+### Common Patterns
+
+**Caching objects:**
+```python
+from htk.cache.classes import CacheableObject
+
+class UserFollowingCache(CacheableObject):
+    def get_cache_key_suffix(self):
+        return f'user_{self.user_id}_following'
+```
+
+**User authentication:**
+```python
+from htk.apps.accounts.backends import HtkUserTokenAuthBackend
+from htk.apps.accounts.utils.auth import login_authenticated_user
+```
+
+**API endpoints:**
+```python
+from htk.api.utils import json_response_form_error, get_object_or_json_error
+```
+
+## Key Features
+
+### Accounts & Authentication
+- User registration and email verification
+- Social authentication backends (OAuth2 support)
+- User profiles and email management
+- Token-based authentication
+
+### Payments & Billing
+- Stripe integration (customers, subscriptions, charges)
+- Quote/Invoice system (CPQ)
+- Payment tracking and history
+
+### Organizations
+- Multi-org support with roles and permissions
+- Org invitations and member management
+- Permission-based access control
+
+### Messaging & Notifications
+- Email notifications
+- Slack integration
+- Conversation/threading support
+
+### Utilities
+- Text processing (formatting, translation, sanitization)
+- Caching decorators and schemes
+- CSV/PDF generation
+- QR codes
+- Geolocation and distance calculations
+- Timezone handling
+
+### Third-Party Services
+See [lib/README.md](./lib/) for details on 45+ integrations including:
+- Cloud: AWS S3, Google Cloud
+- Communication: Slack, Discord, Gmail, Twilio
+- Data: Airtable, Stripe, Shopify, Zuora
+- Analytics: Iterable, Mixpanel
+- Location: Google Maps, Mapbox, Zillow
+- Search: Elasticsearch integration patterns
+
+## Project Structure
+
+```
+htk/
+├── apps/              # Pre-built Django apps
+├── lib/               # Third-party service integrations
+├── utils/             # Common utilities and helpers
+├── models/            # Abstract models and field types
+├── forms/             # Base form classes
+├── api/               # REST API utilities
+├── decorators/        # Function and class decorators
+├── middleware/        # Request/response processing
+├── cache/             # Caching framework
+├── constants/         # Project-wide constants
+├── extensions/        # Django extensions
+├── templates/         # Reusable templates
+└── templatetags/      # Custom template filters and tags
+```
+
+## Module Documentation
+
+For detailed information about each module, see:
+
+- **[Apps](./apps/README.md)** - Reusable Django application packages
+- **[Libraries](./lib/README.md)** - Third-party service integrations
+- **[Utilities](./utils/README.md)** - Helper functions and utilities
+- **[API](./api/README.md)** - REST API patterns and tools
+- **[Cache](./cache/README.md)** - Caching framework and patterns
+- **[Forms](./forms/README.md)** - Form utilities and base classes
+- **[Decorators](./decorators/README.md)** - Function and class decorators
+- **[Models](./models/README.md)** - Abstract models and custom fields
+- **[Validators](./validators/README.md)** - Validation utilities
+
+## Use Cases
+
+**Hackathons:** Rapidly build production-quality features with pre-built apps and integrations.
+
+**SaaS Applications:** Multi-organization support, billing, and user management out of the box.
+
+**E-commerce:** Stripe payments, inventory management, order processing.
+
+**Content Platforms:** User accounts, organizations, messaging, notifications.
+
+**Marketplaces:** Payment processing, user profiles, organization support.
+
+## Contributing
+
+HTK is designed to be extended. Create custom apps that inherit from abstract base classes and add your own business logic.

admin/README.md

@@ -0,0 +1,43 @@
+# Django Admin Utilities
+
+Custom admin display and customization utilities.
+
+## Quick Start
+
+```python
+from htk.admin.decorators import django_admin_bool_field
+
+@django_admin_bool_field('is_active')
+def is_active_display(obj):
+    return obj.is_active
+is_active_display.short_description = 'Active'
+
+class UserAdmin(admin.ModelAdmin):
+    list_display = ['username', is_active_display]
+```
+
+## Boolean Field Display
+
+Display boolean fields as green checkmarks or red X marks in admin list view:
+
+```python
+from htk.admin.decorators import django_admin_bool_field
+
+class ProductAdmin(admin.ModelAdmin):
+    list_display = ['name', is_available, is_featured]
+
+    @django_admin_bool_field('is_available')
+    def is_available(obj):
+        return obj.is_available
+
+    @django_admin_bool_field('is_featured')
+    def is_featured(obj):
+        return obj.is_featured
+```
+
+## Configuration
+
+```python
+# settings.py
+ADMIN_SITE_HEADER = 'My Admin'
+```

admintools/README.md

@@ -0,0 +1,83 @@
+# Admin Tools
+
+Advanced admin functionality including user impersonation and company user management.
+
+## Quick Start
+
+```python
+from htk.admintools.decorators import company_officer_required, company_employee_required
+from htk.admintools.utils import is_allowed_to_emulate_users, request_emulate_user
+
+# Protect views for company officers
+@company_officer_required
+def officer_dashboard(request):
+    return render(request, 'officer_dashboard.html')
+
+# Protect views for company employees
+@company_employee_required
+def employee_portal(request):
+    return render(request, 'employee_portal.html')
+```
+
+## User Impersonation
+
+Allow admins to emulate other users for testing:
+
+```python
+from htk.admintools.utils import is_allowed_to_emulate_users, request_emulate_user
+
+# Check if user can emulate others
+if is_allowed_to_emulate_users(request.user):
+    # Allow user emulation in admin panel
+    pass
+
+# Emulate a specific user
+request_emulate_user(request, original_user, target_user)
+```
+
+## Company User Management
+
+Check company affiliation and roles:
+
+```python
+from htk.admintools.models import company_officer_required, is_company_officer, is_company_employee
+
+# Check officer status
+if is_company_officer(user):
+    # User is a company officer
+    pass
+
+# Check employee status
+if is_company_employee(user):
+    # User is a company employee
+    pass
+
+# Check email domain
+if user.has_company_email_domain():
+    # User has company email
+    pass
+```
+
+## Company Data Lookups
+
+Get mappings of company users:
+
+```python
+from htk.admintools.utils import get_company_officers_id_email_map, get_company_employees_id_email_map
+
+# Get officers mapping
+officers = get_company_officers_id_email_map()
+# Returns: {user_id: email, ...}
+
+# Get employees mapping
+employees = get_company_employees_id_email_map()
+# Returns: {user_id: email, ...}
+```
+
+## Configuration
+
+```python
+# settings.py
+# Enable company user features
+COMPANY_ADMIN_ENABLED = True
+```