Merge pull request #64 from SmartBioTech/documentation

Documentation

Author: xtrojak

.readthedocs.yaml

@@ -0,0 +1,16 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/source/conf.py
+
+python:
+  version: "3.8"
+  install:
+    - requirements: docs/requirements.txt

README.md

@@ -1,10 +1,12 @@
 [![Python Package](https://github.com/SmartBioTech/DeviceControl/actions/workflows/python-flask.yml/badge.svg)](https://github.com/SmartBioTech/DeviceControl/actions/workflows/python-flask.yml)
 [![Docker](https://github.com/SmartBioTech/DeviceControl/actions/workflows/docker.yml/badge.svg)](https://github.com/SmartBioTech/DeviceControl/actions/workflows/docker.yml)
+[![docs](https://readthedocs.org/projects/devicecontrol/badge/?version=latest)](https://devicecontrol.readthedocs.io/en/latest/)
 
 # DeviceControl
 
 `DeviceControl` is a tool to provide unified interface to control and measure data in specific cultivation device.
-We recommend reading [wiki](https://github.com/SmartBioTech/DeviceControl/wiki) to get started with the tool.
+We recommend reading [wiki](https://github.com/SmartBioTech/DeviceControl/wiki) to get started with the tool 
+and [documentation](http://devicecontrol.readthedocs.io/) to get more details about the implementation. 
 
 ## Installation
 

app/__init__.py

@@ -31,7 +31,7 @@ def create_app(config_name):
 
     if config_name != 'testing':
         scheduler.init_app(app)
-        scheduler.add_job(func=app_manager.restore_session, id='load_session',
+        scheduler.add_job(func=app_manager._restore_session, id='load_session',
                           run_date=datetime.now() + timedelta(seconds=30))
         scheduler.start()
 
@@ -47,4 +47,4 @@ def setup_app_manager(app):
     db.create_all()
 
     app_manager.init_app()
-    app_manager.dataManager.store_permanent()
+    app_manager.dataManager._store_permanent()

app/core/app_manager.py

@@ -15,7 +15,14 @@ def validate_attributes(required, attributes, class_name):
 
 
 class AppManager:
+    """
+    Defines entry points to the application.
+    """
+
     def init_app(self):
+        """
+        Initializes the application.
+        """
         from app.src.task_manager import TaskManager
         from app.src.data_manager import DataManager
         from app.src.device_manager import DeviceManager
@@ -26,6 +33,13 @@ def init_app(self):
 
     @log_initialise('device')
     def register_device(self, config: dict) -> Response:
+        """
+        Register a new device (see
+        `details <https://github.com/SmartBioTech/DeviceControl/wiki/End-Points#device-initiation>`__).
+
+        :param config: A dictionary with pre-defined keys
+        :return: Response object
+        """
         try:
             validate_attributes(['device_id', 'device_class', 'device_type', 'address'], config, 'Connector')
             device = self.deviceManager.new_device(config)
@@ -38,6 +52,12 @@ def register_device(self, config: dict) -> Response:
 
     @log_terminate
     def end_device(self, device_id: str) -> Response:
+        """
+        Terminates an existing device.
+
+        :param device_id: ID of an existing device
+        :return: Response object
+        """
         try:
             self.deviceManager.remove_device(device_id)
             self.dataManager.event_device_end(device_id)
@@ -51,7 +71,14 @@ def end_device(self, device_id: str) -> Response:
             Log.error(exc)
             return Response(False, None, exc)
 
-    def command(self, config) -> Response:
+    def command(self, config: dict) -> Response:
+        """
+        Run a specific command (see
+        `details <https://github.com/SmartBioTech/DeviceControl/wiki/End-Points#command>`__).
+
+        :param config: A dictionary with pre-defined keys
+        :return: Response object
+        """
         try:
             validate_attributes(['device_id', 'command_id'], config, 'Command')
 
@@ -61,7 +88,7 @@ def command(self, config) -> Response:
             source = config.get('source', 'external')
             await_result = config.get('await', False)
 
-            cmd = self.create_command(device_id, command_id, args, source)
+            cmd = self._create_command(device_id, command_id, args, source)
             if await_result:
                 self.deviceManager.get_device(device_id).post_command(cmd)
                 cmd.await_cmd()
@@ -74,7 +101,14 @@ def command(self, config) -> Response:
             return Response(False, None, e)
 
     @log_initialise('task')
-    def register_task(self, config) -> Response:
+    def register_task(self, config: dict) -> Response:
+        """
+        Register a new task (see
+        `details <https://github.com/SmartBioTech/DeviceControl/wiki/End-Points#task-initiation>`__).
+
+        :param config: A dictionary with pre-defined keys
+        :return: Response object
+        """
         try:
             validate_attributes(['task_id', 'task_class', 'task_type'], config, 'Task')
             task = self.taskManager.create_task(config)
@@ -87,6 +121,12 @@ def register_task(self, config) -> Response:
 
     @log_terminate
     def end_task(self, task_id) -> Response:
+        """
+        Terminate an existing task.
+
+        :param task_id: ID of an existing task
+        :return: Response object
+        """
         try:
             device_id = self.taskManager.remove_task(task_id)
             self.dataManager.event_task_end(device_id, task_id)
@@ -97,12 +137,25 @@ def end_task(self, task_id) -> Response:
             return Response(False, None, exc)
 
     def ping(self) -> Response:
+        """
+        Get status information about the running devices and tasks (see
+        `details <https://github.com/SmartBioTech/DeviceControl/wiki/End-Points#ping>`__).
+
+        :return: Response object
+        """
         return Response(True, {
             'devices': self.deviceManager.ping(),
             'tasks': self.taskManager.ping()
         }, None)
 
-    def get_data(self, config) -> Response:
+    def get_data(self, config: dict) -> Response:
+        """
+        Retrieves data in supported format (see
+        `details <https://github.com/SmartBioTech/DeviceControl/wiki/End-Points#get-data>`__).
+
+        :param config: A dictionary with pre-defined keys
+        :return: Response object
+        """
         try:
             validate_attributes(['device_id', 'type'], config, 'GetData')
 
@@ -120,6 +173,12 @@ def get_data(self, config) -> Response:
             return Response(False, None, e)
 
     def get_latest_data(self, config) -> Response:
+        """
+        Retrieves the last data entry for specified Device ID and Data Type.
+
+        :param config: A dictionary which specifies the "device_id": string and "type": string
+        :return: Response object
+        """
         try:
             validate_attributes(['device_id', 'type'], config, 'GetData')
             device_id = config.get('device_id')
@@ -130,18 +189,24 @@ def get_latest_data(self, config) -> Response:
             Log.error(e)
             return Response(False, None, e)
 
-    @staticmethod
-    def create_command(device_id, command_id, args, source):
-        from ..command import Command
-        return Command(device_id, command_id, eval(args), source)
-
     @log_terminate_all
     def end(self) -> Response:
+        """
+        Ends the application (see
+        `details <https://github.com/SmartBioTech/DeviceControl/wiki/End-Points#end>`__).
+
+        :return: Response object
+        """
         self.taskManager.end()
         self.deviceManager.end()
         return Response(True, None, None)
 
-    def restore_session(self):
+    @staticmethod
+    def _create_command(device_id, command_id, args, source):
+        from ..command import Command
+        return Command(device_id, command_id, eval(args), source)
+
+    def _restore_session(self):
         # first start devices
         tasks = []
         for log in self.dataManager.load_log():