Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: improve documentation to explain the actual plugin behavior #105

Merged
merged 7 commits into from
Jul 10, 2024
Merged

docs: improve documentation to explain the actual plugin behavior #105

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
ee7e6a7
docs: update edx references
dcoa Jun 12, 2024
c43fe0f
docs: improve writing and formatting
dcoa Jun 12, 2024
42bc898
docs: update compatibility notes and remove eox-core because is being…
dcoa Jun 19, 2024
c6cdace
docs: remove redundant build image
dcoa Jun 24, 2024
ae993c5
docs: improve installation section
dcoa Jun 26, 2024
ad47cfc
docs: update plugin config changes
dcoa Jul 8, 2024
9a81f63
docs: fix typo eox_tagging/settings/test.py
dcoa Jul 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
204 changes: 82 additions & 122 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,118 +1,72 @@
=============
eox_tagging
=============

Eox-tagging (A.K.A. Edunext Open extensions) is an `openedx plugin`_, that adds the capability
===========
EOX Tagging
===========
|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-tagging/.github%2Fworkflows%2Ftests.yml?label=Test
:alt: GitHub Actions Workflow Test Status
.. |PyPI Badge| image:: https://img.shields.io/pypi/v/eox-tagging?label=PyPI
:alt: PyPI - Version

Eox-tagging is an `openedx plugin`_, part of the Edunext Open Extensions (aka EOX), that adds the capability
to tag `edx-platform`_ objects. These tags can be used to categorize, include extra information, and so on.

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

Open edX devstack
------------------

- Install a supported version of the `Open edX devstack`_. See versions for more details.

- Clone the git repo:

.. code-block:: bash

cd ~/Documents/eoxstack/src/ # Assuming that devstack is in ~/Documents/eoxstack/devstack/
sudo mkdir edxapp
cd edxapp
git clone [email protected]:eduNEXT/eox-tagging.git

- Install plugin from your server (in this case the devstack docker lms shell):

.. code-block:: bash
#. Install a new fresh instance of tutor following `this steps <https://docs.tutor.overhang.io/quickstart.html#quickstart-1-click-install>`_. *If your instance is running, you can skip this step.*
#. Add to the Tutor configuration in the file ``cat "$(tutor config printroot)/config.yml"`` these lines that install eox-tagging lib:
dcoa marked this conversation as resolved.
Show resolved Hide resolved

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's use the same structure as in eox-tenant:

#. Add this plugin in your Tutor ``config.yml`` with the ``OPENEDX_EXTRA_PIP_REQUIREMENTS`` setting.

   .. code-block:: yaml
      
      OPENEDX_EXTRA_PIP_REQUIREMENTS:
         - eox-tagging=={{version}}
         
#. Save the configuration with ``tutor config save``.
#. Build the image and launch your platform with ``tutor local launch``.

cd ~/Documents/eoxstack/devstack # Change for your devstack path (if you are using devstack)
make lms-shell # Enter the devstack machine (or server where lms process lives)
cd /edx/src/edxapp/eox-tagging
pip install -e .
python manage.py lms migrate eox_tagging --settings=<your app settings>

Open edX with Tutor (Maple)
----------------------------
If you are using `Tutor <https://docs.tutor.overhang.io/gettingstarted.html>`_ to deploy the Open edX instance, please follow this steps:

#. Install a new fresh instance of tutor following `this steps <https://docs.tutor.overhang.io/quickstart.html#quickstart-1-click-install>`_. *If you already have a tutor instance running you can skip this step.*
#. Add to the Tutor configuration in the file ``cat "$(tutor config printroot)/config.yml"`` this lines that install eox-tagging and eox-core lib:
.. code-block:: yaml

OPENEDX_EXTRA_PIP_REQUIREMENTS:
- eox_core
- eox_tagging
#. Create a new tutor plugin that adds this settings to openedx common settings:
.. code-block:: yaml

EOX_TAGGING_GET_ENROLLMENT_OBJECT = "eox_tagging.edxapp_wrappers.backends.enrollment_l_v1"
EOX_CORE_USERS_BACKEND = "eox_core.edxapp_wrapper.backends.users_m_v1"

.. note::
`Here <https://github.com/eduNEXT/eox-tagging/issues/83>`_ is an example of creating a tutor plugin with a yaml file.
But there are other ways to create tutor plugins, please go to tutor docs and see how to add settings in Open edX common settings.
#. Install the plugin doing ``tutor plugins enable eox-tagging-plugin`` and then ``tutor config save``.
#. Build the openedx image doing ``tutor images build openedx``.
#. Start the tutor instance with the new config doing ``tutor local quickstart``.
#. All set to use eox-tagging lib!
#. Build the docker image and start the tutor instance with ``tutor local launch``.

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

+-------------------+----------------+
| Open edX Release | Version |
+===================+================+
| Ironwood | < 0.9 < 3.0 |
+-------------------+----------------+
| Juniper | >= 0.9 < 3.0 |
+-------------------+----------------+
| Koa | >= 2.2 < 5.0 |
+-------------------+----------------+
| Lilac | >= 2.2 < 5.0 |
+-------------------+----------------+
| Maple | >= 4.0 < 6.0 |
+-------------------+----------------+
| Nutmeg | >= 5.0 < 6.0 |
+-------------------+----------------+
| Olive | >= 5.0 < 6.0 |
+-------------------+----------------+
| Palm | >= 6.0 |
+-------------------+----------------+
| Quince | >= 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.

**Ironwood**

magajh marked this conversation as resolved.
Show resolved Hide resolved
.. code-block:: yaml

EOX_TAGGING_GET_ENROLLMENT_OBJECT: "eox_tagging.edxapp_wrappers.backends.enrollment_i_v1"
EOX_TAGGING_GET_COURSE_OVERVIEW: "eox_tagging.edxapp_wrappers.backends.course_overview_i_v1"
EOX_TAGGING_BEARER_AUTHENTICATION: "eox_tagging.edxapp_wrappers.backends.bearer_authentication_i_v1"

**Koa, Lilac, Maple, Nutmeg, Olive, Palm and Quince**

.. code-block:: yaml

EOX_TAGGING_GET_ENROLLMENT_OBJECT: "eox_tagging.edxapp_wrappers.backends.enrollment_l_v1"


Those settings can be changed in ``eox_tagging/settings/common.py`` or, for example, in ansible configurations.

**NOTE**: the current ``common.py`` works with Open edX Lilac version.
+------------------+--------------+
| Open edX Release | Version |
+==================+==============+
| Ironwood | < 0.9 < 3.0 |
+------------------+--------------+
| Juniper | >= 0.9 < 3.0 |
+------------------+--------------+
| Koa | >= 2.2 < 5.0 |
+------------------+--------------+
| Lilac | >= 2.2 < 5.0 |
+------------------+--------------+
| Maple | >= 4.0 < 6.0 |
+------------------+--------------+
| Nutmeg | >= 5.0 < 6.0 |
+------------------+--------------+
| Olive | >= 5.0 < 6.0 |
+------------------+--------------+
| Palm | >= 6.0 |
+------------------+--------------+
| Quince | >= 7.0 |
+------------------+--------------+

The plugin is configured for the latest release (Quince).

We will list here the changes in the plugin settings that should be applied to be used for previous releases. If the release you are looking for is not listed,
the actual configuration is sufficient or incompatible with the current eox-tagging version.

If you are installing a previous version, please refer to the tag to verify the configuration that should be applied.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same here:

Suggested change
The plugin is configured for the latest release (Quince).
We will list here the changes in the plugin settings that should be applied to be used for previous releases. If the release you are looking for is not listed,
the actual configuration is sufficient or incompatible with the current eox-tagging version.
If you are installing a previous version, please refer to the tag to verify the configuration that should be applied.
The plugin is configured for the latest release (Quince). The following changes in the plugin settings should be applied to be used for previous releases.
If the release you are looking for is not listed, the actual configuration is sufficient or it is incompatible with the current eox-tagging version.

Usage
======

See the `How to section <https://github.com/eduNEXT/eox-tagging/tree/master/docs/how_to>`_ for a detailed guidance on: Model, configurations and API usage.
See the `How to section <https://github.com/eduNEXT/eox-tagging/tree/master/docs/how_to>`_ for detailed guidance on model, configurations and API usage.

Important notes:
----------------
magajh marked this conversation as resolved.
Show resolved Hide resolved

* All the comparison with string objects are case insensitive.
* All the comparisons with string objects are case insensitive.
* If a tag owner is not defined, then it is assumed to be the site.

Examples
Expand All @@ -123,18 +77,18 @@ Examples
.. code-block:: JSON

{
"validate_tag_value":{
"in":[
"validate_tag_value": {
"in": [
"example_tag_value",
"example_tag_value_1"
]
},
"validate_access":{
"equals":"PRIVATE"
"validate_access": {
"equals": "PRIVATE"
},
"validate_target_object":"OpaqueKeyProxyModel",
"owner_object":"User",
"tag_type":"tag_by_example"
"validate_target_object": "OpaqueKeyProxyModel",
"owner_object": "User",
"tag_type": "tag_by_example"
}

This means that:
Expand All @@ -150,12 +104,12 @@ This means that:
.. code-block:: JSON

{
"validate_tag_value":{
"exist":true
"validate_tag_value": {
"exist": true
},
"validate_access":"Public",
"validate_target_object":"User",
"tag_type":"tag_by_edunext"
"validate_access": "Public",
"validate_target_object": "User",
"tag_type": "tag_by_edunext"
}

This means that:
Expand All @@ -170,18 +124,18 @@ This means that:
.. code-block:: JSON

{
"validate_tag_value":"tag_value",
"validate_access":{
"in":[
"validate_tag_value": "tag_value",
"validate_access": {
"in": [
"Private",
"Public"
]
},
"validate_target_object":"CourseEnrollment",
"tag_type":"tag_by_edunext",
"validate_activation_date":{
"exist":true,
"in":[
"validate_target_object": "CourseEnrollment",
"tag_type": "tag_by_edunext",
"validate_activation_date": {
"exist": true,
"in": [
"Dec 04 2020 10:30:40",
"Oct 19 2020 10:30:40"
]
Expand All @@ -194,14 +148,14 @@ This means that:
* The field access can be `private` or `public`.
* The target type must be equal to `CourseEnrollment`
* Tag type must be equal to tag_by_edunext.
* The tag activation date must exist and be between the values defined in the array. This means: value_1 <= activation_date <= value_2.
* The tag activation date must exist between the values defined in the array. This means, value_1 <= activation_date <= value_2.
The array must be sorted or a validation error will be raised.

Tagging REST API
================

Get list of tags
----------------
Get a list of tags
------------------

**Request**

Expand Down Expand Up @@ -324,19 +278,19 @@ Filters example usage:

``/eox_tagging/api/v1/tags/?enrollments=COURSE_ID``

Auditing Django views (Optional in Maple)
=========================================
Auditing Django views
=====================

The majority of views in eox-tagging 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
check your auditing records go to Django sysadmin and find DJANGO EDUNEXT AUDIT MODEL.
that helps save relevant information about non-idempotent operations. By default, this functionality is turned off, to enable it, install eox-audit-model.

Check your auditing records in *Django sysadmin > DJANGO EDUNEXT AUDIT MODEL*.

For more information, check the eox-audit-model documentation.


.. _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-audit-model: https://github.com/eduNEXT/eox-audit-model/

How to Contribute
Expand All @@ -347,3 +301,9 @@ 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-tagging/blob/master/CONTRIBUTING.rst


License
=======

This project is licensed under the AGPL-3.0 License. See the LICENSE file for details.
Loading
Loading