Merge pull request #143 from eduNEXT/MJG/triggering-field

feat: [FC-0074] add support for optional trigger information

Author: bmtcril

CHANGELOG.rst

@@ -14,10 +14,15 @@ Change Log
 Unreleased
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+[2.2.0] - 2025-01-15
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+* Add support for optional Open edX Event trigger in-line annotation.
+
 [2.1.0] - 2024-12-12
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-* Add support for optional event warning for in-line annotation.
+* Add support for optional Open edX Event warning for in-line annotation.
 
 [2.0.0] - 2024-10-18
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

code_annotations/__init__.py

@@ -2,4 +2,4 @@
 Extensible tools for parsing annotations in codebases.
 """
 
-__version__ = '2.1.0'
+__version__ = '2.2.0'

code_annotations/contrib/config/__init__.py

@@ -1,15 +1,14 @@
 """
 Expose contrib configuration file paths as Python variables, for use in 3rd-party utilities.
 """
+import importlib.resources
 import os
 
-import importlib_resources
-
-FEATURE_TOGGLE_ANNOTATIONS_CONFIG_PATH = importlib_resources.files(
+FEATURE_TOGGLE_ANNOTATIONS_CONFIG_PATH = importlib.resources.files(
     "code_annotations") / os.path.join("contrib", "config", "feature_toggle_annotations.yaml")
 
-SETTING_ANNOTATIONS_CONFIG_PATH = importlib_resources.files(
+SETTING_ANNOTATIONS_CONFIG_PATH = importlib.resources.files(
     "code_annotations") / os.path.join("contrib", "config", "setting_annotations.yaml")
 
-OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH = importlib_resources.files(
+OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH = importlib.resources.files(
     "code_annotations") / os.path.join("contrib", "config", "openedx_events_annotations.yaml")

code_annotations/contrib/config/openedx_events_annotations.yaml

@@ -12,6 +12,7 @@ annotations:
     - ".. event_description:":
     - ".. event_data:":
     - ".. event_key_field:":
+    - ".. event_trigger_repository:":
     - ".. event_warning:":
 extensions:
     python:

code_annotations/contrib/sphinx/extensions/openedx_events.py

@@ -100,6 +100,7 @@ def iter_nodes(self):
             event_key_field = event.get(".. event_key_field:", "")
             event_key_literal = nodes.literal(text=event_key_field)
             event_description = event[".. event_description:"]
+            event_trigger_repository = event.get(".. event_trigger_repository:")
 
             event_section = nodes.section("", ids=[f"openedxevent-{event_type}"])
             event_section += nodes.title(text=event_type, ids=[f"title-{event_type}"])
@@ -114,10 +115,42 @@ def iter_nodes(self):
                 )
             event_section += nodes.paragraph("", "Event data: ", event_data_literal)
             event_section += nodes.paragraph(
-                text=f"Defined at: {event['filename']} (line"
-                     f" {event['line_number']})"
+                "",
+                "Defined at: ",
+                nodes.reference(
+                    text="{} (line {})".format(
+                        event["filename"], event["line_number"]
+                    ),
+                    refuri="{}/blob/{}/{}#L{}".format(
+                        self.env.config.openedxevents_repo_url,
+                        self.env.config.openedxevents_repo_version,
+                        event["filename"],
+                        event["line_number"],
+                    ),
+                ),
+                ids=[f"definition-{event_name}"],
             )
 
+            if event_trigger_repository:
+                event_trigger_repository = event_trigger_repository.split(" ")
+                event_section += nodes.paragraph(text="Triggered by:", ids=[f"triggers-{event_name}"])
+                triggers_bullet_list = nodes.bullet_list()
+                for repository in event_trigger_repository:
+                    search_url = f"https://github.com/search?q=repo:{repository}+{event_name}.send_event&type=code"
+                    triggers_bullet_list += nodes.list_item(
+                        "",
+                        nodes.paragraph(
+                            "",
+                            "",
+                            nodes.reference(
+                                text=repository,
+                                refuri=search_url,
+                            ),
+                        ),
+                    )
+
+                event_section += triggers_bullet_list
+
             if event.get(".. event_warning:") not in (None, "None", "n/a", "N/A"):
                 event_section += nodes.warning(
                     "", nodes.paragraph("", event[".. event_warning:"]), ids=[f"warning-{event_name}"]