Docs/update (#521)

* Move docs folder

* Small fix to README

* Update installation guide

* Updated installation documentation

* More documentation changes

* PR changes

* Changed workflow

.github/workflows/build_docs.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - master
     paths:
-      - 'cornflow-server/docs/**'
+      - 'docs/**'
       - 'cornflow-server/README.rst'
       - 'cornflow-server/**'
       - 'libs/client/**'

README.rst

@@ -16,7 +16,7 @@ Cornflow
 .. image:: https://img.shields.io/pypi/l/cornflow-client?color=blue&style=for-the-badge
   :alt: PyPI - License
   :target: https://github.com/baobabsoluciones/cornflow/blob/master/LICENSE
-  
+
 .. image:: https://img.shields.io/codecov/c/gh/baobabsoluciones/cornflow?flag=server-tests&label=cornflow&logo=codecov&logoColor=white&style=for-the-badge&token=H14UGPUQVL
    :alt: Codecov
    :target: https://app.codecov.io/gh/baobabsoluciones/cornflow

cornflow-dags/DAG/graph_coloring/README.rst

@@ -1,7 +1,14 @@
-Problem
-------------
+Graph coloring
+=======================
+
+The problem consists on assigning colors to the nodes in a graph while taking care never to assign the same color to nodes that share an edge (or arc). The objective is to use the least number of different colors to succesfully color the whole graph.
+
+**Name of dag**: graph_coloring
+
+**Available solution methods**:
+
+- **default:** CP model built in ortools with CP-SAT as solver.
 
-A set of nodes in a graph need to be colored. The only constraint is that two nodes that share an arc cannot have the same color. Finally, we want to accomplish this using the least amount of colors possible.
 
 Decision
 ------------
@@ -13,4 +20,4 @@ Colors are represented as an integer number.
 Parameters
 ------------
 
-* Edges of the graph.
+- Edges of the graph.

cornflow-dags/DAG/knapsack/README.rst

@@ -1,15 +1,24 @@
-Problem
+Knapsack
 ------------
 
 We want to decide which elements to put inside a bag in order to maximize the total value of the contents while respecting the capacity of said bag.
 
+**Name of the dag**: knapsack
+
+**Available solution methods**:
+
+- Dynamic: a dynamic programming approach.
+- Direct: a direct heuristic approach.
+- Random: a random heuristic approach.
+- MIP: a mixed integer programming approach.
+
 Decision
-------------
+=========
 
 A list of items to put inside the bag.
 
 Parameters
-------------
+==========
 
-* Items: the weight and the value for each item.
-* Capacity of the bag.
+- Items: the weight and the value for each item.
+- Capacity of the bag.

cornflow-dags/DAG/roadef/README.RST

@@ -5,6 +5,15 @@ Problem
 -------
 A vendor has to manage the inventories of its customers and decide when and how to deliver to them in order to avoid stock-outs. He has to create the delivery routes, assign them to a driver, a trailer, and a starting time, and to decide what quantity of product will be delivered to each customer on every route. The objective to minimize is the total cost of all the shifts.
 
+**Name of dag**: roadef.
+
+**Available slution methods**:
+
+- **default**: a greedy heuristic.
+- Greedy: a greedy heuristic. It is the default solver.
+- MIPMoldel: a MIP approach.
+- PeriodicMIPModel: a MIP approach that gets solved iteratively.
+
 Decisions
 ---------
 A set of routes (ordered list of locations) associated to a trailer, a driver and a departure time. Each step of the route is associated to a quantity, corresponding to the quantity of product delivered (if the location is a customer) or loaded (if the location is a source).

cornflow-dags/DAG/rostering/README.rst

@@ -1,10 +1,17 @@
-Problem
--------
+Rostering
+--------------
 
-A set of employees have to work a given amount of hours or days per week, and we have to find the assignment of employees to timeslots
+A set of employees have to work a given amount of hours or days per week, and we have to find the assignment of employees to timeslots.
+
+**Name of the dag**: rostering
+
+**Available solution methods**:
+
+- **default**: MIP model built on PuLP.
+- mip: The default MiP model.
 
 Decision
---------
+=========
 
 For each employee and time slot if the employee works said time slot or not.
 
@@ -28,7 +35,7 @@ This decision is subject to:
 - RQ16: fixed worktable
 
 Parameters
-----------
+===========
 
 - Contracts: the contracts that the employees have, with the number of days that have to be worked, the weekly hours and the shift.
 - Employees: each employee can be a manager or not.
@@ -53,19 +60,19 @@ Parameters
 
 - Requirements: table indicating which requirements should be complied and which not, and if they are, if they should be applied as strict or soft constraints.
 
-    - rq02: "soft", "strict" or "deactivated for the weekly hours constraint
-    - rq03: "soft", "strict" or "deactivated for the maximum daily hours constraint
-    - rq05: "soft", "strict" or "deactivated for the maximum days worked per week constraint
-    - rq06: "soft", "strict" or "deactivated for the minimum daily hours constraint
-    - rq07: "soft", "strict" or "deactivated for the minimum rest hours between shifts constraint
-    - rq08: "soft", "strict" or "deactivated for the constraint about needing to have a manager in the store at all times
-    - rq09: "soft", "strict" or "deactivated for the skills constraint
-    - rq10: "soft", "strict" or "deactivated for the employees' holidays constraint
-    - rq11: "strict" or "deactivated for the store holidays constraint
-    - rq12: "strict" or "deactivated for the employee downtime constraint
-    - rq13: "soft", "strict" or "deactivated for the employee start hour preferences constraint
-    - rq14: "soft", "strict" or "deactivated for the employee max preference hours constraint
-    - rq15: "soft", "strict" or "deactivated for the employee schedule constraint
-    - rq16: "soft", "strict" or "deactivated for the fixed worktable constraint
+  - rq02: "soft", "strict" or "deactivated" for the weekly hours constraint
+  - rq03: "soft", "strict" or "deactivated" for the maximum daily hours constraint
+  - rq05: "soft", "strict" or "deactivated" for the maximum days worked per week constraint
+  - rq06: "soft", "strict" or "deactivated" for the minimum daily hours constraint
+  - rq07: "soft", "strict" or "deactivated" for the minimum rest hours between shifts constraint
+  - rq08: "soft", "strict" or "deactivated" for the constraint about needing to have a manager in the store at all times
+  - rq09: "soft", "strict" or "deactivated" for the skills constraint
+  - rq10: "soft", "strict" or "deactivated" for the employees' holidays constraint
+  - rq11: "strict" or "deactivated" for the store holidays constraint
+  - rq12: "strict" or "deactivated" for the employee downtime constraint
+  - rq13: "soft", "strict" or "deactivated" for the employee start hour preferences constraint
+  - rq14: "soft", "strict" or "deactivated" for the employee max preference hours constraint
+  - rq15: "soft", "strict" or "deactivated" for the employee schedule constraint
+  - rq16: "soft", "strict" or "deactivated" for the fixed worktable constraint
 
 - Penalties: table indicating for each soft constraint the penalty level when it is not respected.

cornflow-dags/DAG/tsp/README.rst

@@ -1,14 +1,22 @@
-Problem
-------------
+Travelling Salesman Problem (TSP)
+------------------------------------
 
 We want to find the shortest tour that visits each node in a Graph once.
 
+**Name of the dag**: tsp
+
+**Available solution methods**:
+
+- **default**: naive solver.
+- naive: naive solver. It is the default method.
+- cpsat: a constraint programming solver implemented with Google's ORTools.
+
 Decision
-------------
+=========
 
 An ordered list of the nodes to visit.
 
 Parameters
-------------
+===========
 
-* Weighted edges of the Graph. Each edge represents the distance between its pair of nodes.
+- Weighted edges of the Graph. Each edge represents the distance between its pair of nodes.

cornflow-dags/DAG/vrp/README.rst

@@ -1,17 +1,26 @@
-Problem
-------------
+Vehicle Routing Problem (VRP)
+------------------------------------
 
 We want to schedule delivery routes to cover the demand of a given set of customers subject to capacity constraints in each vehicle. We want to satisfy all customers requirements by minimizing the total distance traveled.
 
 Each route has to start and end in one depot.
 
+**Name of dag**: ``vrp
+
+**Available solution methods**:
+
+- algorithm1: dumb heuristic that chooses the closest neighbor at each time. Does not use capacity.
+- algorithm2: dumb heuristic that chooses the closes neighbor at each time. Takes capacity into account.
+- algorithm3: a constraint programming built in ortools with CP-SAT as solver.
+- mip: a MIP model implemented on Pyomo.
+
 Decision
-------------
+============
 
 A set of routes. Each route consists of an ordered list of clients to visit.
 
 Parameters
-------------
+============
 
 * Weighted edges of the Graph. Each edge represent the distance between its pair of nodes.
 * Demand for each customer.

cornflow-server/cornflow/models/base_data_model.py

@@ -28,6 +28,9 @@ class BaseDataModel(TraceAttributesModel):
 
     @declared_attr
     def user_id(self):
+        """
+        The foreign key for the user (:class:`UserModel<cornflow.models.UserModel>`).
+        """
         return db.Column(db.Integer, db.ForeignKey("users.id"), nullable=False)
 
     @declared_attr

cornflow-server/cornflow/models/case.py

@@ -34,10 +34,40 @@
 
 
 class CaseModel(BaseDataModel):
+    """
+    Model class for the Cases. 
+    It inherits from :class:`BaseDataModel<cornflow.models.base_data_model.BaseDataModel>` to have the trace fields and user field.
+
+    - **id**: int, the primary key for the cases, is an autoincrement.
+    - **path**: str, the path for the case, by default it would be the "root folder" (empty string).
+    - **name**: str, the name of the case given by the user.
+    - **description**: str, the description of the case given by the user. It is optional.
+    - **data**: dict (JSON), the data of the instance of the case.
+    - **checks**: dict (JSON), the checks of instance of the case.
+    - **data_hash**: str, the hash of the data of the instance of the case.
+    - **solution**: dict (JSON), the solution of the instance of the case.
+    - **solution_hash**: str, the hash of the solution of the instance of the case.
+    - **solution_checks**: dict (JSON), the checks of the solution of the instance of the case.
+    - **schema**: str, the schema of the instance of the case.
+    - **user_id**: int, the foreign key for the user (:class:`UserModel<cornflow.models.UserModel>`). It links the case to its owner.
+    - **created_at**: datetime, the datetime when the case was created (in UTC).
+      This datetime is generated automatically, the user does not need to provide it.
+    - **updated_at**: datetime, the datetime when the case was last updated (in UTC).
+      This datetime is generated automatically, the user does not need to provide it.
+    - **deleted_at**: datetime, the datetime when the case was deleted (in UTC). Even though it is deleted, actually, it is not deleted from the database, in order to have a command that cleans up deleted data after a certain time of its deletion.
+
+    """
+
+
     __tablename__ = "cases"
 
     id = db.Column(db.Integer, primary_key=True, autoincrement=True)
     path = db.Column(db.String(500), nullable=False, index=True)
+    solution = db.Column(JSON, nullable=True)
+    solution_hash = db.Column(db.String(256), nullable=False)
+    solution_checks = db.Column(JSON, nullable=True)
+
+
     # To find the descendants of this node, we look for nodes whose path
     # starts with this node's path.
     # c_path =
@@ -49,9 +79,7 @@ class CaseModel(BaseDataModel):
             path.concat(id).concat(SEPARATOR + "%")
         ),
     )
-    solution = db.Column(JSON, nullable=True)
-    solution_hash = db.Column(db.String(256), nullable=False)
-    solution_checks = db.Column(JSON, nullable=True)
+
 
     # TODO: maybe implement this while making it compatible with sqlite:
     # Finding the ancestors is a little bit trickier. We need to create a fake
@@ -100,6 +128,17 @@ def __init__(self, data, parent=None):
 
     @classmethod
     def from_parent_id(cls, user, data):
+        """
+        Class method to create a new case from an already existing case.
+
+        :param user: the user that is creating the case.
+        :type user: :class:`UserModel<cornflow.models.UserModel>`
+        :param data: the data of the case
+        :type data: dict
+        :return: the new case
+        :rtype: :class:`CaseModel<cornflow.models.CaseModel>`
+        """
+
         if data.get("parent_id") is None:
             # we assume at root
             return cls(data, parent=None)
@@ -195,6 +234,12 @@ def apply_patch(original_data, data_patch):
         return patched_data, hash_json_256(patched_data)
 
     def move_to(self, new_parent=None):
+        """
+        Method to move the case to a new path based on a new parent case
+
+        :param new_parent: the new parent case
+        :type new_parent: :class:`CaseModel<cornflow.models.CaseModel>`
+        """
         if new_parent is None:
             new_path = ""
         else:

cornflow-server/cornflow/models/execution.py

@@ -15,7 +15,7 @@
 class ExecutionModel(BaseDataModel):
     """
     Model class for the Executions.
-    It inherits from :class:`BaseDataModel` to have the trace fields and user field
+    It inherits from :class:`BaseDataModel<cornflow.models.base_data_model.BaseDataModel>` to have the trace fields and user field.
 
     - **id**: str, the primary key for the executions, a hash generated upon creation of the execution
       and the id given back to the user.

cornflow-server/cornflow/models/instance.py

@@ -11,7 +11,7 @@
 class InstanceModel(BaseDataModel):
     """
     Model class for the Instances
-    It inherits from :class:`BaseDataModel` to have the trace fields and user field
+    It inherits from :class:`BaseDataModel<cornflow.models.base_data_model.BaseDataModel>` to have the trace fields and user field
 
     The :class:`InstanceModel` has the following fields:
 
@@ -58,12 +58,14 @@ def __init__(self, data):
             (str(self.created_at) + " " + str(self.user_id)).encode()
         ).hexdigest()
 
-    def update(self, data):
+    def update(self, data: dict):
         """
-        Method used to update an instance from the database
+        Method used to update an instance from the database.
+
+        This method is mainly used on PUT requests to update the instance.
 
         :param dict data: the data of the object
-        :return: None
+        :return: Nothing, it will update the instance in-place and on the database
         :rtype: None
         """
         # Delete the checks if the data has been modified since they are probably not valid anymore