Skip to content

Commit

Permalink
docs: improve README and hows-to (#271)
Browse files Browse the repository at this point in the history 
* docs: improve writing

* docs: update README.rst

* docs: add how to

* docs: modify compatibility notes in readme

* docs: fix heading levels

* docs: fix plugin definition

* docs: update edx references

* docs: fix format and typos

* docs: update 0001-include-test-cases-files.rst

* docs: update middleware documentation

* docs: include feedback

* docs: add config changes note
  • Loading branch information
@dcoa
dcoa authored Jul 10, 2024
1 parent 623b6d9 commit 1506325
Show file tree
Hide file tree
Showing 10 changed files with 315 additions and 126 deletions.
128 changes: 67 additions & 61 deletions README.rst
View file
Original file line number Diff line number Diff line change
@@ -1,42 +1,59 @@
=======================
EOX core |build-status|
=======================

.. |build-status| image:: https://circleci.com/gh/eduNEXT/eox-core.svg?style=svg

Eox-core (A.K.A. Edunext Open extensions) is an `openedx plugin`_, for the `edx-platform`_ that adds multiple API
endpoints in order to extend the functionality of the `edx-platform`_ and avoid changing the base code directly. These
API endpoints includes bulk creation of pre-activated users (for example, skip sending an activation email), enrollments
and pre-enrollment operations.
========
EOX Core
========
|Maintainance Badge| |Test Badge| |PyPI Badge|

.. |Maintainance Badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen
:alt: Maintainance Status
.. |Test Badge| image:: https://img.shields.io/github/actions/workflow/status/edunext/eox-core/.github%2Fworkflows%2Ftests.yml?label=Test
:alt: GitHub Actions Workflow Test Status
.. |PyPI Badge| image:: https://img.shields.io/pypi/v/eox-core?label=PyPI
:alt: PyPI - Version

Eox-core is an `openedx plugin`_ for the `edx-platform`_, and part of the Edunext Open edX Extensions (aka EOX), that adds multiple API
endpoints to extend its functionality and avoid changing the base code directly. These
API endpoints include bulk creation of pre-activated users (for example, skip sending an activation email), enrollments, and pre-enrollment operations.

Installation
============

#. Add this plugin in your Tutor ``config.yml`` in the ``OPENEDX_EXTRA_PIP_REQUIREMENTS`` variable.
#. Save your configuration with ``tutor config save``.
#. Build your open edx image with ``tutor images build openedx``.
#. Add this plugin in your Tutor ``config.yml`` with the ``OPENEDX_EXTRA_PIP_REQUIREMENTS`` setting.

.. code-block:: yaml
OPENEDX_EXTRA_PIP_REQUIREMENTS:
- eox-core=={{version}} # basic installation
- eox-core{{requirements}}=={{version}} # requeriments e.g. [sentry,tpa]. Useful for integration with third-party applications.
#. Save the configuration with ``tutor config save``.
#. Build an open edx image with ``tutor images build openedx``.
#. Launch your platform with ``tutor local launch``.

**Note:** To use all the features, you need to have `the tutor-forum plugin <https://github.com/overhangio/tutor-forum>`_ and `the eox-tenant plugin <https://github.com/eduNEXT/eox-tenant>`_.

Features
=========
- Support redirections with middlewares.
- Add pipelines to be used with ``openedx-filters``.

- Support redirections with middleware.
- Add pipelines for authentication.
- Add a group of APIs.

.. image:: docs/_images/eox-core-apis.png
:alt: Eox-core APIs
.. image:: docs/_images/eox-core-apis.png
:alt: Eox-core APIs

Usage
=====

See the `How to section <https://github.com/eduNEXT/eox-core/tree/master/docs/how_to>`_ for guidance on middleware, pipeline and API usage.

You can find more information in `Help for devs doc <https://github.com/eduNEXT/eox-core/blob/master/docs/help_for_devs/0001-include-test-cases-files.rst>`_.

Compatibility Notes
--------------------

+------------------+--------------+
| Open edX Release | Version |
+==================+==============+
| Ironwood | < 3.0 |
| Ironwood | < 4.0 |
+------------------+--------------+
| Juniper | >= 3.0 < 5.0 |
+------------------+--------------+
Expand All @@ -57,65 +74,46 @@ Compatibility Notes
| Redwood | >= 10.5.0 |
+------------------+--------------+

**NOTE**: The Maple version does not support Django 2.2 but it does support Django 3.2 as of eox-core 7.0.

The following changes to the plugin settings are necessary. If the release you are looking for is
not listed, then the accumulation of changes from previous releases is enough.
⚠️ The Maple version does not support Django 2.2 but it does support Django 3.2 as of eox-core 7.0.

**Lilac**

.. code-block:: yaml
EOX_CORE_USERS_BACKEND: "eox_core.edxapp_wrapper.backends.users_l_v1"
EOX_CORE_PRE_ENROLLMENT_BACKEND: "eox_core.edxapp_wrapper.backends.pre_enrollment_l_v1"
EOX_CORE_ENROLLMENT_BACKEND: "eox_core.edxapp_wrapper.backends.enrollment_l_v1"
The plugin is configured for the latest release (Redwood). The following changes in the plugin settings should be applied in order to be used for previous releases.

**Maple**

.. code-block:: yaml
EOX_CORE_USERS_BACKEND: "eox_core.edxapp_wrapper.backends.users_m_v1"
EOX_CORE_PRE_ENROLLMENT_BACKEND: "eox_core.edxapp_wrapper.backends.pre_enrollment_l_v1"
EOX_CORE_ENROLLMENT_BACKEND: "eox_core.edxapp_wrapper.backends.enrollment_l_v1"
**Nutmeg**

.. code-block:: yaml
EOX_CORE_USERS_BACKEND: "eox_core.edxapp_wrapper.backends.users_m_v1"
EOX_CORE_PRE_ENROLLMENT_BACKEND: "eox_core.edxapp_wrapper.backends.pre_enrollment_l_v1"
EOX_CORE_ENROLLMENT_BACKEND: "eox_core.edxapp_wrapper.backends.enrollment_l_v1"
**Olive, Palm and Quince**
These settings can be changed in ``eox_core/settings/common.py`` or, in the instance settings.

.. code-block:: yaml

EOX_CORE_ENROLLMENT_BACKEND: "eox_core.edxapp_wrapper.backends.enrollment_o_v1"
🚨 If the release you are looking for is not listed, please note:

These settings can be changed in ``eox_core/settings/common.py`` or, for example, in ansible configurations.
- If the Open edX release is compatible with the current eox-core version (see `Compatibility Notes <https://github.com/eduNEXT/eox-core?tab=readme-ov-file#compatibility-notes>`_), the default configuration is sufficient.
- If incompatible, you can refer to the README from the relevant version tag for configuration details (e.g., `v6.2.1 README <https://github.com/eduNEXT/eox-core/blob/v6.2.1/README.rst>`_).

**NOTE**: the current ``common.py`` works with Open edX Redwood version.


Dependency Management
=====================

EOX core now follows OEP-18 so the correct way to update dependencies is to run ``make upgrade`` inside your virtualenv.


Integrations with third party services
======================================
Integrations with third-party services
--------------------------------------

The plugin offers some integrations listed below:

#. **Sentry**: This service allows to track the errors generated on edx-platform. Check more details in https://sentry.io/welcome/.
#. **Sentry**: This service allows tracking the errors generated on edx-platform. Check more details at https://sentry.io/welcome/.

To enable the integration, follow the steps below:

* Install the plugin with Sentry support (extras_require [sentry]).

* Sign up/in to your sentry account and create a new Django application integration.
* Sign up/in your sentry account and create a new Django application integration.

* Get the DSN for your integration. This is an unique identifier for your application.
* Get the DSN for your integration. This is a unique identifier for your application.

* Setup the following configuration values for edx-platform:

Expand All @@ -125,9 +123,9 @@ The plugin offers some integrations listed below:
EOX_CORE_SENTRY_IGNORED_ERRORS: [] # optional
EOX_CORE_SENTRY_EXTRA_OPTIONS: {} # optional
By default, **EOX_CORE_SENTRY_INTEGRATION_DSN** setting is None, which disables the sentry integration.
**EOX_CORE_SENTRY_IGNORED_ERRORS** is optional. It is a list of the exceptions you want to ignore. For instance, it can be defined as:
**EOX_CORE_SENTRY_EXTRA_OPTIONS** is optional. It is a dictionary with extra options to be passed to the sentry client. For instance, it can be defined as:
- **EOX_CORE_SENTRY_INTEGRATION_DSN:** By default the setting is None, which disables the sentry integration.
- **EOX_CORE_SENTRY_IGNORED_ERRORS:** List of the exceptions you want to ignore (see below for a reference).
- **EOX_CORE_SENTRY_EXTRA_OPTIONS** Dictionary with extra options to be passed to the sentry client. For instance, it can be defined as:

.. code-block:: yaml
Expand All @@ -140,28 +138,36 @@ The plugin offers some integrations listed below:
profiles_sample_rate: 0.5
another_client_parameter: 'value'
Auditing Django views
=====================

The majority of views in eox-core use an auditing decorator, defined in our custom library called `eox-audit-model`_,
that helps saving relevant information about non-idempotent operations. By default this functionality is turned on. To
Most views in eox-core use an auditing decorator, defined in our custom library, *eox-audit-model*,
that helps save relevant information about non-idempotent operations. By default, this functionality is turned on. To
check your auditing records go to Django sysadmin and find DJANGO EDUNEXT AUDIT MODEL.

For more information, check the eox-audit-model documentation.
You can check the `eox-audit-model`_ documentation for more information.

Development
===========

You can find more information about testing in the `Help for devs doc <https://github.com/eduNEXT/eox-core/blob/master/docs/help_for_devs/0001-include-test-cases-files.rst>`_.

.. _Open edX Devstack: https://github.com/edx/devstack/
.. _openedx plugin: https://github.com/edx/edx-platform/tree/master/openedx/core/djangoapps/plugins
.. _edx-platform: https://github.com/edx/edx-platform/
.. _openedx plugin: https://github.com/openedx/edx-platform/tree/master/openedx/core/djangoapps/plugins
.. _edx-platform: https://github.com/openedx/edx-platform/
.. _eox-tenant: https://github.com/eduNEXT/eox-tenant/
.. _eox-audit-model: https://github.com/eduNEXT/eox-audit-model/

How to Contribute
-----------------
=================

Contributions are welcome! See our `CONTRIBUTING`_ file for more
information – it also contains guidelines for how to maintain high code
quality, which will make your contribution more likely to be accepted.

.. _CONTRIBUTING: https://github.com/eduNEXT/eox-core/blob/master/CONTRIBUTING.rst


License
=======

This software is licensed under the terms of the AGPLv3. See the LICENSE file for details.
127 changes: 67 additions & 60 deletions docs/help_for_devs/0001-include-test-cases-files.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,81 +5,88 @@ Eox-core test cases
Context
-------

In order to have a way to test the eox-core API endpoints manually, but quickly, two json files have been
created with the GET, POST, PATCH and DELETE requests. The `Eox-core-test.postman_collection.json`_ and
`Eox-core-test.postman_environment.json`_ files were created with the `Posman`_ application.
To have a way to test the eox-core API endpoints manually, but quickly, two JSON files have been
created with GET, POST, PATCH, and DELETE requests. The `Eox-core Test Collection`_ and
`Eox-core Test Environment`_ files were created for the `Postman`_ application.

.. _eox-core-test.postman_collection.json: ../resources/Eox-core-test.postman_collection.json
.. _eox-core-test.postman_environment.json: ../resources/Eox-core-test.postman_environment.json
.. _Posman: https://www.postman.com/
.. _Eox-core Test Collection: ../resources/eox-core-test.postman_collection.json
.. _Eox-core Test Environment: ../resources/eox-core-test.postman_environment.json
.. _Postman: https://www.postman.com/

Instructions
------------

To test the endpoints it is necessary to have the Open Edx platform running with the eox-core plugin installed.
To properly test the endpoints, the Open Edx platform must be running with the eox-core plugin installed.

#. Once your environment is set up, create a new admin user: ``tutor dev do createuser --staf --superuser admin <custom-mail> --password <password>``.
#. Log into Django's admin site using the user created in the previous step.
#. Create a testing user without staff permissions, you could do this in the Django admin page. Some of the test will require you to be staff user, specifically those for the support API. In case you want to run the test collection once, then user your admin user and skip the permission assignment steps.
#. On the Site Administration panel go to *Authentication and Authorization* > *Users*.
#. Click on the testing user created on the third step.
#. Go to User permissions and look for auth **user** *can access eox-core API* and add it with a double click or one click and right arrow.
#. Once your environment is set up, create a new admin user: ``tutor dev do createuser --staff --superuser admin <custom-mail> --password <password>``.
#. Log into Django's admin site with the user created in the previous step.
#. Create a testing user without staff permissions, you could do this on the Django admin page.

🚨 Some of the tests will require a staff user, specifically those for the support API; if you want to run the test collection at once, use the
admin user and skip the permission assignment steps.

#. On the Site Administration Panel, go to *Authentication and Authorization* > *Users*.
#. Click on the testing user created by the third step.
#. Go to User Permissions, search for ``auth | user | Can access eox-core API`` and add it with a double click or one click and the right arrow.
#. Click Save at the bottom of the page.
#. On the Site Administration panel go to *Django Oauth Toolkit* > *Applications*.
#. You should be redirected to a table with a bunch of applications and on the right upper corner there's a button to Add *Application*, click on it.
#. Once again, you should be redirected to a new page with a bunch of blank spaces, nevertheless, *client id* and *client secret* are given. Save them, as you will need these later.
#. Fill the left spaces with the following rules:
#. On the Site Administration panel, go to *Django Oauth Toolkit* > *Applications*.
#. Once there, in the right-upper corner, you will find the *Add Application* button, click on it.
#. You should be redirected to a new page with a bunch of blank spaces, nevertheless, *client id* and *client secret* are given. Save them, as you will need them later.
#. Fill the blank spaces with the following rules:

- For *User id* click on the magnifier icon next to the blank space, a window should show up with the app's users, pick the one you created for tests.
- On the *Redirect to URL* section add your app's url.
- Pick *Confidential* on the *Client type* dropdown menu.
- Pick *Client credentials* for *Authorization grant type*.
- Add a custom *name*.
- For *User id* click on the magnifying glass icon, and a window should appear with the app's users. Select the one you created for testing.
- On the *Redirect to URL* section add your app URL.
- Pick *Confidential* on the *Client type* dropdown menu.
- Pick *Client credentials* for *Authorization grant type*.
- Add a custom *name*.

#. Once everything is filled, click Save.
#. In this test the desktop Postman application was used. Postman for Linux Version 8.12.5.
#. Download the json files with the test (collection and environment).
#. On *import* > *upload files*, upload the json files. Once it's uploaded, it should be shown in *Collections* and *Environments* menu.
#. For *Collections*, there should be an arrow on the left side of the name, click on it to extend the content. The file consists of 3 folders:

- Main API
* User
+ Create user
+ Get user
+ Update user
* Enrollment
+ Create enrollment
+ Get enrollment
+ Update enrollment
+ Delete enrollment
+ Create enrollment to test grade
* Pre enrollment
+ Create whitelistings
+ Get regular pre-enrollment
+ Update whitelistings
+ Delete pre-enrollment
* Grade
+ Grade information
* User info
+ Get user related to the authorization token
- Task dispatcher API
+ Get task
+ Dispatch a task
+ Check the status
- Support API
+ Update username
+ Delete User
#. Open the desktop Postman application. and load the test collection and environment provided. On *import* > *upload files*, add the JSON files.
Once it's uploaded, it should be shown in the *Collections* and *Environments* menu.
#. For *Collections*, there should be an arrow on the left side of the name, click on it to extend the content. The file structure:

plus an Authorization section. Click on the last one.
.. code-block::
Eox-core
|
├── Main API
│ ├── User
│ │ ├── Create user
│ │ ├── Get user
│ │ └── Update user
│ ├── Enrollment
│ │ ├── Create enrollment
│ │ ├── Get enrollment
│ │ ├── Update enrollment
│ │ ├── Delete enrollment
│ │ └── Create enrollment to test grade
│ ├── Pre-enrollment
│ │ ├── Create whitelisting
│ │ ├── Get regular pre-enrollment
│ │ ├── Update whitelisting
│ │ └── Delete pre-enrollment
│ ├── Grade
│ │ └── Grade information
│ └── User info
│ └── Get user related to the authorization token
├── Task dispatcher API
│ ├── Get task
│ ├── Dispatch a task
│ └── Check the status
├── Support API
│ ├── Update username
│ └── Delete User
└── Authentication
#. More in depth information about the Authorization section should be now displayed on the right side panel. It looks more familiar to a traditional postman request. Go to the body and a table with 3 keys with their values should be displayed. Change this values in Environment.
#. For *Environment* a table on the right panel should appear with the following headers: *variable*, *initial value*, *current value*. Change the *client_id* and *client_secret* with those values retrieved from the *Django Oauth Toolkit*.
#. Open the Authentication POST request and go to the body, a table with 3 keys and values should be displayed. Those values must be updated with the eox-core Environment.
#. For *Environment* a table on the right panel should appear with the following headers: *variable*, *initial value* and *current value*. Modify the *client_id* and
*client_secret* with those values retrieved from the *Django Oauth Toolkit*.

.. image:: ../resources/variables_env.png
.. image:: ../resources/variables_env.png
:height: 300
:width: 900
:alt: Environment variable

#. Edit all variables except token and task_id, these are auto-generated
#. Once again, pick the uploaded files in the Collections panel.
#. On the right top side of the app, make sure your environment with the variables is chosen, if so click on the three dots shown when hovering the file's name and click on run collection. This should run all the tests at once and the result will be shown on the right panel.
#. Go back to the to Collection panel.
#. On the right-top side of the app, make sure eox-core environment is chosen and updated, if so click on the three dots shown when hovering over the file's name and click on *Run collection*. This should carry out all the tests at once and the result will be displayed.
Loading

0 comments on commit 1506325

Please sign in to comment.