From 9be965f615fc4890d693873c3494ef7ec0f51cee Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Thu, 12 Dec 2024 16:36:47 +0100 Subject: [PATCH] docs: add documentation for in-line code annotations (#432) --- docs/how-tos/creating-new-events.rst | 22 +++--------- .../in-line-code-annotations-for-an-event.rst | 34 +++++++++++++++++++ docs/reference/index.rst | 1 + 3 files changed, 40 insertions(+), 17 deletions(-) create mode 100644 docs/reference/in-line-code-annotations-for-an-event.rst diff --git a/docs/how-tos/creating-new-events.rst b/docs/how-tos/creating-new-events.rst index 63872873..a22971c0 100644 --- a/docs/how-tos/creating-new-events.rst +++ b/docs/how-tos/creating-new-events.rst @@ -111,25 +111,13 @@ specifies: The definition created in this step must comply with: -- It should be created in the `signals.py` file in the corresponding subdomain. Refer to Naming Conventions ADR for more +- It should be created in the ``signals.py`` file in the corresponding subdomain. Refer to Naming Conventions ADR for more on events subdomains. -- It should follow the naming conventions specified in Naming Conventions ADR. -- It must be documented using in-line documentation with at least: `event_type`, `event_name`, `event_description` and - `event_data`: +- It should follow the naming conventions specified in :doc:`../decisions/0002-events-naming-and-versioning`. +- It must be documented using in-line documentation with at least: ``event_type``, ``event_name``, ``event_description`` and + ``event_data``. See :doc:`../reference/in-line-code-annotations-for-an-event` for more information. -+-------------------+----------------------------------------------------------------------------------------------------+ -| Annotation | Description | -+===================+====================================================================================================+ -| event_type | Identifier across services of the event. Should follow the events naming conventions. | -+-------------------+----------------------------------------------------------------------------------------------------+ -| event_name | Name of the variable storing the event instance. | -+-------------------+----------------------------------------------------------------------------------------------------+ -| event_description | General description which includes when the event should be emitted. | -+-------------------+----------------------------------------------------------------------------------------------------+ -| event_data | What type of class attribute the event sends. | -+-------------------+----------------------------------------------------------------------------------------------------+ - -Consider the following example: +Consider the course enrollment created event as an example: .. code-block:: python diff --git a/docs/reference/in-line-code-annotations-for-an-event.rst b/docs/reference/in-line-code-annotations-for-an-event.rst new file mode 100644 index 00000000..858ec32d --- /dev/null +++ b/docs/reference/in-line-code-annotations-for-an-event.rst @@ -0,0 +1,34 @@ +In-line Code Annotations for An Open edX Event +============================================== + +When creating a new Open edX Event, you must document the event definition using in-line code annotations. These annotations provide a structured way to document the event's metadata, making it easier for developers to understand the event's purpose and how it should be used. + ++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +| Annotation | Description | ++==================================+==================================================================================================================================+ +| event_type (Required) | Identifier across services of the event. Should follow the :doc:`../decisions/0002-events-naming-and-versioning` standard. | ++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +| event_name (Required) | Name of the variable storing the event instance. | ++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +| event_description (Required) | General description which includes when the event should be emitted. | ++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +| event_data (Required) | What type of class attribute the event sends. | ++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ +| event_warnings (Optional) | Any warnings or considerations that should be taken into account when using the event. | ++----------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ + +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_data: CourseEnrollmentData + COURSE_ENROLLMENT_CREATED = OpenEdxPublicSignal( + event_type="org.openedx.learning.course.enrollment.created.v1", + data={ + "enrollment": CourseEnrollmentData, + } + ) diff --git a/docs/reference/index.rst b/docs/reference/index.rst index b7167d78..ac8d69b4 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -6,6 +6,7 @@ References :caption: Contents: events + in-line-code-annotations-for-an-event glossary event-bus-configurations oeps