Skip to content

Commit

Permalink
docs: improve writing and formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
@dcoa
dcoa committed Jun 12, 2024
1 parent ee7e6a7 commit c43fe0f
Show file tree
Hide file tree
Showing 4 changed files with 168 additions and 153 deletions.
101 changes: 58 additions & 43 deletions README.rst
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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.
Expand All @@ -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 <https://github.com/eduNEXT/eox-tagging/tree/master/docs/how_to>`_ for 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:
----------------
Expand All @@ -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:
Expand All @@ -113,7 +121,7 @@ This means that:
.. code-block:: JSON
{
"validate_tag_value":{
"validate_tag_value": {
"exist": true
},
"validate_access": "Public",
Expand Down Expand Up @@ -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"
]
Expand All @@ -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**

Expand Down Expand Up @@ -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.

Expand All @@ -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.
126 changes: 63 additions & 63 deletions docs/how_to/api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,94 +10,94 @@ 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
---------------------

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**

Expand Down Expand Up @@ -129,7 +129,7 @@ Get list of tags
}
Create tag
^^^^^^^^^^^^^^^^
^^^^^^^^^^

**Request**

Expand Down Expand Up @@ -170,7 +170,7 @@ Where TAG_DATA:
}
Delete tag
^^^^^^^^^^^^^^^^
^^^^^^^^^^

**Request**

Expand Down
Loading

0 comments on commit c43fe0f

Please sign in to comment.