From ee7e6a7a160201c2f977188ad4b319d758df7ba3 Mon Sep 17 00:00:00 2001 From: Diana Catalina Olarte Date: Wed, 12 Jun 2024 16:22:02 +1000 Subject: [PATCH 1/7] docs: update edx references --- README.rst | 82 +++++++++------------------------- eox_tagging/settings/common.py | 2 +- 2 files changed, 23 insertions(+), 61 deletions(-) diff --git a/README.rst b/README.rst index 09cc60f..af6d363 100644 --- a/README.rst +++ b/README.rst @@ -1,61 +1,24 @@ -============= -eox_tagging -============= +=========== +EOX Tagging +=========== -Eox-tagging (A.K.A. Edunext Open extensions) is an `openedx plugin`_, that adds the capability +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 new fresh instance of tutor following `this steps `_. *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 and eox-core lib: -- 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 git@github.com:eduNEXT/eox-tagging.git - -- Install plugin from your server (in this case the devstack docker lms shell): - -.. code-block:: bash - - 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= - -Open edX with Tutor (Maple) ----------------------------- -If you are using `Tutor `_ to deploy the Open edX instance, please follow this steps: - -#. Install a new fresh instance of tutor following `this steps `_. *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 `_ 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 openedx image by doing ``tutor images build openedx``. +#. Start the tutor instance with ``tutor local launch``. Compatibility Notes -------------------- @@ -107,12 +70,12 @@ Those settings can be changed in ``eox_tagging/settings/common.py`` or, for exam Usage ====== -See the `How to section `_ for a detailed guidance on: Model, configurations and API usage. +See the `How to section `_ for detailed guidance on Model, configurations and API usage. Important notes: ---------------- -* 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 @@ -151,11 +114,11 @@ This means that: { "validate_tag_value":{ - "exist":true + "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: @@ -170,17 +133,17 @@ 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", + "validate_target_object": "CourseEnrollment", "tag_type":"tag_by_edunext", "validate_activation_date":{ - "exist":true, + "exist": true, "in":[ "Dec 04 2020 10:30:40", "Oct 19 2020 10:30:40" @@ -328,15 +291,14 @@ Auditing Django views (Optional in Maple) ========================================= 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 +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. -.. _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 diff --git a/eox_tagging/settings/common.py b/eox_tagging/settings/common.py index 455c1c0..26754ef 100644 --- a/eox_tagging/settings/common.py +++ b/eox_tagging/settings/common.py @@ -50,7 +50,7 @@ def plugin_settings(settings): """ Set of plugin settings used by the Open Edx platform. - More info: https://github.com/edx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst + More info: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst """ # Plugin settings settings.EOX_TAGGING_GET_ENROLLMENT_OBJECT = "eox_tagging.edxapp_wrappers.backends.enrollment_l_v1" From c43fe0fb61304b7735354ee33743dded7d8d1f54 Mon Sep 17 00:00:00 2001 From: Diana Catalina Olarte Date: Wed, 12 Jun 2024 18:17:21 +1000 Subject: [PATCH 2/7] docs: improve writing and formatting --- README.rst | 101 +++++++++++++++------------ docs/how_to/api.rst | 126 +++++++++++++++++----------------- docs/how_to/configuration.rst | 42 ++++++------ docs/how_to/model.rst | 52 +++++++------- 4 files changed, 168 insertions(+), 153 deletions(-) diff --git a/README.rst b/README.rst index af6d363..543f04e 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,14 @@ =========== 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. @@ -23,27 +31,27 @@ Installation 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 | -+-------------------+----------------+ ++------------------+--------------+ +| 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. @@ -56,21 +64,21 @@ not listed, then the accumulation of changes from previous releases is enough. 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** +**Koa, Lilac, Maple, Nutmeg, Olive** .. 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. +Those settings can be changed in ``eox_tagging/settings/common.py`` or the instance settings. -**NOTE**: the current ``common.py`` works with Open edX Lilac version. +**NOTE**: the current ``common.py`` works with Open edX Quince and Palm versions. Usage ====== -See the `How to section `_ for detailed guidance on Model, configurations and API usage. +See the `How to section `_ for detailed guidance on model, configurations and API usage. Important notes: ---------------- @@ -86,18 +94,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: @@ -113,7 +121,7 @@ This means that: .. code-block:: JSON { - "validate_tag_value":{ + "validate_tag_value": { "exist": true }, "validate_access": "Public", @@ -141,10 +149,10 @@ This means that: ] }, "validate_target_object": "CourseEnrollment", - "tag_type":"tag_by_edunext", - "validate_activation_date":{ + "tag_type": "tag_by_edunext", + "validate_activation_date": { "exist": true, - "in":[ + "in": [ "Dec 04 2020 10:30:40", "Oct 19 2020 10:30:40" ] @@ -157,14 +165,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** @@ -287,12 +295,13 @@ 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 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. +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. @@ -309,3 +318,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. \ No newline at end of file diff --git a/docs/how_to/api.rst b/docs/how_to/api.rst index bc2e130..3ed134c 100644 --- a/docs/how_to/api.rst +++ b/docs/how_to/api.rst @@ -10,13 +10,13 @@ Currently, to be able to use the API, the user must be authenticated. One of the any request to the tagging API. In the future, public -limited- access will be provided. As mentioned above, an authorization token can be provided as an Authorization HTTP header when calling the API. -If not, then the session authentication will be use. If any of this authentications work then the user won't be able to make any +If not, then the session authentication will be used. If any of these authentications work then the user won't be able to make any successful API call. API permission ^^^^^^^^^^^^^^^ -If a user wants to make API calls, in addition to being authenticated must have the custom eox-tagging permission so can make any write/read operations. -This permission iscalled `can_call_eox_tagging`. +If a user wants to make API calls, in addition to being authenticated, must have the custom eox-tagging permission so can make any write/read operations. +This permission is called `can_call_eox_tagging`. Possible API calls @@ -24,80 +24,80 @@ Possible API calls The tags are `immutable` by definition, so after creating a tag the only calls allowed are to list, get details and delete tags. -+---------------------------------+---------------------------------------------------+ -| Name | Description | -+=================================+===================================================+ -| list | Used to list all tags owned by the user making the| -| | API call. If the owner does not have any tags | -| | created yet, an empty set will be returned. | -+---------------------------------+---------------------------------------------------+ -| details | Used to get the information of a single tag. If | -| | the tag does not exist it returns Not Found. | -+---------------------------------+---------------------------------------------------+ -| delete | Used to deactivate an active tag. This implements | -| | a soft delete operation. | -+---------------------------------+---------------------------------------------------+ -| create | Used to create a tag. | -+---------------------------------+---------------------------------------------------+ ++---------+----------------------------------------------------+ +| Name | Description | ++=========+====================================================+ +| list | Used to list all tags owned by the user making the | +| | API call. If the owner does not have any tags | +| | created yet, an empty set will be returned. | ++---------+----------------------------------------------------+ +| details | Used to get the information of a single tag. If | +| | the tag does not exist it returns Not Found. | ++---------+----------------------------------------------------+ +| delete | Used to deactivate an active tag. This implements | +| | a soft delete operation. | ++---------+----------------------------------------------------+ +| create | Used to create a tag. | ++---------+----------------------------------------------------+ Serializer fields ------------------ -When creating a tag, this are the fields expected: - -+----------------------------------+--------------------------------------------------+------------------+ -| Field Name | Description | Required | -+==================================+==================================================+==================+ -| tag_type | Works as the class of the tag. | Yes | -+----------------------------------+--------------------------------------------------+------------------+ -| tag_value | It can be thought as the class instance. | Yes | -+----------------------------------+--------------------------------------------------+------------------+ -| access | Access level of the tag. | Yes | -+----------------------------------+--------------------------------------------------+------------------+ -| activation_date | Datetime when the tag will be activated. | No | -| | It can have UTC format or Year-Month-Day H:M:S | | -+----------------------------------+--------------------------------------------------+------------------+ -| expiration_date | Datetime when the tag will be deactivated. | No | -| | It can have UTC format or Year-Month-Day H:M:S | | -+----------------------------------+--------------------------------------------------+------------------+ -| target_type | Type of the target. Must be equal to: user, site,| Yes | -| | courseoverview or courseenrollment. | | -+----------------------------------+--------------------------------------------------+------------------+ -| target_id | ID of the target with type target_type. | Yes | -+----------------------------------+--------------------------------------------------+------------------+ -| owner_type | Type of the tag owner. If omitted, site will be | No | -| | as the owner | | -+----------------------------------+--------------------------------------------------+------------------+ - -When retrieving objects, the JSON object will have the following fields (the mentioned above and): - -+----------------------------------+---------------------------------------------------+ -| Field Name | Description | -+==================================+===================================================+ -| meta | Field with technical information, like dates and | -| | information about the target and the owner. | -+----------------------------------+---------------------------------------------------+ -| status | Status of the tag. This could be active or | -| | inactive. | -+----------------------------------+---------------------------------------------------+ -| key | UUID Public identifier. | -+----------------------------------+---------------------------------------------------+ +When creating a tag, these are the fields expected: + ++-----------------+--------------------------------------------------+----------+ +| Field Name | Description | Required | ++=================+==================================================+==========+ +| tag_type | Works as the class of the tag. | Yes | ++-----------------+--------------------------------------------------+----------+ +| tag_value | It can be thought as the class instance. | Yes | ++-----------------+--------------------------------------------------+----------+ +| access | Access level of the tag. | Yes | ++-----------------+--------------------------------------------------+----------+ +| activation_date | Datetime when the tag will be activated. | No | +| | It can have UTC format or Year-Month-Day H:M:S | | ++-----------------+--------------------------------------------------+----------+ +| expiration_date | Datetime when the tag will be deactivated. | No | +| | It can have UTC format or Year-Month-Day H:M:S | | ++-----------------+--------------------------------------------------+----------+ +| target_type | Type of the target. Must be equal to: user, site,| Yes | +| | courseoverview or courseenrollment. | | ++-----------------+--------------------------------------------------+----------+ +| target_id | ID of the target with type target_type. | Yes | ++-----------------+--------------------------------------------------+----------+ +| owner_type | Type of the tag owner. If omitted, site will be | No | +| | as the owner | | ++-----------------+--------------------------------------------------+----------+ + +When retrieving objects, the JSON object will have the following fields (and the mentioned above): + ++------------+---------------------------------------------------+ +| Field Name | Description | ++============+===================================================+ +| meta | Field with technical information, like dates and | +| | information about the target and the owner. | ++------------+---------------------------------------------------+ +| status | Status of the tag. This could be active or | +| | inactive. | ++------------+---------------------------------------------------+ +| key | UUID Public identifier. | ++------------+---------------------------------------------------+ Validations ----------- -During the creation process starts, it's checked that ``target_type`` exists, if not then the creation process is interrupted and an error -will be raised. This results in returning an object describing the error ocurred. After checking if the target_type exists, the model validations +The creation process check that ``target_type`` exists, if not this is interrupted and an error +will be raised, returning an object describing the error that occurred. After checking if the target_type exists, the model validations will be performed and if an error occurs the error message will be returned in a response instead of valid data. Examples -------- -Get list of tags -^^^^^^^^^^^^^^^^ +Get a list of tags +^^^^^^^^^^^^^^^^^^ **Request** @@ -129,7 +129,7 @@ Get list of tags } Create tag -^^^^^^^^^^^^^^^^ +^^^^^^^^^^ **Request** @@ -170,7 +170,7 @@ Where TAG_DATA: } Delete tag -^^^^^^^^^^^^^^^^ +^^^^^^^^^^ **Request** diff --git a/docs/how_to/configuration.rst b/docs/how_to/configuration.rst index 3f5c113..e368caa 100644 --- a/docs/how_to/configuration.rst +++ b/docs/how_to/configuration.rst @@ -24,7 +24,7 @@ Where can be any editable tag field, and any of the de Validations ^^^^^^^^^^^ -Here's how to create validated fields, first, add the key validate_ to the configuration dictionary, where: +Here's how to create validated fields, first, add the key ``validate_`` to the configuration dictionary, where: * The FIELD_VALUE must be a Tag field, if not an exception will be raised. @@ -133,18 +133,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: @@ -160,12 +160,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: @@ -180,18 +180,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" ] diff --git a/docs/how_to/model.rst b/docs/how_to/model.rst index 6a30a31..f81858c 100644 --- a/docs/how_to/model.rst +++ b/docs/how_to/model.rst @@ -9,32 +9,32 @@ A tag is an object created over a specified target by an entity called owner. Th Attributes ----------- -+--------------------------+----------------------------------------------------------------------------+ -| Name | Description | -+==========================+============================================================================+ -| tag_type | This attribute works as a category, it can be for example: | -| | `subscription_tier`. | -+--------------------------+----------------------------------------------------------------------------+ -| tag_value | Contains the value of the tag. This would be for `subscription_tier` | -| | the value `free`. | -+--------------------------+----------------------------------------------------------------------------+ -| access | The access level for the tag, it can be public, private and protected. This| -| | this defines the visibility of the tag to the users. The default is public.| -+--------------------------+----------------------------------------------------------------------------+ -| activation_date | Datetime when the tag will be activated. | -+--------------------------+----------------------------------------------------------------------------+ -| expiration_date | Datetime when the tag will be deactivated. | -+--------------------------+----------------------------------------------------------------------------+ -| created_at | Creation date. | -+--------------------------+----------------------------------------------------------------------------+ -| status | Current tag status, when created is ACTIVE, and when is deleted becomes | -| | an inactive tag. | -+--------------------------+----------------------------------------------------------------------------+ -| target_object | Represents the tag target, this can be a user, courseenrollment, site or | -| | course. | -+--------------------------+----------------------------------------------------------------------------+ -| owner_object | Represents the tag owner. This can be a user or site. | -+--------------------------+----------------------------------------------------------------------------+ ++-----------------+----------------------------------------------------------------------------+ +| Name | Description | ++=================+============================================================================+ +| tag_type | This attribute works as a category, it can be for example: | +| | `subscription_tier`. | ++-----------------+----------------------------------------------------------------------------+ +| tag_value | Contains the value of the tag. This would be for `subscription_tier` | +| | the value `free`. | ++-----------------+----------------------------------------------------------------------------+ +| access | The access level for the tag, it can be public, private and protected. This| +| | this defines the visibility of the tag to the users. The default is public.| ++-----------------+----------------------------------------------------------------------------+ +| activation_date | Datetime when the tag will be activated. | ++-----------------+----------------------------------------------------------------------------+ +| expiration_date | Datetime when the tag will be deactivated. | ++-----------------+----------------------------------------------------------------------------+ +| created_at | Creation date. | ++-----------------+----------------------------------------------------------------------------+ +| status | Current tag status, when created is ACTIVE, and when is deleted becomes | +| | an inactive tag. | ++-----------------+----------------------------------------------------------------------------+ +| target_object | Represents the tag target, this can be a user, courseenrollment, site or | +| | course. | ++-----------------+----------------------------------------------------------------------------+ +| owner_object | Represents the tag owner. This can be a user or site. | ++-----------------+----------------------------------------------------------------------------+ Validations From 42bc898a4631d8bb73a80f4c1b33e90e64e7de5e Mon Sep 17 00:00:00 2001 From: Diana Catalina Olarte Date: Wed, 19 Jun 2024 18:36:38 +1000 Subject: [PATCH 3/7] docs: update compatibility notes and remove eox-core because is being installed as dependency --- README.rst | 28 ++++++---------------------- eox_tagging/settings/production.py | 2 +- eox_tagging/settings/test.py | 2 +- 3 files changed, 8 insertions(+), 24 deletions(-) diff --git a/README.rst b/README.rst index 543f04e..f856c4f 100644 --- a/README.rst +++ b/README.rst @@ -17,12 +17,11 @@ Installation ============ #. Install a new fresh instance of tutor following `this steps `_. *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 and eox-core lib: +#. Add to the Tutor configuration in the file ``cat "$(tutor config printroot)/config.yml"`` these lines that install eox-tagging lib: .. code-block:: yaml OPENEDX_EXTRA_PIP_REQUIREMENTS: - - eox_core - eox_tagging #. Build the openedx image by doing ``tutor images build openedx``. @@ -53,27 +52,12 @@ Compatibility Notes | 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. +The plugin is configured for the latest release (Quince). -**Ironwood** +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. -.. 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** - -.. 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 the instance settings. - -**NOTE**: the current ``common.py`` works with Open edX Quince and Palm versions. +If you are installing a previous version, please refer to the tag to verify the configuration that should be applied. Usage ====== @@ -323,4 +307,4 @@ quality, which will make your contribution more likely to be accepted. License ======= -This project is licensed under the AGPL-3.0 License. See the LICENSE file for details. \ No newline at end of file +This project is licensed under the AGPL-3.0 License. See the LICENSE file for details. diff --git a/eox_tagging/settings/production.py b/eox_tagging/settings/production.py index 4058c80..6c69db7 100644 --- a/eox_tagging/settings/production.py +++ b/eox_tagging/settings/production.py @@ -7,5 +7,5 @@ def plugin_settings(settings): # pylint: disable=unused-argument """ Set of plugin settings used by the Open Edx platform. - More info: https://github.com/edx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst + More info: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst """ diff --git a/eox_tagging/settings/test.py b/eox_tagging/settings/test.py index c6af13d..fae601b 100644 --- a/eox_tagging/settings/test.py +++ b/eox_tagging/settings/test.py @@ -34,7 +34,7 @@ class SettingsClass: def plugin_settings(settings): # pylint: disable=function-redefined """ Set of plugin settings used by the Open Edx platform. - More info: https://github.com/edx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst + More info: https://github.com/eopenedx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst """ settings.EOX_TAGGING_SKIP_VALIDATIONS = True settings.EOX_TAGGING_LOAD_PERMISSIONS = False From c6cdace53b5343f56715daa221f442780a3ba526 Mon Sep 17 00:00:00 2001 From: Diana Catalina Olarte Date: Mon, 24 Jun 2024 11:28:14 +1000 Subject: [PATCH 4/7] docs: remove redundant build image --- README.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.rst b/README.rst index f856c4f..abc3d3d 100644 --- a/README.rst +++ b/README.rst @@ -24,8 +24,7 @@ Installation OPENEDX_EXTRA_PIP_REQUIREMENTS: - eox_tagging -#. Build the openedx image by doing ``tutor images build openedx``. -#. Start the tutor instance with ``tutor local launch``. +#. Build the docker image and start the tutor instance with ``tutor local launch``. Compatibility Notes -------------------- From ae993c570c79a57f8177944134aac3e90ac59865 Mon Sep 17 00:00:00 2001 From: Diana Catalina Olarte Date: Wed, 26 Jun 2024 22:02:29 +1000 Subject: [PATCH 5/7] docs: improve installation section --- README.rst | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/README.rst b/README.rst index abc3d3d..d9c63bf 100644 --- a/README.rst +++ b/README.rst @@ -16,15 +16,15 @@ to tag `edx-platform`_ objects. These tags can be used to categorize, include ex Installation ============ -#. Install a new fresh instance of tutor following `this steps `_. *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: +#. Add this plugin in your Tutor ``config.yml`` with the ``OPENEDX_EXTRA_PIP_REQUIREMENTS`` setting. - .. code-block:: yaml - - OPENEDX_EXTRA_PIP_REQUIREMENTS: - - eox_tagging - -#. Build the docker image and start the tutor instance with ``tutor local launch``. + .. 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``. Compatibility Notes -------------------- @@ -51,10 +51,8 @@ Compatibility Notes | 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. +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. If you are installing a previous version, please refer to the tag to verify the configuration that should be applied. @@ -288,7 +286,6 @@ Check your auditing records in *Django sysadmin > DJANGO EDUNEXT AUDIT MODEL*. For more information, check the eox-audit-model documentation. - .. _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/ From ad47cfc08ebe14e28590fbbdf2788b400ba38061 Mon Sep 17 00:00:00 2001 From: Diana Catalina Olarte Date: Mon, 8 Jul 2024 14:26:14 +1000 Subject: [PATCH 6/7] docs: update plugin config changes --- README.rst | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index d9c63bf..84c4830 100644 --- a/README.rst +++ b/README.rst @@ -10,7 +10,7 @@ EOX Tagging .. |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 +Eox-tagging is an `openedx plugin`_, part of the Edunext Open edX 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 @@ -52,9 +52,13 @@ Compatibility Notes +------------------+--------------+ 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. +Those settings can be changed in `eox_tagging/settings/common.py`` or, for example, in the instance configurations. -If you are installing a previous version, please refer to the tag to verify the configuration that should be applied. + +🚨 If the release you are looking for is not listed, please note: + +- If the Open edX release is compatible with the current eox-tagging version (see `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., `v5.1.0 README `_). Usage ====== From 9a81f63a8bf956caeecb97afd2fa2cdcdd65bdf9 Mon Sep 17 00:00:00 2001 From: Diana Olarte Date: Tue, 9 Jul 2024 05:24:02 +1000 Subject: [PATCH 7/7] docs: fix typo eox_tagging/settings/test.py Co-authored-by: Mariagabriela Jaimes --- eox_tagging/settings/test.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/eox_tagging/settings/test.py b/eox_tagging/settings/test.py index fae601b..045500b 100644 --- a/eox_tagging/settings/test.py +++ b/eox_tagging/settings/test.py @@ -34,7 +34,7 @@ class SettingsClass: def plugin_settings(settings): # pylint: disable=function-redefined """ Set of plugin settings used by the Open Edx platform. - More info: https://github.com/eopenedx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst + More info: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst """ settings.EOX_TAGGING_SKIP_VALIDATIONS = True settings.EOX_TAGGING_LOAD_PERMISSIONS = False