refactor: rearrange documentation to be less overwhelming

* Use docs/how_to instead of sphinx folder * Move validation rules to configuration docs * Reword some of the docs
eduNEXT · Apr 22, 2022 · 9ec7920 · 9ec7920
1 parent 703f3f5
commit 9ec7920
Show file tree

Hide file tree

Showing 8 changed files with 43 additions and 286 deletions.
diff --git a/README.rst b/README.rst
@@ -86,63 +86,13 @@ Those settings can be changed in ``eox_tagging/settings/common.py`` or, for exam
 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.
+
 Important notes:
 ----------------
 
 * All the comparison with string objects are case insensitive.
-* validate_<FIELD_VALUE> meaning:
-
-  * The FIELD_VALUE must be a Tag field, if not an exception will be raised.
-  * If this is defined in EOX_TAGGING_DEFINITIONS as one of the tag definitions:
-
-    ``validate_<FIELD_VALUE_1>: <VALIDATIONS>``
-
-    * The application will expect that <VALIDATIONS> is a dictionary of validations or a string.
-
-    * This dictionary has for keys the validations you want to perform and for values, the values allowed for the field. In case it is a string, the field must be equal to that string.
-
-    * If a key or value is not defined then an exception will be raised. In case that is a string, the field must be equal to that string.
-
-  * If this is defined:
-
-    ``<FIELD_VALUE>: <VALIDATIONS>``
-
-    * The application will expect just a string as a validation. This is also a way to define the required fields.
-
-    * The settings for EOX_TAGGING_DEFINITIONS can be a combination of dictionary validations and strings.
-
-  * If a key in the settings dictionary has as prefix `validate` it means that the <key, value> can have a dictionary of validations as value. If not, is assume that
-      value is a string.
-
-* force_<FIELD_VALUE> meaning:
-
-    * This allows to set a value to a field without running validations or directly specifying it in the tag object.
-
-* The validations available are:
-
-+---------------+-------+-----------------------------------------------+----------------------------------------------------------------+
-| Name          | Description                                           | Example                                                        |
-+===============+=======================================================+================================================================+
-| ``in``        | the field must be equal to one of the strings defined | ``validate_tag_value : {"in": ["tag_value_1", "tag_value_2"]}``|
-|               | inside the array                                      |                                                                |
-+---------------+-------------------------------------------------------+----------------------------------------------------------------+
-| ``exists``    | the field must be different to None                   |  ``validate_tag_value : {"exists": true}``                     |
-+---------------+-------------------------------------------------------+----------------------------------------------------------------+
-|  ``equals``   | the field must be equal to the dictionary value       |  ``validate_tag_value : {"equals": "tag_value"}``              |
-+---------------+-------------------------------------------------------+----------------------------------------------------------------+
-|  ``regex``    | the field must match the pattern defined              |  ``validate_tag_value : {"regex": ".+eduNEXT"}``               |
-+---------------+-------------------------------------------------------+----------------------------------------------------------------+
-|``opaque_key`` | the field must be an opaque key                       |  ``validate_tag_value : {"opaque_key": "CourseKey"}``          |
-+---------------+-------------------------------------------------------+----------------------------------------------------------------+
-| ``between``   | the field must be greater than the first member of    |  ``validate_expiration_date : {"between": [DATE_1, DATE_2]}``  |
-|               | the list and less than the last member. Or can be     |                                                                |
-|               | equal to one of the two. The list must be sorted.     |                                                                |
-+---------------+-------------------------------------------------------+----------------------------------------------------------------+
-
-
-* The available objects to tag and validate are: User, Site, CourseOverview, CourseEnrollment and GeneratedCertificate.
-
-* If an owner is not defined, then it is assumed to be the site.
+* If a tag owner is not defined, then it is assumed to be the site.
 
 Examples
 --------

diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/README.rst b/docs/README.rst
@@ -0,0 +1,8 @@
+Welcome to eox-tagging's documentation!
+=======================================
+
+Here you'll find:
+
+* `How to configure tags <https://github.com/eduNEXT/eox-tagging/tree/master/docs/how_to/configuration.rst>`_
+* `How the tag model works <https://github.com/eduNEXT/eox-tagging/tree/master/docs/how_to/model.rst>`_
+* `How to use the eox-tagging REST API <https://github.com/eduNEXT/eox-tagging/tree/master/docs/how_to/api.rst>`_
diff --git a/docs/source/api.rst → docs/how_to/api.rst b/docs/source/api.rst → docs/how_to/api.rst
@@ -88,10 +88,9 @@ When retrieving objects, the JSON object will have the following fields (the men
 Validations
 -----------
 
-Before doing the validations mentioned in :ref:`model:Validations`, it is 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 will be performed and if an error occurs the error message will be returned in a
-response instead of valid data.
+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
+will be performed and if an error occurs the error message will be returned in a response instead of valid data.
 
 
 Examples

diff --git a/docs/source/configuration.rst → docs/how_to/configuration.rst b/docs/source/configuration.rst → docs/how_to/configuration.rst
@@ -23,6 +23,25 @@ Where <FIELD_NAME> can be any editable tag field, and <VALIDATION> any of the de
 
 Validations
 ^^^^^^^^^^^
+
+Here's how to create validated fields, first, add the key validate_<FIELD_VALUE> to the configuration dictionary, where:
+
+* The FIELD_VALUE must be a Tag field, if not an exception will be raised.
+
+* If this is defined in EOX_TAGGING_DEFINITIONS as one of the tag definitions ``validate_<FIELD_VALUE_1>: <VALIDATIONS>``, then:
+
+  * The application will expect that <VALIDATIONS> is a dictionary of validations or a string.
+  * This dictionary has for keys the validations you want to perform and for values, the values allowed for the field. In case it is a string, the field must be equal to that string.
+  * If a key or value is not defined then an exception will be raised. In case that is a string, the field must be equal to that string.
+
+* If this is defined ``<FIELD_VALUE>: <VALIDATIONS>``, then:
+
+  * The application will expect just a string as a validation. This is also a way to define the required fields.
+  * The settings for EOX_TAGGING_DEFINITIONS can be a combination of dictionary validations and strings.
+  * If a key in the settings dictionary has as prefix `validate` it means that the <key, value> can have a dictionary of validations as value. If not, is assume that value of that tag field is equal to that string.
+
+* force_<FIELD_VALUE> allowing to set a value to a field without running validations or directly specifying it in the tag object.
+
 +---------------+-------+-----------------------------------------------+----------------------------------------------------------------+
 | Name          | Description                                           | Example                                                        |
 +===============+=======================================================+================================================================+
@@ -50,42 +69,41 @@ Fields
 +-------------------------+-----------------------------------------+-----------------------+--------------------------------------------+
 | Name(s)                 | Description                             |  Value/Format         | Possible validators                        |
 +=========================+=========================================+=======================+============================================+
-| validate_tag_value      | Contains possible values for the field  | Not specified         | in, exists, equals, regex, opaque          |
+| tag_value               | Contains possible values for the field  | Not specified         | in, exists, equals, regex, opaque          |
 |                         |                                         |                       | any validation that can validate a string. |
 +-------------------------+-----------------------------------------+-----------------------+--------------------------------------------+
-| validate_access         | Contains possible values for the field  | Public, private,      | Any validator but must have at least one   |
+| access                  | Contains possible values for the field  | Public, private,      | Any validator but must have at least one   |
 |                         |                                         | protected.            | of the values defined.                     |
 +-------------------------+-----------------------------------------+-----------------------+--------------------------------------------+
-| validate_deactivation   | Contains possible datetime values for   | Year-month-day H:M:S  | in, exists, equals, between. If apply, the |
-| _date                   | the field.                              |                       | values must match the format specified.    |
+| deactivation_date       | Contains possible datetime values for   | Year-month-day H:M:S  | in, exists, equals, between. If apply, the |
+|                         | the field.                              |                       | values must match the format specified.    |
 +-------------------------+-----------------------------------------+-----------------------+--------------------------------------------+
-| validate_activation_date| Contains possible datetime values for   | Year-month-day H:M:S  | in, exists, equals, between. If apply, the |
+| activation_date         | Contains possible datetime values for   | Year-month-day H:M:S  | in, exists, equals, between. If apply, the |
 |                         | the field.                              |                       | values must match the format specified.    |
 +-------------------------+-----------------------------------------+-----------------------+--------------------------------------------+
-| validate_target_object  | Contains the only possible target value | User, site,           | equals. The values must match the targets  |
+| target_object           | Contains the only possible target value | User, site,           | equals. The values must match the targets  |
 |                         | of that tag.                            | CourseEnrollment,     | predefined.                                |
 |                         |                                         | OpaqueKeyProxyModel*  |                                            |
 +-------------------------+-----------------------------------------+-----------------------+--------------------------------------------+
-| validate_owner_object   | Contains the only possible owner value  | User, site,           | equals. The values must match the targets  |
+| owner_object            | Contains the only possible owner value  | User, site,           | equals. The values must match the targets  |
 |                         | of that tag.                            |                       | predefined.                                |
 +-------------------------+-----------------------------------------+-----------------------+--------------------------------------------+
 | tag_type                | Contains the only possible type         | Not specified         | equals. The tag_type must always exist and |
 |                         | of that tag.                            |                       | needs to be unique in the config array.    |
 +-------------------------+-----------------------------------------+-----------------------+--------------------------------------------+
 
-
 * In the configuration, if the user wants to create a tag on a course it must use OpaqueKeyProxyModel as the target_object.
 
-**Important note:** as mentioned above the validations can or not have ``validate_`` in front of the <FIELD_NAME>, if they don't have it,
-the program will assume that the field must be equal to the value. For example:
+**Important note:** as mentioned above the tag fields can or not have ``validate_`` in front of the <FIELD_NAME>, if they don't have it,
+the application will assume that the field must be equal to the value. For example:
 
 .. code-block:: JSON
 
         {
             "FIELD_NAME": "VALUE"
         }
 
-This means that the FIELD with FIELD_NAME must be equal to VALUE.
+This means that the FIELD with FIELD_NAME must be equal to VALUE when creating a tag, otherwise, an error will be raised.
 
 Setting values using the configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

diff --git a/docs/source/model.rst → docs/how_to/model.rst b/docs/source/model.rst → docs/how_to/model.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
diff --git a/docs/source/index.rst b/docs/source/index.rst