docs: add initial documentation for notifications

- Document the types used in
  COURSE_NOTIFICATION_TYPES and COURSE_NOTIFICATION_APPS.
- Port the wiki page on creating a new notification to the docs here.
- Add some miscellaneous docs and placeholder TODO notes.
- Add a data flow diagram.
- Add a short getting started guide for operators
  (mainly for getting email notifications working).

Private-ref: https://tasks.opencraft.com/browse/BB-10065

Author: samuelallan72

openedx/core/djangoapps/notifications/README.md

@@ -0,0 +1,5 @@
+# Notifications
+
+Functionality for notifications on Open edX.
+
+See the [./docs/](./docs/) directory for docs.

openedx/core/djangoapps/notifications/base_notification.py

@@ -1,6 +1,8 @@
 """
 Base setup for Notification Apps and Types.
 """
+from typing import Any, Literal, TypedDict, NotRequired
+
 from django.utils.translation import gettext_lazy as _
 
 from .email_notifications import EmailCadence
@@ -11,6 +13,54 @@
 
 FILTER_AUDIT_EXPIRED_USERS_WITH_NO_ROLE = 'filter_audit_expired_users_with_no_role'
 
+
+class NotificationType(TypedDict):
+    """
+    Define the fields for values in COURSE_NOTIFICATION_TYPES
+    """
+    # The notification app associated with this notification.
+    # Must be a key in COURSE_NOTIFICATION_APPS.
+    notification_app: str
+    # Unique identifier for this notification type.
+    name: str
+    # Mark this as a core notification.
+    # When True, user preferences are taken from the notification app's `core_*` configuration,
+    # overriding the `web`, `email`, `push`, `email_cadence`, and `non_editable` attributes set here.
+    is_core: bool
+    # Template string for notification content (see ./docs/templates.md).
+    # Wrap in gettext_lazy (_) for translation support.
+    content_template: str
+    # A map of variable names that can be used in the template, along with their descriptions.
+    # The values for these variables are passed to the templates when generating the notification.
+    # NOTE: this field is for documentation purposes only; it is not used.
+    content_context: dict[str, Any]
+    # Template used when delivering notifications via email.
+    email_template: str
+    filters: list[str]
+
+    # All fields below are required unless `is_core` is True.
+    # Core notifications take this config from the associated notification app instead (and ignore anything set here).
+
+    # Set to True to enable delivery on web.
+    web: NotRequired[bool]
+    # Set to True to enable delivery via email.
+    email: NotRequired[bool]
+    # Set to True to enable delivery via push notifications.
+    # NOTE: push notifications are not implemented yet
+    push: NotRequired[bool]
+    # How often email notifications are sent.
+    email_cadence: NotRequired[Literal[
+        EmailCadence.DAILY, EmailCadence.WEEKLY, EmailCadence.IMMEDIATELY, EmailCadence.NEVER
+    ]]
+    # Items in the list represent delivery channels
+    # where the user is blocked from changing from what is defined for the notification here
+    # (see `web`, `email`, and `push` above).
+    non_editable: NotRequired[list[Literal["web", "email", "push"]]]
+    # Descriptive information about the notification.
+    info: NotRequired[str]
+
+
+# For help defining new notifications, see ./docs/creating_a_new_notification_guide.md
 COURSE_NOTIFICATION_TYPES = {
     'new_comment_on_response': {
         'notification_app': 'discussion',
@@ -250,7 +300,42 @@
     },
 }
 
-COURSE_NOTIFICATION_APPS = {
+
+class NotificationApp(TypedDict):
+    """
+    Define the fields for values in COURSE_NOTIFICATION_APPS
+
+    An instance of this type describes a notification app,
+    which is a way of grouping configuration of types of notifications for users.
+
+    Each notification type defined in COURSE_NOTIFICATION_TYPES also references an app.
+
+    Each notification type can also be optionally defined as a core notification.
+    In this case, the delivery preferences for that notification are taken
+    from the `core_*` fields of the associated notification app.
+    """
+    # Set to True to enable this app and linked notification types.
+    enabled: bool
+    # Description to be displayed about core notifications for this app.
+    # This string should be wrapped in the gettext_lazy function (imported as `_`) to support translation.
+    core_info: str
+    # Set to True to enable delivery for associated core notifications on web.
+    core_web: bool
+    # Set to True to enable delivery for associated core notifications via emails.
+    core_email: bool
+    # Set to True to enable delivery for associated core notifications via push notifications.
+    # NOTE: push notifications are not implemented yet
+    core_push: bool
+    # How often email notifications are sent for associated core notifications.
+    core_email_cadence: Literal[EmailCadence.DAILY, EmailCadence.WEEKLY, EmailCadence.IMMEDIATELY, EmailCadence.NEVER]
+    # Items in the list represent core notification delivery channels
+    # where the user is blocked from changing from what is defined for the app here
+    # (see `core_web`, `core_email`, and `core_push` above).
+    non_editable: list[Literal["web", "email", "push"]]
+
+
+# For help defining new notifications and notification apps, see ./docs/creating_a_new_notification_guide.md
+COURSE_NOTIFICATION_APPS: dict[str, NotificationApp] = {
     'discussion': {
         'enabled': True,
         'core_info': _('Notifications for responses and comments on your posts, and the ones you’re '
@@ -391,18 +476,22 @@ class NotificationTypeManager:
     def __init__(self):
         self.notification_types = COURSE_NOTIFICATION_TYPES
 
-    def get_notification_types_by_app(self, notification_app):
+    def get_notification_types_by_app(self, notification_app: str):
         """
-        Returns notification types for the given notification app.
+        Returns notification types for the given notification app name.
         """
         return [
             notification_type.copy() for _, notification_type in self.notification_types.items()
             if notification_type.get('notification_app', None) == notification_app
         ]
 
-    def get_core_and_non_core_notification_types(self, notification_app):
+    def get_core_and_non_core_notification_types(
+        self, notification_app: str
+    ) -> tuple[NotificationType, NotificationType]:
         """
-        Returns core notification types for the given app name.
+        Returns notification types for the given app name, split by core and non core.
+
+        Return type is a tuple of (core_notification_types, non_core_notification_types).
         """
         notification_types = self.get_notification_types_by_app(notification_app)
         core_notification_types = []
@@ -498,7 +587,7 @@ def get_notification_app_preferences(self, email_opt_out=False):
         return course_notification_preference_config
 
 
-def get_notification_content(notification_type, context):
+def get_notification_content(notification_type: str, context: dict[str, Any]):
     """
     Returns notification content for the given notification type with provided context.
 

openedx/core/djangoapps/notifications/docs/architecture.md

@@ -0,0 +1,6 @@
+
+## Data flow
+
+Below is a diagram of how data flows through the notification system.
+
+![data flow diagram](./data-flow.jpg)

openedx/core/djangoapps/notifications/docs/creating_a_new_notification_guide.md

@@ -0,0 +1,132 @@
+# Creating a new notification
+
+This documentation provides instructions to developers on how to add new notifications to the existing notification system.
+
+## Overview of terms
+
+* Type: every notification a user sees has a defined type. This type describes the notification's behaviour and template text.
+* App: each notification type is associated with a notification app. A notification app is simply a way to group notifications, and to provide a mechanism for shared behaviour.
+* Core notification: a notification type can be labelled as a core notification. In this case, the behaviour is managed at the app level, not at the level of the individual notification type.
+
+## Defining a notification
+
+The configuration consists of notification types and notification apps. Follow the steps below to define a new notification type.
+
+### Step 1: Define the Notification App
+
+The first step to defining a new notification is deciding on an app to associate it with. Either choose an existing one or create a new one in `COURSE_NOTIFICATION_APPS` in [base_notification.py](../base_notification.py). For example, here is an app named "discussion":
+
+```python
+COURSE_NOTIFICATION_APPS = {
+    'discussion': {
+        'enabled': True,
+        'core_info': '',
+        'core_web': True,
+        'core_email': True,
+        'core_push': True,
+        'non_editable': [],
+        'core_email_cadence': 'weekly'
+    }
+}
+```
+
+The app name (the key) can be any name you wish to add but ideally it should represent existing Django apps in the project.
+For an explanation of the available fields, see `NotificationApp` in [base_notification.py](../base_notification.py).
+
+### **Step 2: Define the Notification Type**
+
+Now you can define the notification type itself.
+To do this, add a new entry to `COURSE_NOTIFICATION_TYPES` in [base_notification.py](../base_notification.py).
+For example, here is a notification defined for a new response to a discussion forum post, associated with the "discussion" app example from the previous step:
+
+```python
+COURSE_NOTIFICATION_TYPES = {
+    'new_response': {
+        'notification_app': 'discussion',
+        'name': 'new_response',
+        'is_core': False,
+        'web': True,
+        'email': True,
+        'push': True,
+        'info': 'Response on post',
+        'non_editable': [],
+        'content_template': _('<{p}><{strong}>{replier_name}</{strong}> responded to your post <{strong}>{post_title}</{strong}></{p}>'),
+        'content_context': {
+            'post_title': 'Post title',
+            'replier_name': 'replier name',
+        },
+        'email_template': '',
+    },
+}
+```
+
+For an explanation of the available fields, see `NotificationType` in [base_notification.py](../base_notification.py).
+
+### Step 3: Update the version in the model file
+
+Newly added types are only usable once you have updated the value of `COURSE_NOTIFICATION_CONFIG_VERSION` in [notifications/models.py](../models.py).
+This constant is used to track changes in notification configuration, and whenever this version is updated preferences of users are also updated with newly available types.
+To update it, increment the value by 1.
+
+Adding new notification types without this step will have no effect.
+You don't need to update the constant for changes that are not stored in database (eg. templates).
+
+Now the notification type is defined and ready to use!
+The next section details how to use this notification type to create and send a notification.
+
+## Sending a notification
+
+To send a notification, you need to send the `USER_NOTIFICATION_REQUESTED` signal with an instance of `UserNotificationData` containing information about the notification to send.
+
+Below is an example function to build and send the `new_response` notification type from earlier.
+
+from openedx_events.learning.signals import USER_NOTIFICATION_REQUESTED
+from openedx_events.learning.data import UserNotificationData
+
+```python
+def send_new_response_notification(user_ids, course, thread, replier_user):
+    notification_data = UserNotificationData(
+        user_ids=user_ids,
+        notification_type="new_response",
+        content_url=f"/{course.id}/posts/{thread.id}",
+        app_name='discussion',
+        course_key=course.id,
+        context={
+            'post_title': thread.title,
+            'replier_name': replier_user.username,
+        },
+    )
+    USER_NOTIFICATION_REQUESTED.send_event(notification_data=notification_data)
+```
+
+Explanation of the parameters for `UserNotificationData`:
+
+| Name | Type | Description |
+| :---- | :---- | :---- |
+| `user_ids` | `list[int]` | List of user IDs to send the notification to. |
+| `notification_type` | `str` | The type of notification to send. This must be a key of `COURSE_NOTIFICATION_TYPES`. |
+| `content_url` | `str` | Url the user will navigate to if they click on the notification. |
+| `app_name` | `str` | The app this notification is associated with. This must be a key of `COURSE_NOTIFICATION_APPS`. |
+| `course_key` | `CourseKey` | The course that this notification will be associated with. |
+| `context` | `dict[str, str]` | Context variables and values to pass to the notification content template. Keys are the variable names defined in the notification type. |
+
+That's it! You have implemented the code to send a new user notification using the `USER_NOTIFICATION_REQUESTED` signal.
+
+## Grouping notifications
+
+For some notification types, the volume for a learner can be huge and can cause annoyance.
+For example, if a learner creates a post, and other learners and staff members start adding responses to his post, if for each comment, we add a response, it could result in dozens of notifications.
+To avoid these scenarios, we have implemented a feature that allows grouping more than one similar notifications into a single notification.
+Steps to group a notification:
+
+1. Enable grouping waffle flag `notifications.enable_notification_grouping`.
+2. Add `group_by_id` in context before sending the `USER_NOTIFICATION_REQUESTED` event (see [discussions_notifications.py](../../../../../lms/djangoapps/discussion/rest_api/discussions_notifications.py), and search for `group_by_id` for an example).
+3. Implement a grouper class to modify content_context (see [grouping_notifications.py](../grouping_notifications.py) for an example).
+
+## Legal
+
+When adding a new notification type, you will need a Privacy threshold assessment done by legal.
+
+## Troubleshooting
+
+If you have followed the above steps and notifications are still not working, check if the `notifications.enable_notifications` waffle flag is enabled.

openedx/core/djangoapps/notifications/docs/data-flow.jpg

@@ -0,0 +1,13 @@
+# Getting started with notifications
+
+1. You will need to configure `NOTIFICATIONS_DEFAULT_FROM_EMAIL` to send email notifications.
+2. Daily and weekly digest emails require the respective management commands to be run on a daily and weekly basis:
+   - daily: `manage.py lms send_email_digest Daily`
+   - weekly: `manage.py lms send_email_digest Weekly`
+
+    Example crontab entries:
+
+    ```
+    0 22 * * * ./manage.py lms send_email_digest Daily
+    0 22 * * SUN ./manage.py lms send_email_digest Weekly
+    ```

openedx/core/djangoapps/notifications/docs/getting-started.md

@@ -0,0 +1,7 @@
+# How to enable the notification tray
+
+On the front end, the notification tray needs to be enabled to simplify the user experience.
+Users can click the bell icon in the header to access the notification tray, which will display notifications from the apps listed above.
+For detailed steps please view the following document: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5319491585/How+to+Enable+Notification+Tray
+
+And explicit implementation of the notification tray on the Learning Dashboard can be viewed in the following document: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/5321916443/Notification+Tray+Implementation+in+Learner+Dashboard

openedx/core/djangoapps/notifications/docs/notification_tray.md

@@ -0,0 +1,14 @@
+
+# Notification template spec
+
+TODO: this needs expanding
+
+- Use `_(...)` to mark the template as translatable.
+- Be sure to add content in `<p> ... </p>` tags. Use `<strong>` to make words bold.
+- Note that only `<p>` and `<strong>` are supported.
+
+TODO: show an example
+
+# Notification grouped content template spec
+
+TODO