From c0a2d01636902491cd672ed4008958d9ab7fd4ec Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Fri, 27 Dec 2024 13:04:06 +0100 Subject: [PATCH 01/12] feat: support trigger by fields --- .../config/openedx_events_annotations.yaml | 2 ++ .../sphinx/extensions/openedx_events.py | 28 +++++++++++++++++-- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/code_annotations/contrib/config/openedx_events_annotations.yaml b/code_annotations/contrib/config/openedx_events_annotations.yaml index 17a3d30..c291f2b 100644 --- a/code_annotations/contrib/config/openedx_events_annotations.yaml +++ b/code_annotations/contrib/config/openedx_events_annotations.yaml @@ -12,6 +12,8 @@ annotations: - ".. event_description:": - ".. event_data:": - ".. event_key_field:": + - ".. event_trigger_repository:": + - ".. event_trigger:": - ".. event_warning:": extensions: python: diff --git a/code_annotations/contrib/sphinx/extensions/openedx_events.py b/code_annotations/contrib/sphinx/extensions/openedx_events.py index 3256f35..457f103 100644 --- a/code_annotations/contrib/sphinx/extensions/openedx_events.py +++ b/code_annotations/contrib/sphinx/extensions/openedx_events.py @@ -100,6 +100,8 @@ 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_trigger = event.get(".. event_trigger:", "") event_section = nodes.section("", ids=[f"openedxevent-{event_type}"]) event_section += nodes.title(text=event_type, ids=[f"title-{event_type}"]) @@ -114,8 +116,30 @@ 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}"], + ) + event_section += nodes.paragraph( + "", + "Triggered by: ", + nodes.reference( + text=event_trigger, + refuri="https://github.com/search?q=repo:{}+{}+path:{}".format( + event_trigger_repository, event_name, event_trigger + ), + ), ) if event.get(".. event_warning:") not in (None, "None", "n/a", "N/A"): From 549faa62343a44775b4aae5f3f2d32781235787a Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Fri, 27 Dec 2024 14:16:30 +0100 Subject: [PATCH 02/12] fix: add id to trigger section --- code_annotations/contrib/sphinx/extensions/openedx_events.py | 1 + 1 file changed, 1 insertion(+) diff --git a/code_annotations/contrib/sphinx/extensions/openedx_events.py b/code_annotations/contrib/sphinx/extensions/openedx_events.py index 457f103..545d5cd 100644 --- a/code_annotations/contrib/sphinx/extensions/openedx_events.py +++ b/code_annotations/contrib/sphinx/extensions/openedx_events.py @@ -140,6 +140,7 @@ def iter_nodes(self): event_trigger_repository, event_name, event_trigger ), ), + ids=[f"trigger-{event_name}"], ) if event.get(".. event_warning:") not in (None, "None", "n/a", "N/A"): From 4c4f9765064dfbde3ef71c128f66d1b04c62e8ad Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Fri, 27 Dec 2024 18:00:39 +0100 Subject: [PATCH 03/12] refactor: generate trigger list for paths --- .../config/openedx_events_annotations.yaml | 2 +- .../sphinx/extensions/openedx_events.py | 30 +++++++++++-------- 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/code_annotations/contrib/config/openedx_events_annotations.yaml b/code_annotations/contrib/config/openedx_events_annotations.yaml index c291f2b..f8dc1f7 100644 --- a/code_annotations/contrib/config/openedx_events_annotations.yaml +++ b/code_annotations/contrib/config/openedx_events_annotations.yaml @@ -13,7 +13,7 @@ annotations: - ".. event_data:": - ".. event_key_field:": - ".. event_trigger_repository:": - - ".. event_trigger:": + - ".. event_trigger_path:": - ".. event_warning:": extensions: python: diff --git a/code_annotations/contrib/sphinx/extensions/openedx_events.py b/code_annotations/contrib/sphinx/extensions/openedx_events.py index 545d5cd..00a9b11 100644 --- a/code_annotations/contrib/sphinx/extensions/openedx_events.py +++ b/code_annotations/contrib/sphinx/extensions/openedx_events.py @@ -100,8 +100,8 @@ 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_trigger = event.get(".. event_trigger:", "") + event_trigger_repository = event.get(".. event_trigger_repository:", "").split(" ") + event_trigger_path = event.get(".. event_trigger_path:", "").split(" ") event_section = nodes.section("", ids=[f"openedxevent-{event_type}"]) event_section += nodes.title(text=event_type, ids=[f"title-{event_type}"]) @@ -131,17 +131,23 @@ def iter_nodes(self): ), ids=[f"definition-{event_name}"], ) - event_section += nodes.paragraph( - "", - "Triggered by: ", - nodes.reference( - text=event_trigger, - refuri="https://github.com/search?q=repo:{}+{}+path:{}".format( - event_trigger_repository, event_name, event_trigger + + event_section += nodes.paragraph(text="Triggers", ids=[f"triggers-{event_name}"]) + triggers_bullet_list = nodes.bullet_list() + for repository, path in zip(event_trigger_repository, event_trigger_path): + triggers_bullet_list += nodes.list_item( + "", + nodes.strong( + "", + "Path: ", + nodes.reference( + text=path, + refuri=f"https://github.com/search?q=repo:{repository}+{event_name}+path:{path}" + ), ), - ), - ids=[f"trigger-{event_name}"], - ) + ) + + event_section += triggers_bullet_list if event.get(".. event_warning:") not in (None, "None", "n/a", "N/A"): event_section += nodes.warning( From 934d1551f7f64a2c1e248e29acba46444acacfc7 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 30 Dec 2024 10:36:34 +0100 Subject: [PATCH 04/12] fix: replace with importlib.resources --- code_annotations/contrib/config/__init__.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code_annotations/contrib/config/__init__.py b/code_annotations/contrib/config/__init__.py index 65e9338..9fa7e13 100644 --- a/code_annotations/contrib/config/__init__.py +++ b/code_annotations/contrib/config/__init__.py @@ -3,13 +3,13 @@ """ import os -import importlib_resources +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") From 3cdf9f2e8eac30bcf30bbaab3c39eaecd5a86499 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 30 Dec 2024 11:43:43 +0100 Subject: [PATCH 05/12] fix: address quality issues --- code_annotations/contrib/config/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code_annotations/contrib/config/__init__.py b/code_annotations/contrib/config/__init__.py index 9fa7e13..93eb1cf 100644 --- a/code_annotations/contrib/config/__init__.py +++ b/code_annotations/contrib/config/__init__.py @@ -1,10 +1,10 @@ """ Expose contrib configuration file paths as Python variables, for use in 3rd-party utilities. """ -import os - import importlib.resources +import os + FEATURE_TOGGLE_ANNOTATIONS_CONFIG_PATH = importlib.resources.files( "code_annotations") / os.path.join("contrib", "config", "feature_toggle_annotations.yaml") From 98fbdf4c4d38f97cdc3d5eb87811d919aa13126c Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 30 Dec 2024 11:45:07 +0100 Subject: [PATCH 06/12] refactor: replace strong with paragraph --- code_annotations/contrib/sphinx/extensions/openedx_events.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code_annotations/contrib/sphinx/extensions/openedx_events.py b/code_annotations/contrib/sphinx/extensions/openedx_events.py index 00a9b11..2e2e7ec 100644 --- a/code_annotations/contrib/sphinx/extensions/openedx_events.py +++ b/code_annotations/contrib/sphinx/extensions/openedx_events.py @@ -137,7 +137,7 @@ def iter_nodes(self): for repository, path in zip(event_trigger_repository, event_trigger_path): triggers_bullet_list += nodes.list_item( "", - nodes.strong( + nodes.paragraph( "", "Path: ", nodes.reference( From a07eb00529105995d1f6da7b1016a32ccc78f841 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 30 Dec 2024 11:51:17 +0100 Subject: [PATCH 07/12] fix: address quality issues --- code_annotations/contrib/config/__init__.py | 1 - 1 file changed, 1 deletion(-) diff --git a/code_annotations/contrib/config/__init__.py b/code_annotations/contrib/config/__init__.py index 93eb1cf..b0aa59a 100644 --- a/code_annotations/contrib/config/__init__.py +++ b/code_annotations/contrib/config/__init__.py @@ -2,7 +2,6 @@ Expose contrib configuration file paths as Python variables, for use in 3rd-party utilities. """ import importlib.resources - import os FEATURE_TOGGLE_ANNOTATIONS_CONFIG_PATH = importlib.resources.files( From 626d2a4cb28b0bc42aca5cb8dd42a0deefe1918f Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Mon, 30 Dec 2024 12:13:58 +0100 Subject: [PATCH 08/12] refactor: render triggers only when trigger fields are available --- .../sphinx/extensions/openedx_events.py | 33 ++++++++++--------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/code_annotations/contrib/sphinx/extensions/openedx_events.py b/code_annotations/contrib/sphinx/extensions/openedx_events.py index 2e2e7ec..250b132 100644 --- a/code_annotations/contrib/sphinx/extensions/openedx_events.py +++ b/code_annotations/contrib/sphinx/extensions/openedx_events.py @@ -100,8 +100,8 @@ 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:", "").split(" ") - event_trigger_path = event.get(".. event_trigger_path:", "").split(" ") + event_trigger_repository = event.get(".. event_trigger_repository:") + event_trigger_path = event.get(".. event_trigger_path:") event_section = nodes.section("", ids=[f"openedxevent-{event_type}"]) event_section += nodes.title(text=event_type, ids=[f"title-{event_type}"]) @@ -132,22 +132,25 @@ def iter_nodes(self): ids=[f"definition-{event_name}"], ) - event_section += nodes.paragraph(text="Triggers", ids=[f"triggers-{event_name}"]) - triggers_bullet_list = nodes.bullet_list() - for repository, path in zip(event_trigger_repository, event_trigger_path): - triggers_bullet_list += nodes.list_item( - "", - nodes.paragraph( + if event_trigger_path and event_trigger_repository: + event_trigger_path = event_trigger_path.split(" ") + event_trigger_repository = event_trigger_repository.split(" ") + event_section += nodes.paragraph(text="Triggers", ids=[f"triggers-{event_name}"]) + triggers_bullet_list = nodes.bullet_list() + for repository, path in zip(event_trigger_repository, event_trigger_path): + triggers_bullet_list += nodes.list_item( "", - "Path: ", - nodes.reference( - text=path, - refuri=f"https://github.com/search?q=repo:{repository}+{event_name}+path:{path}" + nodes.paragraph( + "", + "Path: ", + nodes.reference( + text=path, + refuri=f"https://github.com/search?q=repo:{repository}+{event_name}+path:{path}" + ), ), - ), - ) + ) - event_section += triggers_bullet_list + event_section += triggers_bullet_list if event.get(".. event_warning:") not in (None, "None", "n/a", "N/A"): event_section += nodes.warning( From f82bf19c33eb5aa78e67c7ec868a49f868676a88 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Tue, 14 Jan 2025 14:54:44 +0100 Subject: [PATCH 09/12] refactor: drop path from trigger details for more maintainable approach --- .../contrib/config/openedx_events_annotations.yaml | 1 - .../contrib/sphinx/extensions/openedx_events.py | 12 +++++------- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/code_annotations/contrib/config/openedx_events_annotations.yaml b/code_annotations/contrib/config/openedx_events_annotations.yaml index f8dc1f7..a681c92 100644 --- a/code_annotations/contrib/config/openedx_events_annotations.yaml +++ b/code_annotations/contrib/config/openedx_events_annotations.yaml @@ -13,7 +13,6 @@ annotations: - ".. event_data:": - ".. event_key_field:": - ".. event_trigger_repository:": - - ".. event_trigger_path:": - ".. event_warning:": extensions: python: diff --git a/code_annotations/contrib/sphinx/extensions/openedx_events.py b/code_annotations/contrib/sphinx/extensions/openedx_events.py index 250b132..7b1515f 100644 --- a/code_annotations/contrib/sphinx/extensions/openedx_events.py +++ b/code_annotations/contrib/sphinx/extensions/openedx_events.py @@ -101,7 +101,6 @@ def iter_nodes(self): event_key_literal = nodes.literal(text=event_key_field) event_description = event[".. event_description:"] event_trigger_repository = event.get(".. event_trigger_repository:") - event_trigger_path = event.get(".. event_trigger_path:") event_section = nodes.section("", ids=[f"openedxevent-{event_type}"]) event_section += nodes.title(text=event_type, ids=[f"title-{event_type}"]) @@ -132,20 +131,19 @@ def iter_nodes(self): ids=[f"definition-{event_name}"], ) - if event_trigger_path and event_trigger_repository: - event_trigger_path = event_trigger_path.split(" ") + if event_trigger_repository: event_trigger_repository = event_trigger_repository.split(" ") event_section += nodes.paragraph(text="Triggers", ids=[f"triggers-{event_name}"]) triggers_bullet_list = nodes.bullet_list() - for repository, path in zip(event_trigger_repository, event_trigger_path): + for repository in event_trigger_repository: triggers_bullet_list += nodes.list_item( "", nodes.paragraph( "", - "Path: ", + "Event triggered by ", nodes.reference( - text=path, - refuri=f"https://github.com/search?q=repo:{repository}+{event_name}+path:{path}" + text=repository, + refuri=f"https://github.com/search?q=repo:{repository}+{event_name}.send_event&type=code", ), ), ) From cf2a65e50ff086cf3d561eabe6a16daa20ece0c7 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Wed, 15 Jan 2025 12:49:51 +0100 Subject: [PATCH 10/12] refactor: address quality errors and replace event triggered by --- .../contrib/sphinx/extensions/openedx_events.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/code_annotations/contrib/sphinx/extensions/openedx_events.py b/code_annotations/contrib/sphinx/extensions/openedx_events.py index 7b1515f..0e2a72f 100644 --- a/code_annotations/contrib/sphinx/extensions/openedx_events.py +++ b/code_annotations/contrib/sphinx/extensions/openedx_events.py @@ -133,17 +133,17 @@ def iter_nodes(self): if event_trigger_repository: event_trigger_repository = event_trigger_repository.split(" ") - event_section += nodes.paragraph(text="Triggers", ids=[f"triggers-{event_name}"]) + 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( "", - "Event triggered by ", nodes.reference( text=repository, - refuri=f"https://github.com/search?q=repo:{repository}+{event_name}.send_event&type=code", + refuri=search_url, ), ), ) From 4e960391ab4f49cf077a70eb649a051fed76ac71 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Wed, 15 Jan 2025 12:49:51 +0100 Subject: [PATCH 11/12] refactor: address quality errors and replace event triggered by --- code_annotations/contrib/sphinx/extensions/openedx_events.py | 1 + 1 file changed, 1 insertion(+) diff --git a/code_annotations/contrib/sphinx/extensions/openedx_events.py b/code_annotations/contrib/sphinx/extensions/openedx_events.py index 0e2a72f..5f1a770 100644 --- a/code_annotations/contrib/sphinx/extensions/openedx_events.py +++ b/code_annotations/contrib/sphinx/extensions/openedx_events.py @@ -140,6 +140,7 @@ def iter_nodes(self): triggers_bullet_list += nodes.list_item( "", nodes.paragraph( + "", "", nodes.reference( text=repository, From 3958852dcf285fe0f029ed5d49ecd2e37961a0a0 Mon Sep 17 00:00:00 2001 From: Maria Grimaldi Date: Wed, 15 Jan 2025 12:57:48 +0100 Subject: [PATCH 12/12] docs: update changelog and bump library version --- CHANGELOG.rst | 7 ++++++- code_annotations/__init__.py | 2 +- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 8e65378..8563992 100644 --- a/CHANGELOG.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/code_annotations/__init__.py b/code_annotations/__init__.py index 97202b7..0641294 100644 --- a/code_annotations/__init__.py +++ b/code_annotations/__init__.py @@ -2,4 +2,4 @@ Extensible tools for parsing annotations in codebases. """ -__version__ = '2.1.0' +__version__ = '2.2.0'