refactor: move configurations to reference and improve formatting

docs/how-tos/using-the-event-bus.rst

@@ -5,31 +5,34 @@ After creating a new Open edX Event, you might need to send it across services i
 
 The Open edX Event Bus is a key component of the Open edX architecture, enabling services to communicate without direct dependencies on each other. This guide provides an overview of how to use the event bus to broadcast Open edX Events to multiple services, allowing them to react to changes or actions in the system.
 
-Prerequisites
--------------
+Setup
+-----
 
-Before you start using the event bus, you need to have the following:
+To start producing and consuming events using the Open edX Event Bus, follow these steps:
 
-- A service that will consume the event
-- A service that will produce the event
-- The Open edX Event Bus concrete implementation (Django plugin) installed in both services
-- The message broker (e.g., Kafka or Redis) set up
-- The Open edX Event Bus configuration set up in both services
+Install the Open edX Event Bus Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Configurations
---------------
+First, you need to install the Open edX Event Bus plugin in both the producing and consuming services. The plugin is a Django app that provides the necessary tools and configurations to produce and consume events. You could install the Redis plugin by running:
 
-Here are the available configurations for the event bus we'll be using:
+.. code-block:: bash
 
-.. settings::
-    :folder_path: openedx_events/event_bus
+   pip install edx-event-bus-redis
 
-Setup
------
+Configure the Event Bus
+~~~~~~~~~~~~~~~~~~~~~~~
 
-To start producing and consuming events using the Open edX Event Bus, follow these steps:
+In :doc:`../reference/event-bus-configurations`, you can find the available configurations for the event bus that are used to set up the event bus in the Open edX platform.
+
+In both the producing and consuming services, you need to configure the event bus. This includes setting up the event types, topics, and other configurations for the event bus. In this step, you should configure the producer and consumer classes for the event bus implementation you are using:
 
-#. **Produce the event**
+- In the producing service, configure the producer class by setting the ``EVENT_BUS_PRODUCER`` setting. E.g., ``edx_event_bus_redis.create_producer``.
+- In the consuming service, configure the consumer class by setting the ``EVENT_BUS_CONSUMER`` setting. E.g., ``edx_event_bus_redis.RedisEventConsumer``.
+
+By configuring these settings, you are telling Open edX Events which concrete implementation to use for producing and consuming events.
+
+Produce the Event
+~~~~~~~~~~~~~~~~~
 
 In the producing/host application, include ``openedx_events`` in ``INSTALLED_APPS`` settings and add ``EVENT_BUS_PRODUCER_CONFIG`` setting. This setting is a dictionary of event_types to dictionaries for topic-related configuration. Each topic configuration dictionary uses the topic as a key and contains:
 
@@ -38,42 +41,42 @@ In the producing/host application, include ``openedx_events`` in ``INSTALLED_APP
 
 .. note:: The topic names should not include environment prefix as it will be dynamically added based on ``EVENT_BUS_TOPIC_PREFIX`` setting.
 
-Here's an example of the producer configuration:
+Here's an example of the producer configuration which will publish events for XBlock published and deleted events to the specified topics:
 
 .. code-block:: python
 
    EVENT_BUS_PRODUCER_CONFIG = {
-       'org.openedx.content_authoring.xblock.published.v1': {
-           'content-authoring-xblock-lifecycle': {'event_key_field': 'xblock_info.usage_key', 'enabled': True},
-           'content-authoring-xblock-published': {'event_key_field': 'xblock_info.usage_key', 'enabled': True}
-       },
-       'org.openedx.content_authoring.xblock.deleted.v1': {
-           'content-authoring-xblock-lifecycle': {'event_key_field': 'xblock_info.usage_key', 'enabled': True},
-       },
+        'org.openedx.content_authoring.xblock.published.v1': {
+            'content-authoring-xblock-lifecycle': {'event_key_field': 'xblock_info.usage_key', 'enabled': True},
+            'content-authoring-xblock-published': {'event_key_field': 'xblock_info.usage_key', 'enabled': True}
+        },
+        'org.openedx.content_authoring.xblock.deleted.v1': {
+            'content-authoring-xblock-lifecycle': {'event_key_field': 'xblock_info.usage_key', 'enabled': True},
+        },
    }
 
 The ``EVENT_BUS_PRODUCER_CONFIG`` is read by ``openedx_events`` and a handler is attached which does the leg work of reading the configuration again and pushing to appropriate handlers.
 
-To let the openedx-events know about which event bus implementation to use (e.g., Kafka or Redis), you need to set the ``EVENT_BUS_PRODUCER`` setting. This setting should be the dotted path to the concrete implementation class.
-
-#. **Consume the Event**
+Consume the Event
+~~~~~~~~~~~~~~~~~
 
-In the consuming service, include ``openedx_events`` in ``INSTALLED_APPS`` settings and add ``EVENT_BUS_CONSUMER_CONFIG`` setting. Then, you should implement a receiver for the event type you are interested in.
+In the consuming service, include ``openedx_events`` in ``INSTALLED_APPS`` settings and add ``EVENT_BUS_CONSUMER_CONFIG`` setting. Then, you should implement a receiver for the event type you are interested in. In this example, we are interested in the XBlock deleted event:
 
+.. code-block:: python
 
-   .. code-block:: python
-
-       @receiver(XBLOCK_DELETED)
-       def update_some_data(sender, **kwargs):
-       ... do things with the data in kwargs ...
-       ... log the event for debugging purposes ...
-
-To let the openedx-events know about which event bus implementation to use (e.g., Kafka or Redis), you need to set the ``EVENT_BUS_CONSUMER`` setting. This setting should be the dotted path to the concrete implementation class.
+   @receiver(XBLOCK_DELETED)
+   def update_some_data(sender, **kwargs):
+   ... do things with the data in kwargs ...
+   ... log the event for debugging purposes ...
 
-#. **Run the consumer**: Run the consumer process in the consuming service to listen for events.
+Run the Consumer
+~~~~~~~~~~~~~~~~
 
-#. **Send the event**: Send the event from the producing service.
+To consume events, Open edX Events provides a management command called `consume_events`_ which can be called from the command line, how to run this command will depend on your deployment strategy. This command will start a process that listens to the message broker for new messages, processes them and emits the event.
 
-#. **Check the consumer**: Check the consumer logs to see if the event was received.
+You can find more a concrete example of how to produce and consume events in the `event-bus-redis`_ documentation.
 
-.. TODO: add more details about how to run the consumer and send the event. https://github.com/openedx/openedx-events/blob/main/openedx_events/management/commands/consume_events.py
+.. _consume_events: https://github.com/openedx/openedx-events/blob/main/openedx_events/management/commands/consume_events.py
+.. _event-bus-redis: https://github.com/openedx/event-bus-redis
+.. _run the consumer locally without tutor: https://github.com/openedx/event-bus-redis/?tab=readme-ov-file#testing-locally
+.. _run the consumer locally with tutor: https://github.com/openedx/event-bus-redis/blob/main/docs/tutor_installation.rst#setup-example-with-openedx-course-discovery-and-tutor

docs/reference/event-bus-configurations.rst

@@ -0,0 +1,7 @@
+Event Bus Configuration
+=======================
+
+Here are the available configurations for the event bus that are used to setup the event bus in the Open edX platform.
+
+.. settings::
+    :folder_path: openedx_events/event_bus

docs/reference/index.rst

@@ -7,6 +7,7 @@ References
 
    events
    glossary
+   event-bus-configurations
    oeps
    architecture-subdomains
    real-life-use-cases