-
Notifications
You must be signed in to change notification settings - Fork 12
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: Add a config for openedx-events annotations
- Loading branch information
Showing
3 changed files
with
156 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
18 changes: 18 additions & 0 deletions
18
code_annotations/contrib/config/openedx_events_annotations.yaml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |
134 changes: 134 additions & 0 deletions
134
code_annotations/contrib/sphinx/extensions/openedx_events.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,134 @@ | ||
""" | ||
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) | ||
|
||
current_domain = "" | ||
domain_header = None | ||
|
||
for event_type in sorted(events): | ||
domain = event_type.split(".")[2] | ||
if domain != current_domain: | ||
if domain_header: | ||
yield domain_header | ||
|
||
current_domain = domain | ||
domain_header = nodes.section("", ids=[f"openedxevent-domain-{domain}"]) | ||
domain_header += nodes.title(text=f"Architectural domain: {domain}") | ||
|
||
event = events[event_type] | ||
event_name = event[".. event_name:"] | ||
event_name_literal = nodes.literal(text=quote_value(event_name)) | ||
event_data = event[".. event_data:"] | ||
event_key_field = event.get(".. event_key_field:", None) | ||
event_key_literal = nodes.literal(text=quote_value(event_key_field)) | ||
event_description = event[".. event_description:"] | ||
|
||
event_section = nodes.section("", ids=[f"openedxevent-{event_type}"]) | ||
event_section += nodes.title(text=event_type, ids=[f"title-{event_type}"]) | ||
event_section += nodes.paragraph("", "Signal name:", event_name_literal) | ||
if event_key_field: | ||
event_section += nodes.paragraph( | ||
"", | ||
"Event key field:", | ||
event_key_literal | ||
) | ||
event_section += nodes.paragraph(text=f"Description:" | ||
f" {event_description}") | ||
event_section += nodes.paragraph(text=f"Event data: {event_data}") | ||
event_section += nodes.paragraph( | ||
text=f"Defined at: {event['filename']} (line" | ||
f" {event['line_number']})" | ||
) | ||
|
||
domain_header += event_section | ||
|
||
if domain_header: | ||
yield domain_header | ||
|
||
|
||
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, | ||
} |