docs: [FC-0074] index, references and concepts style review

docs/concepts/openedx-filters.rst

@@ -1,20 +1,20 @@
 Open edX Filters
-================
+#################
 
 Overview
---------
+*********
 
 As mentioned in the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework` docs, Open edX filters provide a mechanism for modifying the platform's behavior by altering runtime data or halting execution based on specific conditions. Filters allow developers to implement application flow control based on their business logic or requirements without directly modifying the application code.
 
 Throughout this document, we will refer to Open edX Filters as filters interchangeably.
 
-What are Open edX Filters?
---------------------------
+What Are Open edX Filters?
+*****************************
 
 An Open edX Filter is a pipeline mechanism that executes a series of functions when configured. Each function receives input arguments, which are data used by the process in execution, and returns the same arguments, possibly modified. Given this design, filters can modify the application flow according to the specified configuration, altering or adding new behaviors during execution time.
 
-How do Open edX Filters work?
------------------------------
+How Do Open edX Filters Work?
+******************************
 
 Open edX Filters are implemented using an accumulative pipeline mechanism, which executes a series of functions in a specific order. Each function in the pipeline receives the output of the previous function as input, allowing developers to build complex processing logic by chaining multiple functions together. The pipeline ensures that the order of execution is maintained and that the result of a previous function is available to the current one in the form of a pipeline.
 
@@ -30,58 +30,58 @@ In this diagram, we illustrate the workflow of triggering an Open edX Filter:
    :align: center
 
 Components
-~~~~~~~~~~
+============
 
-#. Application (caller): The component that calls the filter during its execution, triggering the pipeline to process the input data. Developers may have added this call to a part of the application to include different behaviors. E.g., a user enrolls in a course, triggering the `CourseEnrollmentStarted filter`_.
-#. OpenEdxPublicFilter: The class that implements all methods used to manage the execution of the filter.
-#. PipelineStep1...N: The pipeline steps that are executed in sequence, each processing the input data and returning potentially modified data. These steps are defined by the developer to introduce additional behaviors. E.g., a pipeline step that checks user eligibility for enrollment.
+* **Application (caller):** The component that calls the filter during its execution, triggering the pipeline to process the input data. Developers may have added this call to a part of the application to include different behaviors. E.g., a user enrolls in a course, triggering the `CourseEnrollmentStarted filter`_.
+* **OpenEdxPublicFilter:** This class implements all methods used to manage the execution of the filter.
+* **PipelineStep1...N:** The pipeline steps that are executed in sequence, each processing the input data and returning potentially modified data. The developer defines these steps to introduce additional behaviors.  E.g., a pipeline step that checks user eligibility for enrollment.
 
 Workflow
-~~~~~~~~
+===========
 
 #. An application component (caller) invokes the filter during its execution by calling the ``run_filter`` method implemented by its :term:`filter definition<Filter Definition>`.
 
-#. The caller passes the input data to the filter through the ``run_filter`` method, this data are in-memory platform objects that the filter will process.
+#. The caller passes the input data to the filter through the ``run_filter`` method. These data are in-memory platform objects that the filter will process.
 
 #. The ``run_filter`` method of the filter calls the ``OpenEdxPublicFilter.run_pipeline`` method under the hood, which manages the execution of the filter's pipeline.
 
 #. This method retrieves the configuration from ``OPEN_EDX_FILTERS_CONFIG``, which defines a list of N functions :math:`f_1, f_2, \ldots, f_{n}` that will be executed.
 
-#. Then it executes each function in the pipeline sequentially, starting with :math:`f_1`, which processes the input arguments ``kwargs`` and applies the developer's operations, returning potentially modified arguments ``kwargs_1``.
+#. Then, it executes each function in the pipeline sequentially, starting with :math:`f_1`, which processes the input arguments ``kwargs`` and applies the developer's operations, returning potentially modified arguments ``kwargs_1``.
 
-#. The next function (if there are more than one) :math:`f_2` receives the potentially modified arguments ``kwargs_1`` and applies further operations, returning another modified set of arguments ``kwargs_2``. This process continues through the list of functions.
+#. The next function (if there is more than one) :math:`f_2` receives the potentially modified arguments ``kwargs_1`` and applies further operations, returning another modified set of arguments ``kwargs_2``. This process continues through the list of functions.
 
 #. Each subsequent function receives the output from the previous function and returns its modified output until all functions have been executed.
 
-#. At any point in the pipeline, a developer can halt execution by raising an exception, based on conditions defined in the processing logic, to stop the application flow. Let's assume that :math:`f_{2}` raises an exception instead of returning the modified arguments ``kwargs_2``. In this case, the pipeline stops, and the ``OpenEdxPublicFilter.run_pipeline`` method raises the exception to the caller as the final output. From there the caller can handle the exception as needed.
+#. At any point in the pipeline, a developer can halt execution by raising an exception based on conditions defined in the processing logic to stop the application flow. Let's assume that :math:`f_{2}` raises an exception instead of returning the modified arguments ``kwargs_2``. In this case, the pipeline stops, and the ``OpenEdxPublicFilter.run_pipeline`` method raises the exception to the caller as the final output. From there, the caller can handle the exception as needed.
 
 #. If no exceptions are raised, the pipeline continues executing the functions until the final function :math:`f_{n}` has been executed.
 
-#. The final modified arguments ``kwargs_n`` are returned to the caller, which may use them for the remaining part of its execution.
+#. The final modified arguments ``kwargs_n`` are returned to the caller and may be used for the remaining part of its execution.
 
-Each function in the pipeline has the ability to modify the input data, add new data, or halt execution based on specific conditions, such as raising exceptions if certain criteria is not met. This pipeline structure ensures that complex business logic can be applied during runtime without directly altering the application code.
+Each function in the pipeline has the ability to modify the input data, add new data, or halt execution based on specific conditions, such as raising exceptions if certain criteria are not met. This pipeline structure ensures that complex business logic can be applied during runtime without directly altering the application code.
 
 Real-Life Example
-~~~~~~~~~~~~~~~~~
+*******************
 
 Here's an example of the `CourseEnrollmentStarted filter`_ in action:
 
 #. A user enrolls in a course, triggering the `CourseEnrollmentStarted filter`_ by calling the ``run_filter`` method with the enrollment details. This filter processes information about the user, course, and enrollment details.
 
-#. The ``run_pipeline`` method executes a series of functions configured in ``OPEN_EDX_FILTERS_CONFIG``, e.g. checking user eligibility for enrollment or updating the enrollment status in a third-party system.
+#. The ``run_pipeline`` method executes a series of functions configured in ``OPEN_EDX_FILTERS_CONFIG``, e.g., checking user eligibility for enrollment or updating the enrollment status in a third-party system.
 
-#. Each function can modify the input data or halt the process based on business logic, e.g. denying enrollment if the user is ineligible.
+#. Each function can modify the input data or halt the process based on business logic, e.g., denying enrollment if the user is ineligible.
 
 #. The final output of the pipeline, such as the updated enrollment details, is returned to the caller, or an exception is raised if the user is not eligible.
 
 #. The process is complete once all functions in the pipeline have executed, and the enrollment process continues based on the final output.
 
 By running filters in key places of the Open edX platform, developers can extend the platform's functionality in a flexible and maintainable way.
 
-How are Open edX Filters used?
-------------------------------
+How Are Open edX Filters Used?
+*******************************
 
-Developers can implement functions in an `Open edX Django plugin`_, configure them for a particular filter in the ``OPEN_EDX_FILTERS_CONFIG`` setting, and modify the application flow when a the filter in question is invoked by the process in execution. These functions can the application's behavior by altering data, adding new data, or stopping execution by raising exceptions. For example, a filter can stop a student's enrollment if certain conditions, such as business rules, are not met.
+Developers can implement functions in an `Open edX Django plugin`_, configure them for a particular filter in the ``OPEN_EDX_FILTERS_CONFIG`` setting, and modify the application flow when the filter in question is invoked by the process in execution. These functions can change the application's behavior by altering data, adding new data, or stopping execution by raising exceptions. For example, a filter can stop a student's enrollment if certain conditions, such as business rules, are not met.
 
 For more information on how to use Open edX Filters, refer to the :doc:`how-tos section <../how-tos/index>`.
 
@@ -91,3 +91,11 @@ For more information on how to use Open edX Filters, refer to the :doc:`how-tos
 .. _Python Social Auth: https://python-social-auth.readthedocs.io/en/latest/pipeline.html
 .. _OpenEdxPublicFilter: https://github.com/openedx/openedx-filters/blob/main/openedx_filters/tooling.py#L14-L15
 .. _Open edX Django plugin: https://edx.readthedocs.io/projects/edx-django-utils/en/latest/plugins/readme.html
+
+**Maintenance chart**
+
++--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Reviewer                      |   Release      |Test situation                  |
++--------------+-------------------------------+----------------+--------------------------------+
+|2025-02-13    | Maria Grimaldi                |  Sumac         |Pass.                           |
++--------------+-------------------------------+----------------+--------------------------------+

docs/index.rst

@@ -3,17 +3,18 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Open edX Filters's documentation!
-============================================
+Welcome to Open edX Filters's Documentation!
+#############################################
 
-Open edX Filters is a type of hook in the Hooks Extension Framework that allows extending the Open edX platform in a more stable and maintainable way. If you're new to this approach for extending Open edX, start by reading the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework` documentation. This documentation provides an overview of the framework's concepts and structure useful to support your adoption of Open edX Filters.
+Open edX Filters is a type of hook in the Hooks Extension Framework that allows extending the Open edX platform in a more stable and maintainable way. If you're new to this approach for extending Open edX, start by reading the :doc:`docs.openedx.org:developers/concepts/hooks_extension_framework` documentation.
+This documentation provides an overview of the framework's concepts and structure to support your adoption of Open edX Filters.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    concepts/index
-   decisions/index
+   reference/index
    how-tos/index
    quickstarts/index
-   reference/index
+   decisions/index

docs/reference/architecture-subdomains.rst

@@ -1,10 +1,10 @@
 Architecture Subdomains
-=======================
+########################
 
 Currently, these are the `architecture subdomains`_ used by the Open edX Events library:
 
 +-------------------+----------------------------------------------------------------------------------------------------+
-| Subdomain name    | Description                                                                                        |
+| Subdomain Name    | Description                                                                                        |
 +===================+====================================================================================================+
 | Content Authoring | Allows educators to create, modify, package, annotate (tag), and share learning content.           |
 +-------------------+----------------------------------------------------------------------------------------------------+
@@ -31,3 +31,11 @@ Here we list useful information about Open edX architecture subdomains and their
 .. _`Message Content Data Guidelines`: https://docs.openedx.org/projects/openedx-proposals/en/latest/architectural-decisions/oep-0041-arch-async-server-event-messaging.html?highlight=subdomain#message-content-data-guidelines
 .. _`Notes on events design and subdomains`: https://github.com/openedx/openedx-events/issues/72#issuecomment-1179291340
 .. _architecture subdomains: https://microservices.io/patterns/decomposition/decompose-by-subdomain.html
+
+**Maintenance chart**
+
++--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Reviewer                      |   Release      |Test situation                  |
++--------------+-------------------------------+----------------+--------------------------------+
+|2025-02-13    | Maria Grimaldi                |  Sumac         |Pass.                           |
++--------------+-------------------------------+----------------+--------------------------------+

docs/reference/django-plugins-and-filters.rst

@@ -1,22 +1,21 @@
 Django Plugins and Filters
 ##########################
 
-Django plugins is one of the most valuable extension mechanisms for the Open edX platform. In this section, we will
+Django plugins are one of the most valuable extension mechanisms for the Open edX platform. In this section, we will
 guide you through the process of using filters inside your own plugin.
 
 
-Use filters inside your plugin
+Use Filters Inside Your Plugin
 ******************************
 
-Imagine you have your own registration plugin and you want to add a filter to it. The first thing you need to do is
-adding ``openedx-filters`` to your requirements file. Then, you can import the registration filter and use it inside
-your registration flow as it's used in the LMS registration flow. You can even add your own filters to your registration,
-after implementing their definitions in your plugin.
+Imagine you have your own registration plugin, and you want to add a filter to it. The first thing you need to do is
+add ``openedx-filters`` to your requirements file. Then, you can import the registration filter and use it inside
+your registration flow as it is used in the LMS registration flow. After implementing their definitions in your plugin, you can even add your filters to your registration.
 
-Configure filters
+Configure Filters
 *****************
 
-Filters are configured in the ``OPEN_EDX_FILTERS_CONFIG`` dictionary which can be specified in your plugin's settings
+Filters are configured in the ``OPEN_EDX_FILTERS_CONFIG`` dictionary, which can be specified in your plugin's settings
 file. The dictionary has the following structure:
 
 .. code-block:: python
@@ -33,9 +32,18 @@ file. The dictionary has the following structure:
         },
     }
 
+To learm more about this, visit :doc:`/reference/filters-configuration`.
 
-Create pipeline steps
+Create Pipeline Steps
 *********************
 
-In your own plugin, you can create your own :term:`pipeline steps<Pipeline Step>` by inheriting from ``PipelineStep`` and implementing the
-``run_filter`` method. You can find examples of :term:`pipeline steps<Pipeline Step>` in the ``openedx-filters-samples`` repository. See :doc:`/quickstarts/index` for more details.
+In your plugin, you can create your own :term:`pipeline steps<Pipeline Step>` by inheriting from ``PipelineStep`` and implementing the
+``run_filter`` method. You can find examples of :term:`pipeline steps<Pipeline Step>` in the ``openedx-filters-samples`` repository. See :doc:`/quickstarts/index` for more details. To learn more about this process, visit :doc:`/how-tos/create-a-pipeline-step`.
+
+**Maintenance chart**
+
++--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Reviewer                      |   Release      |Test situation                  |
++--------------+-------------------------------+----------------+--------------------------------+
+|2025-02-13    | Maria Grimaldi                |  Sumac         |Pass.                           |
++--------------+-------------------------------+----------------+--------------------------------+

docs/reference/documenting-filters-classes.rst

@@ -1,17 +1,17 @@
 Documenting Open edX Filters Classes
-====================================
+######################################
 
-When creating a new filter, you should document the purpose of the filter in the docstring of the filter class. This will help other developers understand the purpose of the filter and how to use it.
+When creating a new filter, you should document the filter's purpose in the filter class's docstring. This will help other developers understand the purpose of the filter and how to use it.
 
 The docstring should comply with the following guidelines:
 
 - The docstring should be a triple-quoted string.
 - The docstring should be placed at the beginning of the class definition.
-- The docstring should include a brief description of what's supposed to do.
+- The docstring should include a brief description of what it is supposed to do.
 - The docstring should describe the purpose of the filter.
 - The docstring should include the filter type ``filter_type``, which is the unique identifier for the filter.
-- The docstring should include the trigger information, which includes the repository, path, and function or method that triggers the filter. If for some reason the filter is triggered by multiple functions or methods, you should list them all. If it's not triggered by any function or method, you should use NA (Not Applicable).
-- The docstring should include any other relevant information about the filter (e.g., it works only for legacy views not MFEs).
+- The docstring should include the trigger information, which includes the repository, path, and function or method that triggers the filter. If, for some reason, the filter is triggered by multiple functions or methods, you should list them all. If it is not triggered by any function or method, you should use NA (Not Applicable).
+- The docstring should include any other relevant information about the filter (e.g., it works only for legacy views, not MFEs).
 
 Consider the following example:
 
@@ -36,3 +36,11 @@ Consider the following example:
     Additional Information:
         This filter doesn't work alongside the account MFE, only with the legacy account settings page.
     """
+
+**Maintenance chart**
+
++--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Reviewer                      |   Release      |Test situation                  |
++--------------+-------------------------------+----------------+--------------------------------+
+|2025-02-13    | Maria Grimaldi                |  Sumac         |Pass.                           |
++--------------+-------------------------------+----------------+--------------------------------+