docs: [FC-0074] include tooling and data attributes in references (#450)

docs/concepts/openedx-events.rst

@@ -20,7 +20,7 @@ Events are primarily used as a communication method between internal services by
 How do Open edX Events work?
 ----------------------------
 
-Open edX Events are implemented by a class called `OpenEdxPublicSignal`_, which inherits from `Django's Signals class` and adds behaviors specific to the Open edX ecosystem. Thanks to this design, ``OpenEdxPublicSignal`` leverages the functionality of Django signals, allowing developers to apply their existing knowledge of the Django framework.
+Open edX Events are implemented by a class called `OpenEdxPublicSignal`_, which inherits from `Django's Signals class` and adds behaviors specific to the Open edX ecosystem. Thanks to this design, ``OpenEdxPublicSignal`` leverages the functionality of Django signals, allowing developers to apply their existing knowledge of the Django framework. You can review the :doc:`Open edX Events Tooling <../reference/events-tooling>` documentation for more information on the tooling available for working with Open edX events.
 
 .. _events-architecture:
 

docs/conf.py

@@ -12,9 +12,8 @@
 #
 import os
 import re
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
-
+import sys
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
@@ -39,6 +38,9 @@
     'code_annotations.contrib.sphinx.extensions.openedx_events',
     'sphinx.ext.intersphinx',
     'code_annotations.contrib.sphinx.extensions.settings',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/how-tos/create-a-new-event.rst

@@ -159,7 +159,7 @@ In our example, the event definition and payload for the enrollment event could
 - The payload should be an `attrs`_ class to ensure that the data is immutable by using the ``frozen=True`` argument and to ensure that the data is self-descriptive.
 - Use the ``attr.ib`` decorator to define the fields in the payload with the data type that the field should contain. Try to use the appropriate data type for each field to ensure that the data is consistent and maintainable, you can inspect the triggering logic to review the data that is available at the time the event is triggered.
 - Try using nested data classes to group related data together. This will help maintain consistency and make the event more readable. For instance, in the above example, we have grouped the data into User, Course, and Enrollment data.
-- Try reusing existing data classes if possible to avoid duplicating data classes. This will help maintain consistency and reduce the chances of introducing errors.
+- Try reusing existing data classes if possible to avoid duplicating data classes. This will help maintain consistency and reduce the chances of introducing errors. You can review the existing data classes in :doc:`../reference/events-data` to see if there is a data class that fits your use case.
 - Each field in the payload should be documented with a description of what the field represents and the data type it should contain. This will help consumers understand the payload and react to the event. You should be able to justify why each field is included in the payload and how it relates to the event.
 - Use defaults for optional fields in the payload to ensure its consistency in all cases.
 

docs/reference/events-data.rst

@@ -0,0 +1,30 @@
+Open edX Events Data Attributes
+===============================
+
+Here are the data classes and attributes available for use when creating new Open edX Events. Review the classes and attributes to understand the data available for use in your event before creating a new data classes.
+
+.. note:: If you are creating a new data class in a subdomain that is not listed here, please add the new data class to the appropriate new subdomain section.
+
+Learning Subdomain
+------------------
+
+.. automodule:: openedx_events.learning.data
+   :members:
+
+Content Authoring Subdomain
+---------------------------
+
+.. automodule:: openedx_events.content_authoring.data
+   :members:
+
+Analytics Subdomain
+-------------------
+
+.. automodule:: openedx_events.analytics.data
+   :members:
+
+Enterprise Subdomain
+--------------------
+
+.. automodule:: openedx_events.enterprise.data
+   :members:

docs/reference/events-tooling.rst

@@ -0,0 +1,7 @@
+Open edX Events Tooling
+=======================
+
+Here we document the tooling available for working with Open edX events as a developer.
+
+.. autoclass:: openedx_events.tooling.OpenEdxPublicSignal
+   :members:

docs/reference/index.rst

@@ -5,6 +5,8 @@ References
    :maxdepth: 1
    :caption: Contents:
 
+   events-tooling
+   events-data
    events
    in-line-code-annotations-for-an-event
    glossary

openedx_events/analytics/data.py

@@ -13,15 +13,15 @@
 @attr.s(frozen=True)
 class TrackingLogData:
     """
-    Data describing tracking events.
+    Data related to tracking events.
 
-    Arguments:
+    Attributes:
         name (str): event name
         timestamp (datetime): timestamp of the event
-        data (str): json string representation of a dictionary with extra data (optional),
-                    e.g. {"course_id": "course-v1:edX+DemoX+Demo_Course"}
+        data (str): json string representation of a dictionary with extra data (optional), e.g.,
+           >>> {"course_id": "course-v1:edX+DemoX+Demo_Course"}
         context (dict): json string representation of a dictionary of context data
-            defined in https://edx.readthedocs.io/projects/devdata/en/latest/internal_data_formats/tracking_logs/
+           defined in https://edx.readthedocs.io/projects/devdata/en/latest/internal_data_formats/tracking_logs/
     """
 
     name = attr.ib(type=str)

openedx_events/analytics/signals.py

@@ -14,7 +14,7 @@
 # .. event_type: org.openedx.analytics.tracking.event.emitted.v1
 # .. event_name: TRACKING_EVENT_EMITTED
 # .. event_key_field: tracking_log.name
-# .. event_description: emitted when a tracking log is created.
+# .. event_description: Emitted when a tracking log event is emitted.
 # .. event_data: TrackingLogData
 # .. event_trigger_repository: openedx/event-tracking
 TRACKING_EVENT_EMITTED = OpenEdxPublicSignal(

openedx_events/content_authoring/data.py

@@ -18,9 +18,9 @@
 @attr.s(frozen=True)
 class CourseData:
     """
-    Attributes defined for Open edX Course object.
+    Data related to a course object.
 
-    Arguments:
+    Attributes:
         course_key (CourseKey): identifier of the Course object.
     """
 
@@ -30,14 +30,14 @@ class CourseData:
 @attr.s(frozen=True)
 class CourseScheduleData:
     """
-    Data describing course scheduling.
+    Data related to a course schedule.
 
-    Arguments:
-        start (datetime): course start date
-        pacing (str): 'instructor' or 'self'
-        end (datetime): course end date (optional)
-        enrollment_start (datetime): start of course enrollment (optional)
-        enrollment_end (datetime): end of course enrollment (optional)
+    Attributes:
+        start (datetime): course start date.
+        pacing (str): 'instructor' or 'self'.
+        end (datetime): course end date (optional).
+        enrollment_start (datetime): start of course enrollment (optional).
+        enrollment_end (datetime): end of course enrollment (optional).
     """
 
     start = attr.ib(type=datetime)
@@ -50,14 +50,14 @@ class CourseScheduleData:
 @attr.s(frozen=True)
 class CourseCatalogData:
     """
-    Data needed for a course catalog entry.
+    Data related to a course catalog entry.
 
-    Arguments:
+    Attributes:
         course_key (CourseKey): identifier of the Course object.
-        name (str): course name
-        schedule_data (CourseScheduleData): scheduling information for the course
-        hidden (bool): whether the course is hidden from search (optional)
-        invitation_only (bool): whether the course requires an invitation to enroll
+        name (str): course name.
+        schedule_data (CourseScheduleData): scheduling information for the course.
+        hidden (bool): whether the course is hidden from search (optional).
+        invitation_only (bool): whether the course requires an invitation to enroll.
     """
 
     # basic identifiers
@@ -73,13 +73,13 @@ class CourseCatalogData:
 @attr.s(frozen=True)
 class XBlockData:
     """
-    Data about changed XBlock.
+    Data related to an XBlock object.
 
-    Arguments:
+    Attributes:
         usage_key (UsageKey): identifier of the XBlock object.
         block_type (str): type of block.
         version (UsageKey): identifier of the XBlock object with branch and version data (optional). This
-        could be used to get the exact version of the XBlock object.
+           could be used to get the exact version of the XBlock object.
     """
 
     usage_key = attr.ib(type=UsageKey)
@@ -90,11 +90,11 @@ class XBlockData:
 @attr.s(frozen=True)
 class DuplicatedXBlockData(XBlockData):
     """
-    Data about duplicated XBlock.
+    Data related to an XBlock object that has been duplicated.
 
     This class extends XBlockData to include source_usage_key.
 
-    Arguments:
+    Attributes:
         source_usage_key (UsageKey): identifier of the source XBlock object.
     """
 
@@ -104,13 +104,13 @@ class DuplicatedXBlockData(XBlockData):
 @attr.s(frozen=True)
 class CertificateSignatoryData:
     """
-    Attributes defined for Open edX CertificateSignatory data object.
+    Data related to a certificate signatory. Subset of CertificateSignatory object from the LMS.
 
-    Arguments:
-        image (BinaryIO): certificate signature image.
+    Attributes:
+        image (BinaryIO): certificate signature image. Take care that the image field is BinaryIO.
         name (str): name of signatory.
         organization (str): organization that signatory belongs to.
-        title (int): signatory title.
+        title (str): signatory title.
     """
 
     # Note: Please take care that the image field is BinaryIO, which means
@@ -128,22 +128,22 @@ class CertificateSignatoryData:
 @attr.s(frozen=True)
 class CertificateConfigData:
     """
-    Attributes defined for Open edX CertificateConfig data object.
+    Data related to a certificate configuration. Subset of CertificateConfig object from the LMS.
 
-    Arguments:
+    Attributes:
         certificate_type (str): certificate type. Possible types are certificate relevant course modes:
-         - credit,
-         - verified,
-         - professional,
-         - no-id-professional,
-         - executive-education,
-         - paid-executive-education,
-         - paid-bootcamp,
-         - masters.
+           - credit,
+           - verified,
+           - professional,
+           - no-id-professional,
+           - executive-education,
+           - paid-executive-education,
+           - paid-bootcamp,
+           - masters.
         course_key (CourseKey): identifier of the Course object.
         title (str): certificate title.
         signatories (List[CertificateSignatoryData]): contains a collection of signatures
-        that belong to the certificate configuration.
+           that belong to the certificate configuration.
         is_active (bool): indicates whether the certifivate configuration is active.
     """
 
@@ -157,11 +157,11 @@ class CertificateConfigData:
 @attr.s(frozen=True)
 class ContentLibraryData:
     """
-    Data about changed ContentLibrary.
+    Data related to a content library that has changed.
 
-    Arguments:
+    Attributes:
         library_key (LibraryLocatorV2): a key that represents a Blockstore-based content library.
-        update_blocks (bool): flag that indicates whether the content library blocks indexes should be updated
+        update_blocks (bool): flag that indicates whether the content library blocks indexes should be updated.
     """
 
     library_key = attr.ib(type=LibraryLocatorV2)
@@ -171,9 +171,9 @@ class ContentLibraryData:
 @attr.s(frozen=True)
 class LibraryBlockData:
     """
-    Data about changed LibraryBlock.
+    Data related to a library block that has changed.
 
-    Arguments:
+    Attributes:
         library_key (LibraryLocatorV2): a key that represents a Blockstore-based content library.
         usage_key (LibraryUsageLocatorV2): a key that represents a XBlock in a Blockstore-based content library.
     """
@@ -185,12 +185,12 @@ class LibraryBlockData:
 @attr.s(frozen=True)
 class ContentObjectData:
     """
-    Data about a content object.
+    Data related to a content object.
 
-    Arguments:
+    Attributes:
         object_id (str): identifier of the Content object. This represents the id of the course or library block
-        as a string. For example:
-        block-v1:SampleTaxonomyOrg2+STC1+2023_1+type@vertical+block@f8de78f0897049ce997777a3a31b6ea0
+           as a string. For example:
+           >>> block-v1:SampleTaxonomyOrg2+STC1+2023_1+type@vertical+block@f8de78f0897049ce997777a3a31b6ea0
     """
 
     object_id = attr.ib(type=str)
@@ -199,15 +199,14 @@ class ContentObjectData:
 @attr.s(frozen=True)
 class ContentObjectChangedData(ContentObjectData):
     """
-    Data about a changed content object.
+    Data related to a content object that has changed.
 
-    Arguments:
+    Attributes:
         object_id (str): identifier of the Content object. This represents the id of the course or library block
-        as a string. For example:
-        block-v1:SampleTaxonomyOrg2+STC1+2023_1+type@vertical+block@f8de78f0897049ce997777a3a31b6ea0
-
-        changes: list of changes made to this ContentObject, e.g. "tags", "collections"
-        If list is empty, assume everything has changed.
+           as a string. For example:
+           >>> block-v1:SampleTaxonomyOrg2+STC1+2023_1+type@vertical+block@f8de78f0897049ce997777a3a31b6ea0
+        changes: list of changes made to this ContentObject, e.g. "tags", "collections". If list is empty,
+           assume everything has changed.
     """
 
     changes = attr.ib(type=List[str], factory=list)
@@ -216,13 +215,13 @@ class ContentObjectChangedData(ContentObjectData):
 @attr.s(frozen=True)
 class LibraryCollectionData:
     """
-    Data about changed content library Collection.
+    Data related to a library collection that has changed.
 
-    Arguments:
+    Attributes:
         library_key (LibraryLocatorV2): a key that represents a Blockstore-based content library.
         collection_key (str): identifies the collection within the library's learning package
         background (bool): indicate whether the sender doesn't want to wait for handler to finish execution,
-        i.e., the handler can run the task in background. By default it is False.
+           i.e., the handler can run the task in background. By default it is False.
     """
 
     library_key = attr.ib(type=LibraryLocatorV2)