Added developer documentation

This commit contains 'how to do' documents for creating new flavor
criteria plugin and writing funcitonal test cases.

Change-Id: I1268e804cbf3493058599b014f7e8b0378444440
Closes-bug: #1639731

doc/source/developer-guide/add_new_api.rst

@@ -0,0 +1,111 @@
+.. _add_new_api:
+      Copyright 2016 Intel Corporation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+=================================
+Add a new API endpoint in Valence
+=================================
+
+In this Guide, you will find information on how to add new API in to Valence.
+This guide assumes that Valence environment is already setup (if not please go
+through the `readme.rst`).
+
+
+Interacting with Valence
+-------------------------
+
+Before starting modification/adding a new functionality in Valence, it is suggested
+to check that the valence has been setup properly. This could be done by making some
+REST calls to the existing APIs and verifying their response.
+
+.. NOTE::
+
+         curl or some other GUI REST clients(like Postman plugin for Chrome browser)
+         could be used for making the REST calls.
+
+        .. code-block:: bash
+
+           $ curl http://localhost:8181/v1
+
+The above REST API call will return a json with valence version specific details. This
+ensure that Valence has been setup rightly.
+
+
+Example 'Hello World' API implementation
+----------------------------------------
+
+Consider we want to implement a new API /v1/example that returns "hello world" json.
+
+#. Create a python module inside api/v1 directory that
+   handles the API call
+
+        .. code-block:: python
+
+           #valence/api/v1/example.py
+
+           from flask import request
+           from flask_restful import Resource
+           import logging
+
+           LOG = logging.getLogger(__name__)
+
+           class Example(Resorce):
+               def get(self):
+               LOG.debug("GET /example")
+               return {“msg” : “hello world”}
+
+      .. note:: Check the valence/common/utils.py for commonly used functions
+                and valence/common/exceptions.py for valence structured
+                errors and standard confirmation messages.
+
+#. Add a new route at 'routes.py' to receive requests at particular URL extension
+
+        .. code-block:: python
+
+           from valence.api.v1.example import Example
+           ...
+           ...
+           api.add_resource(Example, '/v1/example',
+                                       endpoint='example')
+
+#. Start/Restart the valence server
+
+        .. code-block:: bash
+
+           $ python -m valence.cmd.api
+
+        .. note:: Ensure config(/etc/valence/valence.conf) and
+                  log(/var/log/valence/valence.log) files exists.
+
+
+#. Test the service manually by issuing a GET request to /v1/example
+
+        .. code-block:: bash
+
+           $ curl http://localhost:8181/v1/example
+
+
+#. Run tox testing to check pep8 and python2.7 compatibility. This
+   should be ran from the valence root directory(where tox.ini is
+   present)
+
+        .. code-block:: bash
+
+           $ tox -e pep8,py27
+
+
+#. Update the automated testing scripts to include the new API.
+        .. include:: add_new_functional_testing.rst
+

doc/source/developer-guide/add_new_functional_testing.rst

@@ -0,0 +1,83 @@
+.. _valence_functional_testcase:
+      Copyright 2016 Intel Corporation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+============================
+Addng a Functional Test case
+============================
+
+Getting used to writing testing code and running this code in parallel is considered
+as a good workflow.
+Whenever an API for valence is implemented, it is necessary to include
+the corresponding testcase in the testing framework.
+Currently, valence uses pythons unittest module for running the testcases.
+
+Tests scripts are located in `<valence_root>/valence/tests
+<https://github.com/openstack/rsc/tree/master/valence/tests>`_ directory
+
+.. NOTE::
+      valence/tests/__init__.py contains the base class for FunctionalTest
+
+
+Implementing a Test Case
+------------------------
+
+Consider implementing an functional testcase for our /example(add_new_api_) API
+
+
+The characteristics of /example(add_new_api_) API
+
+* REST Method : GET
+* Parameters  : Nil
+* Expected Response Status : 200
+* Expected Response JSON   : {“msg” : “hello world”}
+
+To implement a testcase for the /example api,
+
+Create a class in valence/tests/functional/test_functional.py
+which inherits the FunctionalTest class from valence/tests/__init__.py
+i.e.
+
+  .. code-block:: python
+
+    # valence/tests/functional/test_functional.py
+
+    class TestExampleController(FunctionalTest):
+
+        def test_example_get(self):
+            response = self.app.get('/example')
+            #Call GET method of /example from Flask APP
+            #If REST call went fine, we expect HTTP STATUS 200 along with JSON
+            assert response.status_code == 200
+            #Test the status
+            assert response["msg"] == "hello world"
+            #Test the response message
+            #likely we could test headers for content-type..etc
+
+        def test_example_post(self):
+            #suppose consider if POST is implemented & returns STATUS 201
+            response = self.app.post('/example')
+            assert response.status_code == 201
+
+The above is a very basic example which could be extended to test complex JSONs
+and response headers.
+
+Also for every new code added, it is better to do pep8 and other python automated
+syntax checks. As we have tox integrated in to valence, this could be achieved by,
+running the below command from the valence root directory(where tox.ini is present)
+
+        .. code-block:: bash
+
+           $ tox -e pep8,py27

doc/source/developer-guide/deploy.rst

@@ -0,0 +1,29 @@
+.. _valence_deploy:
+
+      Copyright 2016 Intel Corporation
+      All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+This document describes how to update the code base of Valence after installation.
+Whenever valence code has been updated, either through git or modifying it locally,
+it needs to be deployed to standard python path. The below steps describes them.
+
+Execure the below bash commands in the valence root directory
+(where the setup.py file exists)
+
+ .. code-block:: bash
+
+    $ python setup.py install
+    $ sudo service valence restart

doc/source/index.rst

@@ -16,6 +16,13 @@ Contents:
    usage
    contributing
 
+Developers Documentation
+========================
+.. toctree::
+   :maxdepth: 2
+
+   developer-guide/*
+
 Indices and tables
 ==================