feat: Add a config for openedx-events annotations

code_annotations/contrib/config/__init__.py

@@ -13,3 +13,7 @@
     "code_annotations",
     os.path.join("contrib", "config", "setting_annotations.yaml"),
 )
+OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH = pkg_resources.resource_filename(
+    "code_annotations",
+    os.path.join("contrib", "config", "openedx_events_annotations.yaml"),
+)

code_annotations/contrib/config/openedx_events_annotations.yaml

@@ -0,0 +1,18 @@
+# This code-annotations configuration file supports openedx-events
+
+source_path: ./
+report_path: reports
+safelist_path: .annotation_safe_list.yml
+coverage_target: 100.0
+annotations:
+  feature_toggle:
+    # See annotation format documentation: https://edx-toggles.readthedocs.io/en/latest/how_to/documenting_new_feature_toggles.html
+    - ".. event_type:":
+    - ".. event_name:":
+    - ".. event_description:":
+    - ".. event_data:":
+    - ".. event_key_field:":
+extensions:
+    python:
+        - py
+rst_template: doc.rst.j2

code_annotations/contrib/sphinx/extensions/openedx_events.py

@@ -0,0 +1,133 @@
+"""
+Sphinx extension for viewing openedx events annotations.
+"""
+import os
+
+from docutils import nodes
+from sphinx.util.docutils import SphinxDirective
+
+from code_annotations.contrib.config import OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH
+
+from .base import find_annotations, quote_value
+
+
+def find_events(source_path):
+    """
+    Find the feature toggles as defined in the configuration file.
+
+    Return:
+        toggles (dict): feature toggles indexed by name.
+    """
+    return find_annotations(
+        source_path, OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH, ".. event_type:"
+    )
+
+
+class OpenedxEvents(SphinxDirective):
+    """
+    Sphinx directive to list the events in a single documentation page.
+
+    Use this directive as follows::
+
+        .. openedxevents::
+
+    This directive supports the following configuration parameters:
+
+    - ``openedxevents_source_path``: absolute path to the repository file tree. E.g:
+
+        openedxevents_source_path = os.path.join(os.path.dirname(__file__), "..", "..")
+
+    - ``openedxevents_repo_url``: Github repository where the code is hosted. E.g:
+
+        openedxevents_repo_url = "https://github.com/openedx/myrepo"
+
+    - ``openedxevents_repo_version``: current version of the git repository. E.g:
+
+        import git
+        try:
+            repo = git.Repo(search_parent_directories=True)
+            openedxevents_repo_version = repo.head.object.hexsha
+        except git.InvalidGitRepositoryError:
+            openedxevents_repo_version = "main"
+    """
+
+    required_arguments = 0
+    optional_arguments = 0
+    option_spec = {}
+
+    def run(self):
+        """
+        Public interface of the Directive class.
+
+        Return:
+            nodes (list): nodes to be appended to the resulting document.
+        """
+        return list(self.iter_nodes())
+
+    def iter_nodes(self):
+        """
+        Iterate on the docutils nodes generated by this directive.
+        """
+        events = find_events(self.env.config.openedxevents_source_path)
+
+        for event_type in sorted(events):
+            event = events[event_type]
+            event_name = event[".. event_name:"]
+            event_data = event[".. event_data:"]
+            event_key_field = event.get(".. event_key_field:", 'Not documented')
+            event_description = event[".. event_description:"]
+
+            event_section = nodes.section("", ids=[f"openedxevent-{event_type}"])
+            event_section += nodes.title(text=event_type, ids=[f"name-{event_type}"])
+            event_section += nodes.paragraph(
+                "", "Event name: ", event_name, ids=[f"default-{event_name}"]
+            )
+            event_section += nodes.paragraph(
+                "", "Event key field: ", event_key_field, ids=[f"key-{event_name}"]
+            )
+            event_section += nodes.paragraph(
+                text=f"Description: {event_description}",
+                ids=[f"description-{event_type}"],
+            )
+            event_section += nodes.paragraph(
+                text=f"Event data: {event_data}",
+                ids=[f"event-data-{event_data}"]
+            )
+            event_section += nodes.paragraph(
+                "",
+                "Source: ",
+                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"source-{event_type}"],
+            )
+
+            yield event_section
+
+
+def setup(app):
+    """
+    Declare the Sphinx extension.
+    """
+    app.add_config_value(
+        "openedxevents_source_path",
+        os.path.abspath(".."),
+        "env",
+    )
+    app.add_config_value("openedxevents_repo_url", "", "env")
+    app.add_config_value("openedxevents_repo_version", "main", "env")
+    app.add_directive("openedxevents", OpenedxEvents)
+
+    return {
+        "version": "0.1",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }