Skip to content

Commit

Permalink
feat: Add a config for openedx-events annotations
Browse files Browse the repository at this point in the history
  • Loading branch information
bmtcril committed Feb 20, 2024
1 parent 786da8c commit d99bb11
Show file tree
Hide file tree
Showing 3 changed files with 156 additions and 0 deletions.
4 changes: 4 additions & 0 deletions code_annotations/contrib/config/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"),
)
18 changes: 18 additions & 0 deletions code_annotations/contrib/config/openedx_events_annotations.yaml
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 code_annotations/contrib/sphinx/extensions/openedx_events.py
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,
}

0 comments on commit d99bb11

Please sign in to comment.