feat: Add autodoc for event annotations (openedx#318)

* feat: Add autodoc for event annotations * feat: Add event_key_field annotations where possible Not all events are compatible with the bus, and some that are have never been configured for it that I could find. This is everything I could locate in the org. * chore: Update to new code-annotations release and make upgrade * chore: Finish removal of pii checks It looks like the pii check config was removed at some point, but checks that pointed to it were left in place. This just finishes the removal.
raccoongang · Mar 14, 2024 · fb6c3e1 · fb6c3e1
1 parent 912ecc0
commit fb6c3e1
Show file tree

Hide file tree

Showing 17 changed files with 120 additions and 130 deletions.
diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
 .PHONY: clean clean_tox compile_translations coverage diff_cover docs dummy_translations \
-        extract_translations fake_translations help pii_check pull_translations push_translations \
+        extract_translations fake_translations help pull_translations push_translations \
         quality requirements selfcheck test test-all upgrade validate install_transifex_client
 
 .DEFAULT_GOAL := help
@@ -56,9 +56,6 @@ upgrade: ## update the requirements/*.txt files with the latest packages satisfy
 quality: ## check coding style with pycodestyle and pylint
 	tox -e quality
 
-pii_check: ## check for PII annotations on all Django models
-	tox -e pii_check
-
 piptools: ## install pinned version of pip-compile and pip-sync
 	pip install -r requirements/pip.txt
 	pip install -r requirements/pip-tools.txt
@@ -72,11 +69,11 @@ test: clean ## run tests in the current virtualenv
 diff_cover: test ## find diff lines that need test coverage
 	diff-cover coverage.xml
 
-test-all: quality pii_check ## run tests on every supported Python/Django combination
+test-all: quality ## run tests on every supported Python/Django combination
 	tox
 	tox -e docs
 
-validate: quality pii_check test ## run tests and quality checks
+validate: quality test ## run tests and quality checks
 
 selfcheck: ## check that the Makefile is well-formed
 	@echo "The Makefile is well-formed."

diff --git a/docs/conf.py b/docs/conf.py
@@ -35,6 +35,7 @@
     'sphinx_copybutton',
     'sphinx.ext.graphviz',
     'sphinxcontrib.mermaid',
+    'code_annotations.contrib.sphinx.extensions.openedx_events',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -103,4 +104,4 @@
 html_static_path = ['_static']
 
 
-# -- Extension configuration -------------------------------------------------
+# -- Extension configuration -------------------------------------------------
diff --git a/docs/reference/events.rst b/docs/reference/events.rst
@@ -0,0 +1,9 @@
+Events
+======
+
+This is the list of Open edX events found in this repository.
+
+.. note::
+    Events can be created in other projects and plugins as well, but these default events are guaranteed to exist.
+
+.. openedxevents::
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -5,5 +5,6 @@ References
    :maxdepth: 1
    :caption: Contents:
 
+   events
    oeps
    architecture-subdomains
diff --git a/openedx_events/analytics/signals.py b/openedx_events/analytics/signals.py
@@ -13,6 +13,7 @@
 
 # .. event_type: org.openedx.analytics.tracking.event.emitted.v1
 # .. event_name: TRACKING_EVENT_EMITTED
+# .. event_key_field: tracking_log.name
 # .. event_description: emitted when a tracking log is created.
 # .. event_data: TrackingLogData
 TRACKING_EVENT_EMITTED = OpenEdxPublicSignal(

diff --git a/openedx_events/content_authoring/signals.py b/openedx_events/content_authoring/signals.py
@@ -20,6 +20,7 @@
 
 # .. event_type: org.openedx.content_authoring.course.catalog_info.changed.v1
 # .. event_name: COURSE_CATALOG_INFO_CHANGED
+# .. event_key_field: catalog_info.course_key
 # .. event_description: Fired when a course changes in Studio in a way that is relevant for catalog consumers.
 # .. event_data: CourseCatalogData
 COURSE_CATALOG_INFO_CHANGED = OpenEdxPublicSignal(
@@ -31,6 +32,7 @@
 
 # .. event_type: org.openedx.content_authoring.xblock.created.v1
 # .. event_name: XBLOCK_CREATED
+# .. event_key_field: xblock_info.usage_key
 # .. event_description: Fired when an XBlock is created.
 # .. event_data: XBlockData
 XBLOCK_CREATED = OpenEdxPublicSignal(
@@ -42,6 +44,7 @@
 
 # .. event_type: org.openedx.content_authoring.xblock.updated.v1
 # .. event_name: XBLOCK_UPDATED
+# .. event_key_field: xblock_info.usage_key
 # .. event_description: Fired when an XBlock is updated.
 # .. event_data: XBlockData
 XBLOCK_UPDATED = OpenEdxPublicSignal(
@@ -53,6 +56,7 @@
 
 # .. event_type: org.openedx.content_authoring.xblock.published.v1
 # .. event_name: XBLOCK_PUBLISHED
+# .. event_key_field: xblock_info.usage_key
 # .. event_description: Fired when an XBlock is published. If a parent block
 #       with changes in one or more child blocks is published, only a single
 #       XBLOCK_PUBLISHED event is fired with parent block details.
@@ -70,6 +74,7 @@
 
 # .. event_type: org.openedx.content_authoring.xblock.deleted.v1
 # .. event_name: XBLOCK_DELETED
+# .. event_key_field: xblock_info.usage_key
 # .. event_description: Fired when an XBlock is deleted.
 # .. event_data: XBlockData
 XBLOCK_DELETED = OpenEdxPublicSignal(
@@ -82,6 +87,7 @@
 
 # .. event_type: org.openedx.content_authoring.xblock.duplicated.v1
 # .. event_name: XBLOCK_DUPLICATED
+# .. event_key_field: xblock_info.usage_key
 # .. event_description: Fired when an XBlock is duplicated in Studio.
 # .. event_data: DuplicatedXBlockData
 XBLOCK_DUPLICATED = OpenEdxPublicSignal(

diff --git a/openedx_events/learning/signals.py b/openedx_events/learning/signals.py
@@ -39,6 +39,7 @@
 
 # .. event_type: org.openedx.learning.auth.session.login.completed.v1
 # .. event_name: SESSION_LOGIN_COMPLETED
+# .. event_key_field: user.pii.username
 # .. event_description: emitted when the user's login process in the LMS is completed.
 # .. event_data: UserData
 SESSION_LOGIN_COMPLETED = OpenEdxPublicSignal(
@@ -75,6 +76,7 @@
 
 # .. event_type: org.openedx.learning.course.unenrollment.completed.v1
 # .. event_name: COURSE_UNENROLLMENT_COMPLETED
+# .. event_key_field: enrollment.course.course_key
 # .. event_description: emitted when the user's unenrollment process is completed.
 # .. event_data: CourseEnrollmentData
 COURSE_UNENROLLMENT_COMPLETED = OpenEdxPublicSignal(
@@ -87,6 +89,7 @@
 
 # .. event_type: org.openedx.learning.certificate.created.v1
 # .. event_name: CERTIFICATE_CREATED
+# .. event_key_field: certificate.course.course_key
 # .. event_description: emitted when the user's certificate creation process is completed.
 # .. event_data: CertificateData
 CERTIFICATE_CREATED = OpenEdxPublicSignal(
@@ -98,6 +101,7 @@
 
 # .. event_type: org.openedx.learning.program.certificate.awarded.v1
 # .. event_name: PROGRAM_CERTIFICATE_AWARDED
+# .. event_key_field: program_certificate.program.uuid
 # .. event_description: Emit when a program certificate is awarded to a learner
 # .. event_data: ProgramCertificateData
 PROGRAM_CERTIFICATE_AWARDED = OpenEdxPublicSignal(
@@ -121,6 +125,7 @@
 
 # .. event_type: org.openedx.learning.certificate.revoked.v1
 # .. event_name: CERTIFICATE_REVOKED
+# .. event_key_field: certificate.course.course_key
 # .. event_description: emitted when the user's certificate annulation process is completed.
 # .. event_data: CertificateData
 CERTIFICATE_REVOKED = OpenEdxPublicSignal(
@@ -132,6 +137,7 @@
 
 # .. event_type: org.openedx.learning.program.certificate.revoked.v1
 # .. event_name: PROGRAM_CERTIFICATE_REVOKED
+# .. event_key_field: program_certificate.program.uuid
 # .. event_description: Emit when a program certificate is revoked from a learner
 # .. event_data: ProgramCertificateData
 PROGRAM_CERTIFICATE_REVOKED = OpenEdxPublicSignal(
@@ -179,6 +185,7 @@
 
 # .. event_type: org.openedx.learning.xblock.skill.verified.v1
 # .. event_name: XBLOCK_SKILL_VERIFIED
+# .. event_key_field: xblock_info.usage_key
 # .. event_description: Fired when an XBlock skill is verified.
 # .. event_data: XBlockSkillVerificationData
 XBLOCK_SKILL_VERIFIED = OpenEdxPublicSignal(
@@ -258,6 +265,7 @@
 
 # .. event_type: org.openedx.learning.user.course_access_role.added.v1
 # .. event_name: COURSE_ACCESS_ROLE_ADDED
+# .. event_key_field: course_access_role_data.course_key
 # .. event_description: Emitted when a user is given a course access role.
 # .. event_data: CourseAccessRoleData
 COURSE_ACCESS_ROLE_ADDED = OpenEdxPublicSignal(
@@ -269,6 +277,7 @@
 
 # .. event_type: org.openedx.learning.user.course_access_role.removed.v1
 # .. event_name: COURSE_ACCESS_ROLE_REMOVED
+# .. event_key_field: course_access_role_data.course_key
 # .. event_description: Emitted when a course access role is removed from a user.
 # .. event_data: CourseAccessRoleData
 COURSE_ACCESS_ROLE_REMOVED = OpenEdxPublicSignal(

diff --git a/requirements/base.txt b/requirements/base.txt
@@ -8,11 +8,13 @@ asgiref==3.7.2
     # via django
 attrs==23.2.0
     # via -r requirements/base.in
+backports-zoneinfo==0.2.1
+    # via django
 cffi==1.16.0
     # via pynacl
 click==8.1.7
     # via edx-django-utils
-django==3.2.24
+django==4.2.11
     # via
     #   -c https://raw.githubusercontent.com/openedx/edx-lint/master/edx_lint/files/common_constraints.txt
     #   -r requirements/base.in
@@ -23,13 +25,13 @@ django-crum==0.7.9
     # via edx-django-utils
 django-waffle==4.1.0
     # via edx-django-utils
-edx-django-utils==5.10.1
+edx-django-utils==5.11.0
     # via -r requirements/base.in
 edx-opaque-keys[django]==2.5.1
     # via -r requirements/base.in
 fastavro==1.9.4
     # via -r requirements/base.in
-newrelic==9.7.0
+newrelic==9.7.1
     # via edx-django-utils
 pbr==6.0.0
     # via stevedore
@@ -41,8 +43,6 @@ pymongo==3.13.0
     # via edx-opaque-keys
 pynacl==1.5.0
     # via edx-django-utils
-pytz==2024.1
-    # via django
 sqlparse==0.4.4
     # via django
 stevedore==5.2.0

diff --git a/requirements/ci.txt b/requirements/ci.txt
@@ -4,7 +4,7 @@
 #
 #    make upgrade
 #
-cachetools==5.3.2
+cachetools==5.3.3
     # via tox
 chardet==5.2.0
     # via tox
@@ -16,7 +16,7 @@ filelock==3.13.1
     # via
     #   tox
     #   virtualenv
-packaging==23.2
+packaging==24.0
     # via
     #   pyproject-api
     #   tox
@@ -32,7 +32,7 @@ tomli==2.0.1
     # via
     #   pyproject-api
     #   tox
-tox==4.13.0
+tox==4.14.1
     # via -r requirements/ci.in
 virtualenv==20.25.1
     # via tox