Skip to content

Commit 2bd8d5d

Browse files
YosefAshenaficlaude
YosefAshenafi
and
claude
committed
docs: add comprehensive README files across the codebase
Add 173 new README files automatically generated across the codebase: - Core modules: admin/, api/, cache/, decorators/, extensions/, forms/, middleware/, models/, utils/, validators/ - Django apps: accounts/, changelog/, organizations/, cpq/, and 25+ additional apps - External integrations: lib/google/, lib/stripe/, lib/slack/, lib/aws/, lib/github/, and 40+ third-party library wrappers - Utilities: scripts/, south_migrations/, templatetags/, test_scaffold/ These README files provide clear, concise module summaries for improved code navigation and documentation. Updated existing README files for main project and key modules. Corrected Hacktoolkit branding to proper capitalization (only H capitalized). Updated .gitignore to exclude MkDocs build artifacts (site/). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 0a0e513 commit 2bd8d5d

File tree

173 files changed

+18469
-123
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

173 files changed

+18469
-123
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
*.pyc
2+
site/

‎README.md‎

Lines changed: 131 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,134 @@
1-
django-htk
2-
==========
1+
# Django HTK (Hacktoolkit)
32

4-
A set of apps, utilities, middlewares, etc for Django
3+
> Production-ready Django toolkit with 29 apps, 47+ integrations, and 24 utility categories for rapid prototyping and scaling.
54
6-
Used/embedded in <https://github.com/hacktoolkit/htk-django-skeleton
5+
## Overview
76

8-
Author: Jonathan Tsai <https://github.com/jontsai>
9-
License: MIT
7+
HTK provides reusable Django applications, third-party service integrations, and utility functions. Use what you need—the modular architecture allows selective adoption without unnecessary dependencies.
8+
9+
## Quick Start
10+
11+
Add to `settings.py`:
12+
13+
```python
14+
INSTALLED_APPS = [
15+
# ... your apps
16+
'htk.apps.accounts', # User authentication & profiles
17+
'htk.apps.notifications', # Multi-channel notifications
18+
'htk.apps.organizations', # Team management
19+
]
20+
```
21+
22+
See individual module documentation for configuration.
23+
24+
## Components at a Glance
25+
26+
### Core Modules
27+
28+
Essential Django utilities organized by function:
29+
30+
| Module | Purpose |
31+
|--------|---------|
32+
| **[admin](admin/README.md)** | Admin customizations and abstract classes |
33+
| **[api](api/README.md)** | REST/JSON API utilities |
34+
| **[cache](cache/README.md)** | Smart caching with descriptors |
35+
| **[models](models/README.md)** | Base model classes and custom fields |
36+
| **[forms](forms/README.md)** | Form classes and widgets |
37+
| **[utils](utils/README.md)** | 24 categories of utility functions |
38+
| **[validators](validators/README.md)** | Data validation helpers |
39+
| **[decorators](decorators/README.md)** | Reusable function decorators |
40+
| **[constants](constants/README.md)** | Centralized application constants |
41+
| **[extensions](extensions/README.md)** | Extended data structures |
42+
43+
### Feature Applications (29)
44+
45+
Pre-built, production-ready apps for common needs:
46+
47+
**User & Organizations**
48+
- [accounts](apps/accounts/README.md) - Authentication, profiles, OAuth
49+
- [organizations](apps/organizations/README.md) - Team and organization management
50+
- [addresses](apps/addresses/README.md) - Address storage and validation
51+
- [invitations](apps/invitations/README.md) - Invitation system
52+
53+
**Communication**
54+
- [notifications](apps/notifications/README.md) - Multi-channel delivery
55+
- [conversations](apps/conversations/README.md) - Direct messaging
56+
- [forums](apps/forums/README.md) - Discussion forums
57+
58+
**Content & Commerce**
59+
- [store](apps/store/README.md) - E-commerce functionality
60+
- [cpq](apps/cpq/README.md) - Configure, Price, Quote
61+
- [customers](apps/customers/README.md) - Customer management
62+
- [bible](apps/bible/README.md) - Bible data and lookup
63+
- [assessments](apps/assessments/README.md) - Quizzes and evaluations
64+
- [feedback](apps/feedback/README.md) - User feedback collection
65+
66+
**Storage & Infrastructure**
67+
- [file_storage](apps/file_storage/README.md) - File uploads
68+
- [blob_storage](apps/blob_storage/README.md) - Binary large object storage
69+
- [kv_storage](apps/kv_storage/README.md) - Key-value storage
70+
- [async_task](apps/async_task/README.md) - Async task handling
71+
- [tokens](apps/tokens/README.md) - Token management
72+
73+
**Features & Configuration**
74+
- [features](apps/features/README.md) - Feature flags and A/B testing
75+
- [url_shortener](apps/url_shortener/README.md) - URL shortening
76+
- [geolocations](apps/geolocations/README.md) - Location services
77+
- [i18n](apps/i18n/README.md) - Internationalization
78+
- [mobile](apps/mobile/README.md) - Mobile app support
79+
- [changelog](apps/changelog/README.md) - Release notes
80+
- [maintenance_mode](apps/maintenance_mode/README.md) - Maintenance windows
81+
- [prelaunch](apps/prelaunch/README.md) - Pre-launch modes
82+
- [sites](apps/sites/README.md) - Multi-site support
83+
- [mp](apps/mp/README.md) - Marketplace functionality
84+
85+
[Complete app documentation →](apps/README.md)
86+
87+
### Service Integrations (47+)
88+
89+
Connect to external services with pre-built integrations:
90+
91+
| Category | Services |
92+
|----------|----------|
93+
| **Cloud** | AWS (S3, EC2, Lambda), Google Cloud, Mapbox, MongoDB, RabbitMQ |
94+
| **Messaging** | Slack, Discord, Mailchimp, Iterable, Plivo, OpenAI, Alexa |
95+
| **Social** | Google OAuth, Facebook, Twitter, LinkedIn, GitHub, Apple Sign In |
96+
| **Payments** | Stripe, Zuora |
97+
| **Data** | Airtable, FullContact, DarkSky, GeoIP |
98+
| **Real Estate** | Zillow, Redfin, Yelp, Indeed, ZipRecruiter, Glassdoor |
99+
| **Other** | Bible APIs (ESV, LiteralWord), QR Codes, Gravatar, Shopify, YouTube |
100+
101+
[Complete integrations documentation →](lib/README.md)
102+
103+
## Documentation
104+
105+
**Choose your path:**
106+
107+
- **[Core modules](admin/README.md)** - Django utilities and helpers
108+
- **[Feature apps](apps/README.md)** - 29 production-ready applications
109+
- **[Integrations](lib/README.md)** - 47+ service connectors
110+
- **[Complete analysis](../htk_analysis.md)** - Comprehensive codebase reference
111+
112+
## Installation
113+
114+
```bash
115+
pip install django-htk
116+
```
117+
118+
## Contributing
119+
120+
Contributions welcome! [Fork the repository](https://github.com/hacktoolkit/htk-django-skeleton), create a feature branch, add tests, and submit a pull request.
121+
122+
## Support
123+
124+
- **Bug reports:** [GitHub Issues](https://github.com/hacktoolkit/htk-django-skeleton/issues)
125+
- **Module docs:** See individual README files
126+
- **Deep dive:** [Full codebase analysis](../htk_analysis.md)
127+
128+
## Notes
129+
130+
- **Author:** [Jonathan Tsai](https://github.com/jontsai)
131+
- **License:** MIT
132+
- **Status:** Production-Ready
133+
- **Last Updated:** November 2025
134+
- **Maintained by:** HTK Contributors

‎admin/README.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# HTK Admin Module
2+
3+
> Django admin customizations and abstract base classes for consistent admin interfaces.
4+
5+
## Purpose
6+
7+
The admin module provides reusable Django admin classes and decorators to reduce boilerplate when building consistent admin interfaces across multiple models.
8+
9+
## Quick Start
10+
11+
```python
12+
from django.contrib import admin
13+
from htk.admin.classes import AbstractAttributeAdmin
14+
from myapp.models import Product
15+
16+
@admin.register(Product)
17+
class ProductAdmin(AbstractAttributeAdmin):
18+
list_display = ['name', 'price', 'is_active']
19+
list_filter = ['is_active', 'created_at']
20+
search_fields = ['name', 'description']
21+
readonly_fields = ['created_at', 'updated_at']
22+
```
23+
24+
## Key Components
25+
26+
| Component | Purpose |
27+
|-----------|---------|
28+
| **AbstractAttributeAdmin** | Base class for models with dynamic attributes |
29+
| **admin decorators** | Performance and permission checking decorators |
30+
| **custom admin site** | Custom AdminSite subclass for branding |
31+
32+
## Common Patterns
33+
34+
### Organized Fieldsets
35+
36+
```python
37+
@admin.register(User)
38+
class UserAdmin(AbstractAttributeAdmin):
39+
list_display = ['username', 'email', 'is_active']
40+
readonly_fields = ['created_at', 'updated_at']
41+
42+
fieldsets = (
43+
('Account', {'fields': ('username', 'email')}),
44+
('Personal', {'fields': ('first_name', 'last_name')}),
45+
('Permissions', {
46+
'fields': ('is_active', 'groups'),
47+
'classes': ('collapse',)
48+
}),
49+
)
50+
```
51+
52+
### Custom List Display with Formatting
53+
54+
```python
55+
from django.utils.html import format_html
56+
57+
@admin.register(Product)
58+
class ProductAdmin(admin.ModelAdmin):
59+
list_display = ['name', 'colored_price', 'status_badge']
60+
61+
def colored_price(self, obj):
62+
color = 'green' if obj.price < 100 else 'red'
63+
return format_html(
64+
'<span style="color: {};">${}</span>',
65+
color, obj.price
66+
)
67+
68+
def status_badge(self, obj):
69+
return format_html(
70+
'<span style="color: {};">●</span> {}',
71+
'green' if obj.is_active else 'red',
72+
'Active' if obj.is_active else 'Inactive'
73+
)
74+
```
75+
76+
### Inline Admin
77+
78+
```python
79+
class BookInline(admin.TabularInline):
80+
model = Book
81+
extra = 1
82+
83+
@admin.register(Author)
84+
class AuthorAdmin(admin.ModelAdmin):
85+
list_display = ['name', 'email']
86+
inlines = [BookInline]
87+
```
88+
89+
### Permission-Based Fields
90+
91+
```python
92+
@admin.register(SensitiveData)
93+
class SensitiveDataAdmin(admin.ModelAdmin):
94+
def get_fields(self, request, obj=None):
95+
fields = ['name', 'description']
96+
if request.user.is_superuser:
97+
fields.append('api_key')
98+
return fields
99+
100+
def get_readonly_fields(self, request, obj=None):
101+
if not request.user.is_superuser:
102+
return ['api_key']
103+
return []
104+
```
105+
106+
## Best Practices
107+
108+
- **Organize fields with fieldsets** - Group related fields, use collapse for advanced options
109+
- **Implement search** - Index searchable fields with `search_fields`
110+
- **Use list filters** - Provide common filter options
111+
- **Secure with permissions** - Check `has_change_permission()` and `has_delete_permission()`
112+
- **Use raw_id_fields** - For large foreign key lists instead of dropdowns
113+
- **Show key info in list_display** - Balance visibility with performance
114+
115+
## Testing
116+
117+
```python
118+
from django.test import TestCase
119+
from django.contrib.admin.sites import AdminSite
120+
from myapp.models import Product
121+
from myapp.admin import ProductAdmin
122+
123+
class ProductAdminTestCase(TestCase):
124+
def setUp(self):
125+
self.admin_site = AdminSite()
126+
self.admin = ProductAdmin(Product, self.admin_site)
127+
128+
def test_list_display(self):
129+
"""Verify list display fields."""
130+
self.assertEqual(
131+
self.admin.list_display,
132+
['name', 'price', 'category']
133+
)
134+
```
135+
136+
## Related Modules
137+
138+
- `htk.admintools` - Admin tools and utilities
139+
- `django.contrib.admin` - Django admin framework
140+
- `htk.decorators` - Function decorators
141+
142+
## References
143+
144+
- [Django Admin Documentation](https://docs.djangoproject.com/en/stable/ref/contrib/admin/)
145+
- [Django Admin Actions](https://docs.djangoproject.com/en/stable/ref/contrib/admin/actions/)
146+
147+
## Notes
148+
149+
- **Status:** Production-Ready
150+
- **Last Updated:** November 2025
151+
- **Maintained by:** HTK Contributors

0 commit comments

Comments
 (0)