Add missing developer-guide docs

Add missing developer docs for unit test, etcd db and writing
developer guide.
Fix errors occurred when building developer docs with Sphinx :
   # tox -e docs
Fix some other nits.

Change-Id: I8580af70630edd0c214645ce4b6bbcd308925aa1
Closes-Bug: #1653198
Signed-off-by: Andy Yan <yanchao3@lenovo.com>

doc/source/developer-guide/add_new_developer_guide.rst

@@ -0,0 +1,46 @@
+.. _valence_add_new_developer_guide:
+      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 developer guide doc
+============================
+
+Adding a new developer guide document generally takes three steps:
+
+1. Write an rst file for doc
+----------------------------
+
+Write a new rst file for developer guide document,
+which should be placed correspondingly in valence/doc/source.
+
+2. Check TOC tree for docs
+--------------------------
+
+We should check TOC tree ref for your newly added rst file,
+ensure that your rst file can be generated according to valence/doc/source/index.rst.
+
+3. Generate docs
+----------------
+
+Regenerate all the docs including your newly added rst file:
+        .. code-block:: bash
+
+           $ tox -e docs
+
+Or, directly run sphinx in valence/doc:
+        .. code-block:: bash
+
+           $ python setup.py build_sphinx

doc/source/developer-guide/add_new_functional_testing.rst

@@ -14,9 +14,9 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-============================
+==========================
-Addng a Functional Test case
+Add a Functional Test case
-============================
+==========================
 
 Getting used to writing testing code and running this code in parallel is considered
 as a good workflow.
@@ -25,7 +25,7 @@ the corresponding testcase in the testing framework.
 Currently, valence uses pythons unittest module for running the test cases.
 
 Tests scripts are located in `<valence_root>/valence/tests
-<https://github.com/openstack/rsc/tree/master/valence/tests>`_ directory
+<https://github.com/openstack/valence>`_ directory
 
 .. NOTE::
       valence/tests/__init__.py contains the base class for FunctionalTest

doc/source/developer-guide/add_new_unit_test.rst

@@ -0,0 +1,72 @@
+.. _valence_unit_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.
+
+======================
+Add a Unit Test case
+======================
+
+Getting used to writing testing code and running this code in parallel is considered
+a good workflow.
+Whenever an API for valence is implemented, it is necessary to include
+the corresponding unit test case in the testing framework.
+Currently, when adding a unit test, valence uses basic libraries e.g. unittest, mock.
+
+Unit tests scripts are located in `<valence_root>/valence/tests/unit/
+<https://github.com/openstack/rsc/tree/master/valence/tests/unit>`_ directory
+
+.. NOTE::
+      Place your unit test in the corresponding directory in valence/tests/unit.
+
+      "valence/tests/unit/fakes" contains the fake data for all the units.
+
+
+Implement a Unit Test Case
+-----------------------------
+
+Consider implementing an unit test case for our example unit module.
+
+To implement an unit test case for the example unit module,
+
+Create a class in valence/tests/unit/(directory)/test_(example).py,
+which inherits the TestCase class from unittest.
+i.e.
+
+  .. code-block:: python
+
+    # valence/tests/unit/redfish/test_redfish.py
+
+    class TestRedfish(TestCase):
+
+        # This should be any function name your want to test
+        def test_get_rfs_url(self):
+            cfg.podm_url = "https://127.0.0.1:8443"
+            expected = urljoin(cfg.podm_url, "redfish/v1/Systems/1")
+
+            # test without service_ext
+            result = redfish.get_rfs_url("/Systems/1/")
+            self.assertEqual(expected, result)
+
+Also if you want to add fakes data in unit test,
+please put fakes data in "valence/tests/unit/fakes",
+which should be named valence/tests/unit/fakes/(example)_fakes.py.
+
+For every bit of 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/db_development.rst

@@ -0,0 +1,92 @@
+.. _valence_db_development:
+      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.
+
+==============
+DB Development
+==============
+
+Valence uses Etcd as the management DB for handling multiple pod managers,
+as well as underneath hardware resources info.
+There is one root Etcd directory for the pod managers, named
+"/pod_managers".
+Each key-value pair under directory "/pod_managers" indicates
+information about one pod manager.
+
+.. NOTE::
+      All db layer codes are located in valence/db.
+
+
+Add a model for db
+------------------
+
+Models are defined in the valence/db/models.py file. A new model
+should be updated there.
+
+To add a example model for Etcd db, we should create
+a class that inherits the ModelBase class in valence/db/models.py.
+
+.. NOTE::
+      If timestamp info is needed for this model,
+      please inherit ModelBaseWithTimestamp class instead.
+i.e.
+
+  .. code-block:: python
+
+    # valence/db/models.py
+
+    class ExampleModel(ModelBase):
+
+        # This is the Etcd dir the new model lives in
+        path = "example_model"
+
+        # The fields will be wrapped as a value for one object
+        fields = {
+            'uuid': {
+                'validate': types.Text.validate
+            },
+            'name': {
+                'validate': types.Text.validate
+            },
+
+        }
+
+
+Add a driver for model
+----------------------
+
+Etcd driver definition is in the file valence/db/etcd_driver.py.
+
+Considering adding operations for one example model,
+we should create a class in valence/db/etcd_driver.py.
+i.e.
+
+  .. code-block:: python
+
+    # valence/db/etcd_driver.py
+
+    @six.add_metaclass(singleton.Singleton)
+    class ExampleDriver(object):
+
+        def __init__(self, host=config.etcd_host, port=config.etcd_port):
+            self.client = etcd.Client(host=host, port=port)
+
+        def get_example_object(self, object_id):
+            pass
+
+        def create_example_object(self, values):
+            pass
+
+There should be more guides to be continued later.

doc/source/developer-guide/deploy.rst

@@ -15,12 +15,15 @@
       License for the specific language governing permissions and limitations
       under the License.
 
+======================
+Deploy Valence Project
+======================
 
 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
+Execute the below bash commands in the valence root directory
 (where the setup.py file exists)
 
  .. code-block:: bash

doc/source/index.rst

@@ -19,7 +19,7 @@ Contents:
 Developers Documentation
 ========================
 .. toctree::
-   :maxdepth: 2
+   :glob:
 
    developer-guide/*
 

valence/db/etcd_driver.py

@@ -47,7 +47,7 @@ def translate_to_models(etcd_resp, model_type):
 
 @six.add_metaclass(singleton.Singleton)
 class EtcdDriver(object):
-    """etcd API."""
+    """etcd Driver."""
 
     def __init__(self, host=config.etcd_host, port=config.etcd_port):
         self.client = etcd.Client(host=host, port=port)