feat: Add autodoc for event annotations

openedx · Feb 20, 2024 · e85be8b · e85be8b
1 parent dc6f759
commit e85be8b
Show file tree

Hide file tree

Showing 7 changed files with 20 additions and 4 deletions.
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 create 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/content_authoring/signals.py b/openedx_events/content_authoring/signals.py
@@ -31,6 +31,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 +43,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 +55,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 +73,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 +86,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/requirements/doc.txt b/requirements/doc.txt
@@ -36,7 +36,7 @@ click==8.1.7
     #   -r requirements/test.txt
     #   code-annotations
     #   edx-django-utils
-code-annotations==1.6.0
+git+https://github.com/openedx/code-annotations.git@bmtcril/add_openedx_events
     # via -r requirements/test.txt
 colorama==0.4.6
     # via sphinx-autobuild

diff --git a/requirements/test.in b/requirements/test.in
@@ -6,4 +6,4 @@
 ddt                       # A library to multiply test cases
 pytest-cov                # pytest extension for code coverage statistics
 pytest-django             # pytest extension for better Django support
-code-annotations          # provides commands used by the pii_check make target.
+https://github.com/openedx/code-annotations.git@bmtcril/add_openedx_events
diff --git a/requirements/test.txt b/requirements/test.txt
@@ -19,7 +19,7 @@ click==8.1.7
     #   -r requirements/base.txt
     #   code-annotations
     #   edx-django-utils
-code-annotations==1.6.0
+git+https://github.com/openedx/code-annotations.git@bmtcril/add_openedx_events
     # via -r requirements/test.in
 coverage[toml]==7.4.1
     # via