feat: Add autodoc for event annotations

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."

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 -------------------------------------------------

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::

docs/reference/index.rst

@@ -5,5 +5,6 @@ References
    :maxdepth: 1
    :caption: Contents:
 
+   events
    oeps
    architecture-subdomains

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(

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(

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(

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

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