Rename doc folder

The Jenkins job that triggers the creation of documents looks for
docs folder[1], in order to be covered by this job it's necessary to
adapt to this convention.

[1] https://git.onap.org/ci-management/tree/jjb/doc/doc-templates-rtd.yaml

Change-Id: Ieca92084d95b0ef4736223b1ea60cb0f9c688550
Signed-off-by: Victor Morales <victor.morales@intel.com>
Issue-ID: DOC-261

5 files changed, 416 insertions, 0 deletions

diff --git a/docs/source/features/configure_execution.rst b/docs/source/features/configure_execution.rst
new file mode 100644
index 0000000..df08605
--- /dev/null
+++ b/docs/source/features/configure_execution.rst
@@ -0,0 +1,72 @@
+=======================
+Modify execution values
+=======================
+
+In order to provide a flexible platform that adjusts to different developer
+needs, there are two mechanisms to configure the execution of this project.
+
+Settings configuration file
+---------------------------
+
+The first mechanism refers to the process to replace default configuration
+values in the settings configuration file. This file needs to be placed into
+the *./etc* folder and named *settings.yaml*. It must contain the key/pair
+configuration values that will be overriden.
+
+.. note::
+
+    There are sample files (e. g. settings.yaml.development and
+    settings.yaml.testing) placed into the *./etc* folder. Their purpose is to
+    provide a reference of different configurations.
+
+.. end
+
+Configuration values:
+
++------------------+-------------------+---------------------------------------+
+| Key              | Values            | Description                           |
++==================+===================+=======================================+
+| build_image      | "True" or "False" | Determines if the Docker image is     |
+|                  |                   | retrieved from public hub or built    |
+|                  |                   | from source code.                     |
++------------------+-------------------+---------------------------------------+
+| clone_repo       | "True" or "False" | Determines if all the source code     |
+|                  |                   | repositories of a given component are |
+|                  |                   | cloned locally.                       |
++------------------+-------------------+---------------------------------------+
+| compile_repo     | "True" or "False" | Determines if all the source code     |
+|                  |                   | repositories of a given component are |
+|                  |                   | going to be compiled.                 |
++------------------+-------------------+---------------------------------------+
+| enable_oparent   | "True" or "False" | Determines if the OParent project     |
+|                  |                   | will be used during the maven         |
+|                  |                   | compilation.                          |
++------------------+-------------------+---------------------------------------+
+| skip_get_images  | "True" or "False" | Determines if the process to build or |
+|                  |                   | retrieve docker images of a given     |
+|                  |                   | component are going to skipped.       |
++------------------+-------------------+---------------------------------------+
+| skip_install     | "True" or "False" | Determines if the process to start    |
+|                  |                   | the services of a given component     |
+|                  |                   | will be started.                      |
++------------------+-------------------+---------------------------------------+
+
+Parameters
+----------
+
+The **skip_get_images** and **skip_install** are the only two configuration
+values that can be overriden using *-g* and *-i* respectively by the run scripts
+(*./tools/run.sh* and *.\\tools\\Run.ps1*).
+
+.. note::
+
+    The script parameters take precendence of the configuration file.
+
+.. end
+
+.. code-block:: console
+
+   $ ./tools/run.sh sdc -g
+
+.. end
+
diff --git a/docs/source/features/consuming_scripts.rst b/docs/source/features/consuming_scripts.rst
new file mode 100644
index 0000000..4290c25
--- /dev/null
+++ b/docs/source/features/consuming_scripts.rst
@@ -0,0 +1,88 @@
+==============================
+Using the provisioning scripts
+==============================
+
+Vagrant is a platform that uses prebaked images called
+*vagrant boxes* to guarranty that running multiple times a
+provisioning script will result in an expected output. This
+mechanism is crucial for reducing the number of external factors
+during the creation, development and testing of provisioning scripts. 
+However, it's possible to provide an ONAP development enviroment
+without having to install Vagrant tool. This document explains how to
+consume the provisioning scripts localed in **./lib** folder to
+provision a development environment and the environment variables
+that modifies their behavior.
+
+This project was built on an Ubuntu 14.04 ("Trusty") Operating System,
+therefore it's necessary to have an user who has *sudo* permissions to
+access to a Bare Metal or Virtual Machine.
+
+The following instructions retrieve the provisioning scripts and place
+them into the */var/onap/* folder.
+
+.. code-block:: console
+
+    $ sudo apt-get install git -y
+    $ git clone https://git.onap.org/integration/devtool
+    $ cd /var/
+    $ ln -s ~/devtool/lib/ ./onap
+
+.. end
+
+Loading a provisioning script will be based on the desired ONAP
+service, for example to setup the development environment for Active
+and Available Inventory (AAI) service will be required to load the
+*/var/onap/aai* script.
+
+.. note::
+
+    The **git_src_folder** environment variable specifies the
+    source code destination folder, it's default value is */opt/onap/*
+    but it can be changed only after is loaded the provisioning
+    scripts.
+
+.. end
+
+.. code-block:: console
+
+    # source /var/onap/aai
+
+.. end
+
+Lastly, every script has defined a initialization function with
+*init_* as prefix. This function is the starting point to provision
+the chosen ONAP service. This example uses the *init_aai* function
+to provision a AAI Developement environment.
+
+.. note::
+
+    The **compile_repo** environment variable defines whether or not
+    the source code located on the repositories of the service.
+    Enabling this value can impact the provisioning time of the
+    service.
+
+.. end
+.. note::
+
+    **nexus_docker_repo**, **nexus_username** and **nexus_password**
+    environment variables specify the connectivity to a private Docker
+    Hub.
+
+.. end
+.. note::
+
+    **build_image** environment variable allows the Docker images
+    from source code.  Enabling this value can impact the
+    provisioning time of the service.
+
+.. end
+
+.. code-block:: console
+
+    # init_aai
+
+.. end
+
+As result, the source code is pulled into */opt/onap/aai/* folder and the
+AAI services are up and running with the proper connection to the
+Titan Distributed Graph Database.
diff --git a/docs/source/features/example_usage.rst b/docs/source/features/example_usage.rst
new file mode 100644
index 0000000..1aae887
--- /dev/null
+++ b/docs/source/features/example_usage.rst
@@ -0,0 +1,151 @@
+=================================================
+Example usage to bring up a developer environment
+=================================================
+
+In the example, we will bring up a single ONAP component using the Devtool ONAP
+tool.
+
+There are multiple scenarios in which this tool can be made use of by a
+developer, they usually fall in the following use cases.
+
+Use case 1: Use Devtool ONAP to just clone project related source code
+----------------------------------------------------------------------
+
+In this use case, the developer needs just the source code of the project to work on.
+
+Since the Devtool ONAP project supports building docker containers and compiling
+source files, we need to first edit the settings.yaml file to add key value pairs
+indicating we need to only clone repo and not build docker image or compile then.
+By default, Devtool ONAP clones repo, but to not run the build process and cloning
+docker images, the following are required to be added in the settings file.
+
+.. code-block:: console
+
+    skip_get_images: "True"
+
+.. end
+
+The reason this is done is because as mentioned in the
+`configure execution docs. <https://git.onap.org/integration/devtool/tree/doc/source/features/configure_execution.rst>`,
+the default values taken are:
+
+.. code-block:: console
+
+    'build_image'         => 'True',
+    'clone_repo'          => 'True',
+    'compile_repo'        => 'False',
+    'enable_oparent'      => 'True',
+    'skip_get_images'     => 'False',
+    'skip_install'        => 'True'
+
+.. end
+
+We override them and skip_get_images is given precedence over build_image.
+
+Use case 2: Use Devtool ONAP to clone project related source code and clone Docker Images
+-----------------------------------------------------------------------------------------
+
+In this use case, the developer needs to clone docker images of the project to work on.
+
+For this case, we will edit the settings.yaml file to add key value pairs indicating we
+need to clone repo and clone docker image from Nexus.
+
+.. code-block:: console
+
+    build_images: "False"
+    compile_repo: "True"
+    skip_get_images: "False"
+    skip_install: "True"
+
+.. end
+
+Use case 3: Use Devtool ONAP to clone project related source code and build Docker Images locally
+-------------------------------------------------------------------------------------------------
+
+In this use case, the developer needs to build docker images of the project to work on.
+
+For this case, we will edit the settings.yaml file to add key value pairs indicating we need to
+clone repo and build docker image locally and not fetch them from Nexus.
+
+.. code-block:: console
+
+    build_images: "True"
+    compile_repo: "True"
+    skip_get_images: "False"
+    skip_install: "True"
+
+.. end
+
+Use case 4: Use Devtool ONAP to clone project related source code and build Docker Images and start services
+------------------------------------------------------------------------------------------------------------
+
+In this use case, the developer needs to build docker images of the project he or
+she wanted to work on and start the services running inside them.
+
+For this case, we will edit the settings.yaml file to add key value pairs indicating
+we need to clone repo, compile repo, build docker image and run the image.
+
+.. code-block:: console
+
+    build_images: "True"
+    compile_repo: "True"
+    skip_get_images: "False"
+    skip_install: "False"
+
+.. end
+
+Once the required changes to the settings file is added, we can use the run.sh
+script in tools directory to setup the development environment.
+
+Example steps for setting up a development environment for VFC project.
+-----------------------------------------------------------------------
+
+In this example we will be using Devtool ONAP to get all the source code of VFC
+project and the developer can point the IDE to the cloned repo in the ./opt directory
+and start the development process.
+
+.. code-block:: console
+
+   $ ./tools/run.sh vfc
+
+.. end
+
+At the end of the setup process, all the VFC related source code will be present
+in the devtool/opt/ directory. The developer can point an IDE to this directory
+and start contributing. When the changes are done, the developer can SSH into the VM
+running VFC and tests can be executed by running Maven for Java and Tox for Python
+from the ~/opt/vfc directory.
+
+.. code-block:: console
+
+   $ vagrant ssh vfc
+   $ cd ~/opt/onap/vfc/<vfc-subrepo>
+   $ tox -e py27
+
+.. end
+
+This way the tool helps the developer to clone repos of a particular project,
+without having to manually search for repos and setup an environment.
+
+Also, if something gets messed up in the VM, the developer can tear down the VM
+and spin a fresh one without having to lose the changes made to the source code since
+the ./opt files are in sync from the host to the VM.
+
+.. code-block:: console
+
+   $ vagrant destroy vfc
+
+.. end
+
+Testing
+-------
+
+Use the run.sh script to test if the provisioning scripts run without errors.
+
+And example test to check the number of covered repositories with this tool.
+
+.. code-block:: console
+
+   $ ./tools/run.sh testing -y -c coverity_repos -s functions
+
+.. end
diff --git a/docs/source/features/features.rst b/docs/source/features/features.rst
new file mode 100644
index 0000000..9055301
--- /dev/null
+++ b/docs/source/features/features.rst
@@ -0,0 +1,16 @@
+.. _features:
+
+=================
+Advanced features
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   openstack.rst
+   consuming_scripts.rst
+   configure_execution.rst
+   example_usage.rst
+
+This chapter explains how to use Devtool ONAP tool for Advanced features
+like different providers.
diff --git a/docs/source/features/openstack.rst b/docs/source/features/openstack.rst
new file mode 100644
index 0000000..f44bc62
--- /dev/null
+++ b/docs/source/features/openstack.rst
@@ -0,0 +1,89 @@
+==================
+OpenStack Provider
+==================
+
+It's possible to use Vagrant to provision VMs on OpenStack using the
+`Vagrant OpenStack Cloud Provider <https://github.com/ggiamarchi/vagrant-openstack-provider/>`.
+The only requirement for the Cloud provider is to have an Ubuntu Cloud
+image accesible to your tenant and a Security Rule that allows to do
+SSH into the instance.
+
+Environment variables
+---------------------
+
+The usage of environment variables in OpenStack command-line clients
+is to avoid repeating some values.  These variables have *OS_* as
+prefix. This provider will use them for authentication to Keystone
+service.
+
+.. code-block:: console
+
+    export OS_AUTH_URL=http://<keystone_ip>:5000/v3
+    export OS_TENANT_NAME=<project_or_tenant_name>
+    export OS_PROJECT_NAME=<project_or_tenant_name>
+    export OS_USERNAME=<openstack_username>
+    export OS_PASSWORD=<openstack_password>
+    export OS_REGION_NAME=<openstack_region_name>
+    export OS_IDENTITY_API_VERSION=<keystone_version_number>
+    export OS_PROJECT_DOMAIN_ID=<openstack_domain_name>
+
+.. end
+
+OpenStack Vagrant provider needs additional information about the
+name of the image to be used and the networking where the instance
+will be provisioned.  That information can be passed using the
+following variables
+
+.. code-block:: console
+
+    export OS_IMAGE=<ubuntu_cloud_image_name>
+    export OS_NETWORK=<neutron_private_network>
+    export OS_FLOATING_IP_POOL=<neutron_floating_ip_pool>
+    export OS_SEC_GROUP=<onap-ssh-secgroup>
+
+.. end
+
+Tenant setup
+------------
+
+The *tools/setup_openstack.sh* script can be useful to get an idea
+of the process to setup the OpenStack environment with the necessary
+requirements. This script depends on the Environment Variables
+explained previously.
+
+----
+
+Devstack
+--------
+
+It's possible to use this plugin to provision instances on
+`Devstack <https://docs.openstack.org/devstack/latest/>`. This is
+an example of the *local.conf* file that can be used as input
+for Devstack
+
+.. path local.conf
+.. code-block:: ini
+
+    [[local|localrc]]
+    ADMIN_PASSWORD=<password>
+    DATABASE_PASSWORD=<password>
+    RABBIT_PASSWORD=<password>
+    SERVICE_PASSWORD=<password>
+    SERVICE_TOKEN=<token>
+
+    # Used to only upload the Ubuntu Cloud Image
+    DOWNLOAD_DEFAULT_IMAGES=False
+    IMAGE_URLS+="http://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-disk1.img"
+
+    # (Optional) These values helps to improve the experience deploying and using Devstack
+    GIT_BASE=https://git.openstack.org
+    FORCE_CONFIG_DRIVE="True"
+    disable_service tempest
+
+.. end
+
+.. note::
+
+    There is a validation that checks if the
+    *vagrant-openstack-provider* plugin is installed raising an error
+    for those cases when it isn't.