docs: address reviews of how-to docs

Improve how-to docs based on reviews: - Remove duplicate event bus how-to - Add missing imports in sample code - Update in-line code docs to reflect latest updates - Fix broken links from event bus concrete implementation
openedx · Feb 14, 2025 · be4ce94 · be4ce94
1 parent acd824c
commit be4ce94
Show file tree

Hide file tree

Showing 8 changed files with 44 additions and 108 deletions.
diff --git a/docs/how-tos/add-event-bus-support-to-an-event.rst b/docs/how-tos/add-event-bus-support-to-an-event.rst
@@ -124,7 +124,7 @@ Run ``python manage.py generate_avro_schemas --help`` to see the available optio
 Step 5: Send the Event Across Services with the Event Bus
 ==========================================================
 
-To validate that you can consume the event emitted by a service through the event bus, you can send the event across services. Here is an example of how you can send the event across services using the Redis event bus implementation following the `setup instructions in a Tutor environment`_. We recommend also following the :doc:`../how-tos/use-the-event-bus` to understand how to use the event bus in your environment.
+To validate that you can consume the event emitted by a service through the event bus, you can send the event across services. Here is an example of how you can send the event across services using the Redis event bus implementation following the `setup instructions in a Tutor environment`_. We recommend also following :doc:`../how-tos/use-the-event-bus-to-broadcast-and-consume-events` to understand how to use the event bus in your environment.
 
 .. note:: If you implemented a custom serializer for a type in the :term:`Event Payload`, the custom serializer support must be included in both the producer and consumer sides before it can be used.
 

diff --git a/docs/how-tos/add-new-event-bus-concrete-implementation.rst b/docs/how-tos/add-new-event-bus-concrete-implementation.rst
@@ -25,14 +25,14 @@ At a high level, the consumer should be a process that takes the signals and eve
 
 The consumer class then needs to implement ``consume_indefinitely`` loop, which will stay running and listen to events as they come in.
 
-We have included a utility function called `prepare_for_new_work_cycle <../../openedx_events/tooling.py#L323>`_ in openedx-events which needs to be called before processing any signal. Currently, it reconnects the db connection if required as well as clears RequestCache and there may be later, more comprehensive changes. These steps mimic some setup/teardown that is normally performed by Django in its request/response-based architecture.
+We have included an utility function called `prepare_for_new_work_cycle <https://github.com/openedx/openedx-events/blob/26d1d3b87c8ba56f159ab20072cd231264e870f9/openedx_events/tooling.py#L332-L346>`_ in openedx-events which needs to be called before processing any signal. Currently, it reconnects the db connection if required as well as clears RequestCache and there may be later, more comprehensive changes. These steps mimic some setup/teardown that is normally performed by Django in its request/response based architecture.
 
 Check out `consumer.py <https://github.com/openedx/event-bus-redis/blob/main/edx_event_bus_redis/internal/consumer.py>`_ in the event bus redis implementation.
 
 Abstraction Tickets
 *********************
 
-The known remaining work for a fully abstracted event bus is captured in the `Abstraction tickets <https://github.com/orgs/edx/projects/11/views/4?filterQuery=label%3Aevent-bus+-status%3ADone+abstraction>`_
+The known remaining work for a fully abstracted event bus is captured in the `Abstraction tickets <https://github.com/search?q=abstraction+event+bus+org%3Aopenedx++&type=issues&state=open>`_
 
 **Maintenance chart**
 

diff --git a/docs/how-tos/consume-an-event.rst b/docs/how-tos/consume-an-event.rst
@@ -86,7 +86,8 @@ Given the design of Open edX Events, you can include the events' definitions in
 
 .. code-block:: python
 
-    from openedx_events import send_event, COURSE_ENROLLMENT_CREATED
+    from openedx_events.learning.signals import COURSE_ENROLLMENT_CREATED
+    from openedx_events.learning.data import CourseData, CourseEnrollmentData, UserData, UserPersonalData
 
     def test_send_enrollment_data_to_webhook(self):
         # Trigger the event

diff --git a/docs/how-tos/create-a-new-event.rst b/docs/how-tos/create-a-new-event.rst
@@ -175,20 +175,24 @@ The :term:`Event Definition` should be implemented in the corresponding subdomai
     # Location openedx_events/learning/signals.py
     # .. event_type: org.openedx.learning.course.enrollment.created.v1
     # .. event_name: COURSE_ENROLLMENT_CREATED
-    # .. event_description: emitted when the user's enrollment process is completed.
+    # .. event_key_field: enrollment.course.course_key
+    # .. event_description: Emitted when the user enrolls in a course.
     # .. event_data: CourseEnrollmentData
+    # .. event_trigger_repository: openedx/edx-platform
     COURSE_ENROLLMENT_CREATED = OpenEdxPublicSignal(
         event_type="org.openedx.learning.course.enrollment.created.v1",
         data={
             "enrollment": CourseEnrollmentData,
         }
     )
 
-- The event definition should be documented using in-line documentation with at least ``event_type``, ``event_name``, ``event_description``, and ``event_data``. This will help consumers understand the event and react to it. See :doc:`../reference/in-line-code-annotations-for-an-event` for more information.
+- The event definition should be documented using in-line documentation with at lest ``event_type``, ``event_name``, ``event_key_field``, ``event_description``, ``event_data`` and ``event_trigger_repository``. This will help consumers understand the event and react to it. See :doc:`../reference/in-line-code-annotations-for-an-event` for more information.
 - The :term:`Event Type` should be unique and follow the naming convention for event types specified in the :doc:`../decisions/0002-events-naming-and-versioning` ADR. This is used by consumers to identify the event.
 - The ``event_name`` should be a constant that is used to identify the event in the code.
+- The ``event_key_field`` should be a field in the payload that uniquely identifies the event. This is used by consumers to identify the event.
 - The ``event_description`` should describe what the event is about and why it is triggered.
 - The ``event_data`` should be the payload class that is used to define the data that is included in the event.
+- The ``event_trigger_repository`` should be the repository where the event is triggered.
 - The ``data`` dictionary should contain the payload class that is used to define the data that is included in the event. This will help consumers understand the event and react to it. Try using a descriptive name for the data field, but keep consistency with the payload class name. Avoid using suffixes like ``_data`` or ``_payload`` in the data field name.
 - The event should be an instance of the ``OpenEdxPublicSignal`` class to ensure that the event is consistent with the Open edX event framework.
 - Receivers should be able to access the event payload in their receivers to react to the event.
@@ -202,7 +206,8 @@ Here is how the integration could look like:
 
 .. code-block:: python
 
-    # Location common/djangoapps/student/models.py
+    # Location common/djangoapps/student/models/course_enrollment.py
+    from openedx_events.learning.data import CourseData, CourseEnrollmentData, UserData, UserPersonalData
     from openedx_events.learning.signals import COURSE_ENROLLMENT_CREATED
 
     def enroll(cls, user, course_key, mode=None, **kwargs):
@@ -212,6 +217,7 @@ Here is how the integration could look like:
         # Enrollment logic here
         ...
         # .. event_implemented_name: COURSE_ENROLLMENT_CREATED
+        # .. event_type: org.openedx.learning.course.enrollment.created.v1
         COURSE_ENROLLMENT_CREATED.send_event(
             enrollment=CourseEnrollmentData(
                 user=UserData(

diff --git a/docs/how-tos/index.rst b/docs/how-tos/index.rst
@@ -9,5 +9,4 @@ How-tos
    consume-an-event
    add-event-bus-support-to-an-event
    use-the-event-bus-to-broadcast-and-consume-events
-   use-the-event-bus
    add-new-event-bus-concrete-implementation
diff --git a/docs/how-tos/use-the-event-bus-to-broadcast-and-consume-events.rst b/docs/how-tos/use-the-event-bus-to-broadcast-and-consume-events.rst
@@ -1,6 +1,8 @@
 Use the Open edX Event Bus to Broadcast and Consume Events
 ==========================================================
 
+.. note:: Be sure to check out how to make your Open edX Event event bus compatible in the :doc:`../how-tos/add-event-bus-support-to-an-event` guide.
+
 After creating a new Open edX Event, you might need to send it across services instead of just within the same process. For this kind of use-cases, you might want to use the Open edX Event Bus. Here :doc:`../concepts/event-bus`, you can find useful information to start getting familiar with the Open edX Event Bus.
 
 The Open edX Event Bus is a key component of the Open edX architecture, enabling services to communicate without direct dependencies on each other. This guide provides an overview of how to use the event bus to broadcast Open edX Events to multiple services, allowing them to react to changes or actions in the system.

diff --git a/docs/how-tos/use-the-event-bus.rst b/docs/how-tos/use-the-event-bus.rst
diff --git a/docs/reference/in-line-code-annotations-for-an-event.rst b/docs/reference/in-line-code-annotations-for-an-event.rst
@@ -21,23 +21,48 @@ Consider the following example:
 
 .. code-block:: python
 
-    # Location openedx_events/learning/signals.py
     # .. event_type: org.openedx.learning.course.enrollment.created.v1
     # .. event_name: COURSE_ENROLLMENT_CREATED
-    # .. event_description: emitted when the user's enrollment process is completed.
+    # .. event_key_field: enrollment.course.course_key
+    # .. event_description: Emitted when the user enrolls in a course.
     # .. event_data: CourseEnrollmentData
+    # .. event_trigger_repository: openedx/edx-platform
     COURSE_ENROLLMENT_CREATED = OpenEdxPublicSignal(
         event_type="org.openedx.learning.course.enrollment.created.v1",
         data={
             "enrollment": CourseEnrollmentData,
         }
     )
 
+When integrating this event into the service, add the following in-line code annotations to help developers find and understand the event:
+
+.. code-block:: python
+
+    # .. event_implemented_name: COURSE_ENROLLMENT_CREATED
+        COURSE_ENROLLMENT_CREATED.send_event(
+            enrollment=CourseEnrollmentData(
+                user=UserData(
+                    pii=UserPersonalData(
+                        username=user.username,
+                        email=user.email,
+                        name=user.profile.name,
+                    ),
+                    id=user.id,
+                    is_active=user.is_active,
+                ),
+                course=course_data,
+                mode=enrollment.mode,
+                is_active=enrollment.is_active,
+                creation_date=enrollment.created,
+            )
+        )
+
+Developers can refer to the in-line code annotations to understand the event's purpose and how it should be used. This makes it easier to work with the event and ensures that it is used correctly across services.
+
 **Maintenance chart**
 
 +--------------+-------------------------------+----------------+--------------------------------+
 | Review Date  | Reviewer                      |   Release      |Test situation                  |
 +--------------+-------------------------------+----------------+--------------------------------+
 |2025-02-05    | Maria Grimaldi                |  Sumac         |Pass.                           |
 +--------------+-------------------------------+----------------+--------------------------------+
-