From e0a327b8e02c9202732752cbb14ca4900c49bc52 Mon Sep 17 00:00:00 2001 From: opensource-tnbt Date: Mon, 30 Nov 2020 23:30:03 +0530 Subject: DOCS: Update the Documentation. This patch updates the documentation for Jerma. Signed-off-by: Sridhar K. N. Rao Change-Id: Ic0d61a74b1c8d31c8facaa16837894fc816ac739 --- .../docker/state/development/design/index.rst | 0 .../docker/state/development/overview/index.rst | 0 .../overview/result-api-architecture.png | Bin 24756 -> 0 bytes .../state/development/overview/result_api.rst | 178 --------------------- .../docker/state/development/overview/settings.rst | 38 ----- 5 files changed, 216 deletions(-) delete mode 100644 docs/release/userguide/docker/state/development/design/index.rst delete mode 100644 docs/release/userguide/docker/state/development/overview/index.rst delete mode 100644 docs/release/userguide/docker/state/development/overview/result-api-architecture.png delete mode 100644 docs/release/userguide/docker/state/development/overview/result_api.rst delete mode 100644 docs/release/userguide/docker/state/development/overview/settings.rst (limited to 'docs/release/userguide/docker/state/development') diff --git a/docs/release/userguide/docker/state/development/design/index.rst b/docs/release/userguide/docker/state/development/design/index.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/release/userguide/docker/state/development/overview/index.rst b/docs/release/userguide/docker/state/development/overview/index.rst deleted file mode 100644 index e69de29..0000000 diff --git a/docs/release/userguide/docker/state/development/overview/result-api-architecture.png b/docs/release/userguide/docker/state/development/overview/result-api-architecture.png deleted file mode 100644 index e464187..0000000 Binary files a/docs/release/userguide/docker/state/development/overview/result-api-architecture.png and /dev/null differ diff --git a/docs/release/userguide/docker/state/development/overview/result_api.rst b/docs/release/userguide/docker/state/development/overview/result_api.rst deleted file mode 100644 index 12fd62c..0000000 --- a/docs/release/userguide/docker/state/development/overview/result_api.rst +++ /dev/null @@ -1,178 +0,0 @@ -Result API -========== - -Table of contents -^^^^^^^^^^^^^^^^^ - -- `Description <#Description>`__ -- `Architecture <#Architecture>`__ -- `Managing configuration <#Managing%20configuration>`__ -- `How to Use <#How%20to%20Use>`__ - ----------------------- - -Description -~~~~~~~~~~~ - -Result API is very simple write-only API for storing results of any size -to multiple storage endpoints. - -Results API focuses on only sending test results to required -destinations so that they can be later viewed by user but do not -implements read functionality as this is not required while running -tests - -Usage is very simple: -''''''''''''''''''''' - -.. code:: python - - from result_api import result_api as api - from result_api import Local - - # First register storage enpoints - endpoint = Local() - api.register_storage(endpoint) - - # Now, use anywhere in program - api.store(data) - -Note: In above example we used only one storage endpoints so, whenever -``api`` will make call to ``store()`` method it will be used. But if -register multiple storage endpoints then whenever ``api`` will make call -to ``store()`` method all endpoints will be called to store data. This -package doesn't allows to selectively make calls to different storage -endpoint for storing. Instead follows **one api -> many endpoint (one to -many)** design. - ----------------------- - -Architecture -~~~~~~~~~~~~ - -|img| - -*ResultsAPI exports data to various storage endpoints like harddisk, -SQL, Mongo, etc. exposed by StorageAPI in write-only mode* - ----------------------- - -Managing configuration -~~~~~~~~~~~~~~~~~~~~~~ - -Result API uses `Conf: Program Settings handler <../conf/readme.md>`__ -to manage all it's settings. So, user can change any settings of -ResultAPI as they need. ``Conf`` allows to change settings in two ways -either read from file ``settings.load_from_file(path/to/file)`` or set -inside program ``settings.setValue(key, Value)`` - -Configurations available: - -+-----------------+---------------------+-------------------------------------+ -| Storage | setting | optional | -+=================+=====================+=====================================+ -| Local Storage | results\_path | Yes, defaults to ``/tmp/local/`` | -+-----------------+---------------------+-------------------------------------+ -| Local Storage | results\_filename | Yes, defaults to ``results.json`` | -+-----------------+---------------------+-------------------------------------+ - ----------------------- - -How to Use -~~~~~~~~~~ - -For using ResultAPI successfully the following steps are required - -#. **Import result\_api instance** from ResultAPI package as this - instance will be commonly used across our program. -#. **Import required StorageAPI** -#. **Set Storage settings** or load settings from file -#. **Create Storage Endpoints from StorageAPI** -#. **Register Storage Endpoints with result\_api** - -Now, result\_api is ready to use. We can send values to all registered -storage endpoints by making a simple call to ```store()`` -method <#store()%20method>`__ - -store() method -'''''''''''''' - -``result_api`` has ``store(dict)`` method for storing data. - -.. code:: python - - # data must be a dict - data = { 'key1': "value1", 'key2': 5, 'dumykeytext': "dummy string value"} - result_api.store(data) - -rfile -''''' - -rfile stands for result file. When you have extremely big value for a -key you would like to tell your storage endpoint to store them in -separate file and refer them in actual key. For storing value of type -file in result\_api use rfile construct. - -.. code:: python - - data = { 'name': 'example', 'myfile': rfile('Text to store in this file')} - result_api.store(data) - # Respective StorageAPI will evaluate "data" for all rfile values and store their text in some separate file/storage-object and put there refernece in "data" - -Use Local Storage with Result API -''''''''''''''''''''''''''''''''' - -.. code:: python - - from result_api import result_api as api - from result_api import Local - from result_api import rfile - - def main(): - # Update settings required for Local storage - settings.setValue('results_path', '/tmp/myresults/') - settings.setValue('results_filename', 'results.json') - - # Register Local() to result_api, this will load above settings automatically - api.register_storage(Local()) - - data = { 'testcase': "RA1.24", 'value': 'Pass', 'logs': rfile('These are logs')} - - # Now, store any data - api.store(data) - -Register Storage Endpoint -''''''''''''''''''''''''' - -.. code:: python - - from result_api.storage.mystorageapi import MyStorageAPI - - # Set required settings values for storage endpoint - settings.setValue('mysetting1', 'value') - settings.setValue('mysetting2', 'value2') - - #Now Register StorageAPI to ResultAPI - endpoint = MyStorageAPI() - api.register_storage(endpoint) - -Changing settings -''''''''''''''''' - -.. code:: python - - # Set values in a yaml file and load it - settings.load_from_file('result.yml') - - # Or set in program - settings.setValue('key', 'value') - - # Note above steps will only change settings values but will not impact any previously registered storage endpoints - # To use endpoints with new value, register new endpoints - endpoint = MyStorageAPI() - api.register_storage(endpoint) - - # And do not forget to unregister old endpoint as they have old settings - api.unregister_storage(old_endpoint) - -.. |img| image:: result-api-architecture.png diff --git a/docs/release/userguide/docker/state/development/overview/settings.rst b/docs/release/userguide/docker/state/development/overview/settings.rst deleted file mode 100644 index c70f21e..0000000 --- a/docs/release/userguide/docker/state/development/overview/settings.rst +++ /dev/null @@ -1,38 +0,0 @@ -Program Settings handler ------------------------- - -``from tools.conf import settings`` - -Settings will be loaded from several ``.yaml`` or ``.yml`` files and any -user provided settings files. - -So, that user can use these settings values across program. - -This utility loads settings from yaml files in form of key and value -where key is always ``string`` while value can be of type python: - -- ``int`` e.g. 5, 45, 1234 -- ``str`` e.g. hello, world -- ``float`` e.g. 34.56, 12.7 -- ``list`` e.g. [ ‘month’ , ‘is’, 45 ] -- ``dict`` e.g. {‘program’: ‘sdv’, ‘language’: ‘python’} -- ``bool`` e.g. True, False - -keys are case-insensitive -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The utility is case-insensitive to keys used as it automatically -converts all keys to lower case. - -E.g. ``Program : sdv``, ``program : sdv``, ``PrOgRam : sdv`` all are -same. - -- ``settings.load_from_file(path/to/file)`` -- ``settings.load_from_env()`` -- ``settings.load_from_dir(directory/to/search/yamls)`` - -``settings.load_from_dir()`` reads all yaml files in given directory and -all it’s sub-directory recursively in ascending order, hence if a -configuration item exists in more than one file, then the setting in the -file that occurs in the last read file will have high precedence and -overwrite previous values. . \ No newline at end of file -- cgit 1.2.3-korg