Improve code annotations and integrate with docs

[bmtcril]

Currently the openedx events are documented with code-annotations styled comments:

# .. event_type: org.openedx.learning.student.registration.completed.v1
# .. event_name: STUDENT_REGISTRATION_COMPLETED
# .. event_description: emitted when the user registration process in the LMS is completed.
# .. event_data: UserData

However the integrations with the code-annotations toolchain isn't quite complete, and the important event_key_field is not currently documented, making configuring these events difficult. I propose that we:

• Update the current spec for these annotations to include the event_key_field and add that field to all existing events
• Create a code-annotations extension here so the events can be automatically documented
• Update the openedx-events docs to use the Sphinx autodoc tooling in code-annotations to automatically create documentation for each event like we do with feature toggles
• Add / Update the openedx-events docs around event creation to clarify the annotation strategy and purpose
• If possible, add annotation linting to CI

[mariajgrimaldi]

Those code annotations served their purpose at the beginning of the project, mainly event identification and documentation for developers. Now, I agree there's still work to do, so thank you for the effort.

Some time back, I implemented a few things to generate documentation automatically, but I didn't have the time to finish it. I wish I could provide more detail, but I don't remember what I did exactly:
eduNEXT/edx-platform#236
openedx/code-annotations#72
openedx/edx-lint#176
I hope that helps, although a lot has changed since then. For example, events' docs lived in edx-platform. We'll need to figure out whether the implementation could be adapted to work with what we currently have. Let me know if you want help making it work! Thank you again.

[bmtcril]

@mariajgrimaldi awesome, thanks for the links! I'll definitely reach out when I get stuck.

[bmtcril]

Closed via #318 , but we have the ability not to add this documentation to any repo that defines events in it. I think the linter work is valuable, but outside of what I was hoping to accomplish here. We may take it on as part of the larger Data WG task to organize and better document / lint tracking log events as the two are starting to converge a bit.