Fix rtd, add zuul.yaml, update REST doc

Change-Id: I0c5f2964e813c830c20da55630b081913a861f8d

.zuul.yaml

@@ -0,0 +1,15 @@
+
+- project:
+    templates:
+      - docs-on-readthedocs
+      - publish-to-pypi
+    vars:
+      rtd_webhook_id: '83817'
+    check:
+      jobs:
+        - tox-pep8
+        - tox-py27
+    gate:
+      jobs:
+        - tox-pep8
+        - tox-py27

doc/source/usage.rst

@@ -85,8 +85,95 @@ provided URL at port 8080.
     * `KloudBuster REST API Documentation Preview <https://htmlpreview.github.io/?https://github.com/openstack/kloudbuster/blob/master/doc/source/_static/kloudbuster-swagger.html>`_
     * `REST API Documentation (Swagger yaml) <https://github.com/openstack/kloudbuster/blob/master/kb_server/kloudbuster-swagger.yaml>`_
 
-Examples of REST requests
+
-^^^^^^^^^^^^^^^^^^^^^^^^^
+The following curl examples assume the server runs on localhost.
+
+Display version and retrieve default configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To get the current version and retrieve the default configuration and copy to a file:
+
+.. code-block:: bash
+
+    > curl http://localhost:8080/api/kloudbuster/version
+    7.1.1
+    > curl http://localhost:8080/api/config/default_config >default_config
+
+     ...
+
+
+Create a new Kloudbuster session
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Before running any benchmark, the first step is to create a new session:
+
+The body of the REST request msut have the following fields:
+
+.. code-block:: bash
+
+    {
+       'credentials': {'tested-rc': '<STRING>',
+                       'testing-rc': '<STRING>'},
+       'kb_cfg': {<USER_OVERRIDED_CONFIGS>},
+       'topo_cfg': {<TOPOLOGY_CONFIGS>},
+       'tenants_cfg': {<TENANT_AND_USER_LISTS_FOR_REUSING>},
+       'storage_mode': true|false
+    }
+
+List of fields and content:
+
+- credentials (mandatory)
+- tested-rc (mandatory) contains the openrc variables (string containing the list of variables separated by \n)
+- testing-rc (optional) only needed in case of dual cloud testing (HTTP only)
+- kb_cfg (mandatory) a string containing the Kloudbuster configuration to use (json)
+- topo_cfg (optional) a string containing the topology configuration (json)
+- tenants_cfg (optional) a string containing the list of tenants and users to use (json)
+- storage_mode (mandatory) true for storage benchmark, false for HTTP benchmark
+
+
+Example of configuration:
+
+.. code-block:: bash
+
+    # Content of a standard openrc file that we store in a variable
+    OPENRC="export OS_CACERT=/root/openstack-configs/haproxy-ca.crt
+    export OS_AUTH_URL=https://10.0.0.1:5000/v3
+    export OS_USERNAME=admin
+    export OS_PASSWORD=55DgmREFWenMqkxK
+    export OS_REGION_NAME=RegionOne
+    export OS_PROJECT_NAME=admin
+    export OS_PROJECT_DOMAIN_NAME=default
+    export OS_USER_DOMAIN_NAME=default
+    export OS_IDENTITY_API_VERSION=3"
+
+    # Example of simple Kloudbuster configuration
+    KBCFG="{client:{storage_stage_configs:{ vm_count: 1, disk_size: 50, io_file_size: 1},
+    storage_tool_configs:{[description: 'Random Read', mode: 'randread', runtime: 30,
+    block_size: '4k', iodepth: 4]}}}"
+
+    # REST request body in json format
+    BODY="{'credentials': {'tested-rc': $OPENRC},
+           'kb_cfg': $KBCFG,
+           'storage_mode': true}"
+
+Create the Kloudbuster session with above configuration:
+
+.. code-block:: bash
+
+    > curl -H "Content-Type: application/json" -X POST -d "$BODY" http://localhost:8080/api/config/running_config
+
+Note that this request only updates the running configuration and does not start any benchmark.
+It will return a session ID that needs to be passed to subsequent REST requests.
+
+Start a storage benchmark using the running configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SESSION_ID is the id returned from the /api/config/running_config POST request.
+
+.. code-block:: bash
+
+    > curl -H "Content-Type: application/json" -X POST http://localhost:8080/api/kloudbuster/run_test/$SESSION_ID
+
 
 .. _upload_kb_image:
 
@@ -143,5 +230,3 @@ To upload the image from a local copy of that image using the Glance CLI:
 .. code-block:: bash
 
     glance image-create --file kloudbuster-7.0.0.qcow2 --disk-format qcow2 --container-format bare --visibility public --name kloudbuster-7.0.0
-
-