Document integration of the tool

Document and show example how to integrate python-tempetsconf
with a different project.

Change-Id: I3757d298653dfb243d1b710759f9550a9e27c8a7
Story: 2002703
Task: 22574

doc/source/index.rst

@@ -9,7 +9,8 @@ Welcome to python-tempestconf's documentation!
 python-tempestconf is a tool for automatic generation of tempest configuration
 based on user's cloud.
 
-Contents:
+Content:
+--------
 
 .. toctree::
    :maxdepth: 2
@@ -19,8 +20,6 @@ Contents:
    user/index
    contributor/index
 
-Indices and tables
-==================
 
 * :ref:`genindex`
 * :ref:`search`

doc/source/install/installation.rst

@@ -44,3 +44,10 @@ RPM Installation (RDO)
 
     $ sudo yum install openstack-tempest
 
+
+Pip installation
+----------------
+
+Install `python-tempestconf` via pip as follows::
+
+   $ pip install python-tempestconf

doc/source/user/import.rst

@@ -0,0 +1,193 @@
+=======================================
+Use python-tempestconf as Python module
+=======================================
+
+`python-tempestconf` can be imported and used from a different Python project.
+
+.. warning::
+
+    The import of config_tempest is possible only when the tool is installed
+    from **master branch** or via pip, however, **python-tempestconf-2.0.0.
+    or newer has to be installed**.
+
+Installation
+++++++++++++
+
+See our `Install Guide`_ on how to install `python-tempestconf`.
+
+.. _Install Guide: ../install/installation.html
+
+Import
+++++++
+
+Import python-tempestconf in your project as follows:
+
+.. code-block:: Python
+
+    from config_tempest import main as tempestconf
+
+python-tempestconf needs cloud credentials in order to create a tempest
+configuration file. There is a helper method for obtaining cloud credentials
+which uses
+`os-client-config <https://docs.openstack.org/os-client-config/latest/user/configuration.html>`_
+for parsing the cloud for credentials.
+
+The following example shows how to get cloud credentials and how to pass it to
+the configuration tool:
+
+.. code-block:: Python
+
+    # The following call will return a dict containing cloud credentials,
+    # for example:
+    # >>> tempestconf.get_cloud_creds(args_namespace)
+    # {
+    #     'username': 'demo',
+    #     'project_name': 'demo',
+    #     'user_domain_name': 'Default',
+    #     'auth_url': 'http://172.16.52.8:5000/v3',
+    #     'password': 'f0921edc3c2b4fc8',
+    #     'project_domain_name': 'Default'
+    # }
+    cloud_creds = tempestconf.get_cloud_creds(args_namespace)
+
+    # Then the configuration step can be run using:
+    tempestconf.config_tempest(cloud_creds=cloud_creds)
+
+.. note::
+
+    If `args_namespace` contains **--os-cloud** argument, the `get_cloud_creds`
+    method returns cloud credentials related to that cloud, otherwise, returns
+    credentials of the current cloud (according to the sourced credentials).
+
+
+List of arguments which may be passed to `config_tempest`
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+ * cloud_creds
+ * create
+ * create_accounts_file
+ * debug
+ * deployer_input
+ * image_disk_format
+ * image_path
+ * network_id
+ * non_admin
+ * os_cloud
+ * out
+ * overrides
+ * remove
+ * test_accounts
+ * verbose
+
+.. note::
+
+    For detailed description of the options see our `CLI documentation`_
+
+    .. _CLI documentation: ../cli/cli_options.html
+
+
+Example implementation
+++++++++++++++++++++++
+
+1. Save following code snippet as `example.py`:
+
+    .. code-block:: Python
+
+        import argparse
+        from config_tempest import main as tempestconf
+
+        parser = argparse.ArgumentParser(description='Example implementation.')
+        args = parser.parse_args()
+
+        # gets credentials of the current cloud according to
+        # the sourced credentials
+        cloud_creds = tempestconf.get_cloud_creds(args)
+
+        tempestconf.config_tempest(non_admin=True,
+                                   out='./etc/tempest.conf',
+                                   cloud_creds=cloud_creds)
+
+2. Source your OpenStack RC file containing the cloud credentials. Let's say
+   you have a overcloud_rc file with the following content:
+
+    .. code-block:: Bash
+
+        $ cat overcloud_rc
+        unset OS_SERVICE_TOKEN
+        export OS_USERNAME=demo
+        export OS_PASSWORD='password'
+        export OS_AUTH_URL=http://172.16.52.15/identity/v3
+        export PS1='[\u@\h \W(keystone_demo)]\$ '
+        export OS_PROJECT_NAME=demo
+        export OS_USER_DOMAIN_NAME=default
+        export OS_PROJECT_DOMAIN_NAME=default
+        export OS_IDENTITY_API_VERSION=3
+
+   Then it can be source by:
+
+    .. code-block:: Bash
+
+        $ source overcloud_rc
+
+
+3. Run the `example.py`:
+
+    .. code-block:: Bash
+
+        $ python example.py
+
+
+Example implementation with a named cloud
++++++++++++++++++++++++++++++++++++++++++
+
+1. Let's say there is a `clouds.yaml` file located in `/etc/openstack/` with
+   the following content:
+
+    .. code-block:: Bash
+
+        $ cat /etc/openstack/clouds.yaml
+        clouds:
+          devstack:
+            auth:
+              auth_url: http://172.16.52.15/identity/v3
+              password: password
+              project_domain_id: default
+              project_name: demo
+              user_domain_id: default
+              username: demo
+            identity_api_version: '3'
+            region_name: RegionOne
+            volume_api_version: '2'
+
+
+2. Save following code snippet as an `example.py`:
+
+    .. code-block:: Python
+
+        import argparse
+        from config_tempest import main as tempestconf
+
+        parser = argparse.ArgumentParser(description='Example implementation.')
+        # Let's add an os_cloud option which will be passed
+        # to config_tempest later.
+        parser.add_argument('--os-cloud', help='Name of a named cloud.')
+        args = parser.parse_args()
+
+        # gets credentials to the devstack cloud
+        cloud_creds = tempestconf.get_cloud_creds(args)
+
+        tempestconf.config_tempest(non_admin=True,
+                                   out='./etc/tempest.conf',
+                                   cloud_creds=cloud_creds)
+
+3. Run the `example.py`:
+
+    .. code-block:: Bash
+
+        $ python example.py --os-cloud devstack
+
+    .. note::
+
+        In this example you **don't need** to source cloud credentials. The
+        credentials are obtained from the `/etc/openstack/clouds.yaml`
+        thanks to `--os-cloud` argument.

doc/source/user/index.rst

@@ -6,3 +6,4 @@ Usage
   :includehidden:
 
   usage
+  import