Clean up docs

Author: kevinrenskers

docs/customizing.md

@@ -12,6 +12,9 @@ class SMSChannel(BaseChannel):
     supports_realtime = True
     supports_digest = False
 
+    def should_send(self, notification):
+        return bool(getattr(notification.recipient, "phone_number", None))
+
     def send_now(self, notification):
         # Send SMS using your preferred service
         send_sms(
@@ -20,131 +23,80 @@ class SMSChannel(BaseChannel):
         )
 ```
 
-## Channel Defaults
+## Required Channels
+
+Make certain channels mandatory for critical notifications:
+
+```python
+from generic_notifications.channels import EmailChannel
+
+@register
+class SecurityAlert(NotificationType):
+    key = "security_alert"
+    name = "Security Alerts"
+    description = "Important security notifications"
+    required_channels = [EmailChannel]  # Cannot be disabled
+```
+
+## Forbidden Channels
 
-Control which channels are enabled by default for different notification types and channels.
+Prevent certain channels from being used for specific notification types:
+
+```python
+from generic_notifications.channels import SMSChannel, WebsiteChannel
+
+@register
+class CommentReceivedNotification(NotificationType):
+    key = "comment_received"
+    name = "Comment received"
+    description = "You received a comment"
+    forbidden_channels = [SMSChannel]  # Never send via SMS
+```
+
+Forbidden channels take highest priority - they cannot be enabled even if specified in `default_channels`, `required_channels`, or user preferences.
+
+## Defaults Channels
+
+By default all channels are enabled for all users, and for all notifications types. Control which channels are enabled by default.
 
 ### Per-Channel Defaults
 
-Set whether a channel is enabled by default across all notification types:
+Disable a channel by default across all notification types:
 
 ```python
 @register
 class SMSChannel(BaseChannel):
     key = "sms"
     name = "SMS"
-    enabled_by_default = False  # Opt-in only - users must explicitly enable
-    supports_realtime = True
-
-@register
-class PushChannel(BaseChannel):
-    key = "push"
-    name = "Push Notifications"
-    enabled_by_default = True  # Opt-out - enabled unless user disables
     supports_realtime = True
+    supports_digest = False
+    enabled_by_default = False  # Opt-in only - users must explicitly enable
 ```
 
-The default value for `enabled_by_default` is `True`, maintaining backward compatibility.
-
 ### Per-NotificationType Defaults
 
-Override channel defaults for specific notification types:
+By default all channels are enabled for every notification type. You can override channel defaults for specific notification types:
 
 ```python
 @register
 class MarketingEmail(NotificationType):
     key = "marketing"
     name = "Marketing Updates"
-    # Only enable email by default, disable website notifications
+    # Only enable email by default
+    # (users can still opt-in to enable other channels)
     default_channels = [EmailChannel]
-
-@register
-class UrgentAlert(NotificationType):
-    key = "urgent_alert"
-    name = "Urgent Alerts"
-    # Enable all channels including normally opt-in ones
-    default_channels = [EmailChannel, WebsiteChannel, SMSChannel, PushChannel]
 ```
 
-When `default_channels` is specified, it overrides the global `enabled_by_default` settings. If `default_channels` is `None` (the default), the system uses each channel's `enabled_by_default` setting.
-
 ### Priority Order
 
 The system determines enabled channels in this priority order:
 
 1. **Forbidden channels** - Always disabled (cannot be overridden)
 2. **Required channels** - Always enabled (cannot be disabled)
-3. **User preferences** - Explicit user enable/disable choices
+3. **User preferences** - Explicit user enable/disable choices (see [preferences.md](https://github.com/loopwerk/django-generic-notifications/tree/main/docs/preferences.md))
 4. **NotificationType.default_channels** - Per-type defaults (if specified)
 5. **BaseChannel.enabled_by_default** - Global channel defaults
 
-### Examples
-
-```python
-# Example: Marketing emails are opt-in only
-@register
-class MarketingEmail(NotificationType):
-    key = "marketing"
-    name = "Marketing Emails"
-    default_channels = []  # No channels enabled by default
-
-# Example: Critical alerts use all available channels
-@register
-class SecurityBreach(NotificationType):
-    key = "security_breach"
-    name = "Security Breach Alert"
-    default_channels = [EmailChannel, SMSChannel, PushChannel]
-    required_channels = [EmailChannel]  # Email cannot be disabled
-
-# Example: Social notifications only on website by default
-@register
-class SocialNotification(NotificationType):
-    key = "social"
-    name = "Social Updates"
-    default_channels = [WebsiteChannel]  # Only website, not email
-```
-
-## Required Channels
-
-Make certain channels mandatory for critical notifications:
-
-```python
-from generic_notifications.channels import EmailChannel
-
-@register
-class SecurityAlert(NotificationType):
-    key = "security_alert"
-    name = "Security Alerts"
-    description = "Important security notifications"
-    required_channels = [EmailChannel]  # Cannot be disabled
-```
-
-## Forbidden Channels
-
-Prevent certain channels from being used for specific notification types:
-
-```python
-from generic_notifications.channels import SMSChannel, WebsiteChannel
-
-@register
-class InternalAuditLog(NotificationType):
-    key = "audit_log"
-    name = "Internal Audit Log"
-    description = "Internal system audit events"
-    forbidden_channels = [SMSChannel]  # Never send audit logs via SMS
-    default_channels = [WebsiteChannel]  # Only show in web interface
-
-@register
-class PrivacySensitiveNotification(NotificationType):
-    key = "privacy_sensitive"
-    name = "Privacy Sensitive Alert"
-    description = "Contains sensitive personal information"
-    forbidden_channels = [WebsiteChannel]  # Don't show in UI where others might see
-    required_channels = [EmailChannel]  # Must go to private email
-```
-
-Forbidden channels take highest priority - they cannot be enabled even if specified in `default_channels`, `required_channels`, or user preferences.
-
 ## Custom Frequencies
 
 Add custom email frequencies:

docs/preferences.md

@@ -1,6 +1,6 @@
 ## User Preferences
 
-By default, users receive notifications based on the channel defaults configured for each notification type and channel. Users can then customize their preferences by explicitly enabling or disabling specific channels for each notification type.
+By default, users receive notifications based on the channel defaults configured for each notification type and channel (see [customizing.md](https://github.com/loopwerk/django-generic-notifications/tree/main/docs/customizing.md)). Users can then customize their preferences by explicitly enabling or disabling specific channels for each notification type.
 
 The system supports both:
 
@@ -47,22 +47,6 @@ CommentNotification.enable_channel(user=user, channel=EmailChannel)
 # Check which channels are enabled for a user
 enabled_channels = CommentNotification.get_enabled_channels(user)
 
-# Set frequency preference directly in the database
-NotificationFrequencyPreference.objects.update_or_create(
-    user=user,
-    notification_type=CommentNotification.key,
-    defaults={'frequency': RealtimeFrequency.key}
-)
-```
-
-### How defaults work
-
-The system determines which channels are enabled using this priority order:
-
-1. **Forbidden channels** - Always disabled (defined in `NotificationType.forbidden_channels`)
-2. **Required channels** - Always enabled (defined in `NotificationType.required_channels`)
-3. **User preferences** - Explicit user choices stored in `NotificationTypeChannelPreference`
-4. **NotificationType defaults** - Per-type defaults (defined in `NotificationType.default_channels`)
-5. **Channel defaults** - Global defaults (defined in `BaseChannel.enabled_by_default`)
-
-This allows for flexible configuration where notification types can have different default behaviors while still allowing user customization.
+# Change to realtime frequency for a notification type
+CommentNotification.set_frequency(user=user, frequency=RealtimeFrequency)
+```