Add quick start guide to RST documentation.

Change-Id: I33f8fd242745a8779cb6133a37fc91e8f34bb22a

README.rst

@@ -20,4 +20,4 @@ Links
 * Documentation: `Tobiko Documentation <https://docs.openstack.org/>`__
 * Source: https://opendev.org/x/tobiko.git
 * Bugs: `StoryBoard <https://storyboard.openstack.org/#!/project/x/tobiko>`__
-* Usage: `Quick Start Guide <https://opendev.org/x/tobiko/src/branch/master/doc/quick-start.md>`__
+* Usage: `Quick Start Guide <https://opendev.org/x/tobiko/src/branch/master/doc/source/user/index.rst>`__

doc/quick-start.md

@@ -1,74 +0,0 @@
-# Quick start guide
-
-## Install Tobiko
-sudo yum install python-virtualenv
-virtualenv path/to/yuor/venv
-source path/to/yuor/venv/bin/activate
-pip install tobiko
-
-## Set up credentials
-
-In order to run the tests successfully you'll need to set up OpenStack credentials.
-You can do it in one of two ways:
-
-1. Using environment variables.
-   Either by downloading the credentials file directly from your OpenStack project or
-   setting them up manually like this:
-
-       export API_VERSION = 2
-       export OS_USERNAME = admin
-       export OS_PASSWORD = admin
-       export PROJECT_NAME = admin
-       export OS_USER_DOMAIN_NAME="Default"
-       export OS_PROJECT_DOMAIN_NAME = admin
-       export OS_AUTH_URL=https://my_cloud:13000/v3
-
-
-2. Setting up tobiko.conf file with the following format:
-
-       api_version = 2
-       username = admin
-       password = admin
-       project_name = admin
-       user_domain_name = admin
-       project_domain_name = admin
-       auth_url = http://my_cloud:13000/v3
-
-## Run Tests
-
-To run neutron tests, use the following command:
-
-    tox -e neutron
-
-
-## Quick Start Setup&Run Template:
-```bash
-sudo yum install python-virtualenv.noarch -y
-virtualenv ~/tobiko_venv && source ~/tobiko_venv/bin/activate
-wget https://bootstrap.pypa.io/get-pip.py
-python get-pip.py
-pip install tox
-sudo yum install gcc python-devel -y
-git clone https://opendev.org/x/tobiko.git
-cd tobiko
-pip install -r extra-requirements.txt; pip install .
-
-. ~/overcloudrc
-wget http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img
-openstack image create "cirros" \
-  --file cirros-0.3.5-x86_64-disk.img \
-  --disk-format qcow2 --container-format bare \
-  --public
-openstack flavor create --id 0 --vcpus 1 --ram 64 --disk 1 m1.tiny
-
-cat > tobiko.conf <<EOF
-[neutron]
-floating_network='public'
-[nova]
-image='cirros'
-flavor = 'm1.tiny'
-EOF
-
-tox -e neutron |& tee tox_neutron.out
-
-```

doc/source/index.rst

@@ -8,7 +8,7 @@ Test Big Cloud Operations
 Tobiko is a project used to write system tests for OpenStack. Main projects
 goals are:
 
-- Provide a Python framewor to write system scenario test cases
+- Provide a Python framework to write system scenario test cases
 - Provide CLI tools to implement a workflow designed to test potentially
   destructive operations.
 
@@ -19,7 +19,7 @@ Links
 * Documentation: `Tobiko Documentation <https://docs.openstack.org/>`__
 * Source: https://opendev.org/x/tobiko.git
 * Bugs: `StoryBoard <https://storyboard.openstack.org/#!/project/x/tobiko>`__
-* Usage: `Quick Start Guide <https://opendev.org/x/tobiko/src/branch/master/doc/quick-start.md>`__
+* Usage: `Quick Start Guide <https://opendev.org/x/tobiko/src/branch/master/doc/source/user/index.rst>`__
 
 
 Document Overview

doc/source/install/index.rst

@@ -1,13 +1,15 @@
-============
+.. _tobiko-install-guide:
-Installation
+
-============
+=========================
+Tobiko Installation Guide
+=========================
 
 
 Document Overview
 -----------------
 
 This document describes how to install Tobiko inside a Python virtualenv. For
-a quick and simpler start you can jump to the Quick Start Guide.
+a quick and simpler start you can jump to the :ref:`quick-start-guide`.
 
 
 Install Tobiko Using Virtualenv
@@ -24,7 +26,7 @@ Make sure pip and setuptools are installed and up-to date::
     sudo python get-pip.py
     sudo pip install --upgrade setuptools
 
-Make sure tox, virtualenv and wheel are installed and up to date::
+Make sure virtualenv and wheel are installed and up to date::
 
     sudo pip install --upgrade tox virtualenv wheel
 

doc/source/user/index.rst

@@ -1,3 +1,8 @@
 =================
 Tobiko User Guide
 =================
+
+.. toctree::
+   :maxdepth: 2
+
+   quick-start

doc/source/user/quick-start.rst

@@ -0,0 +1,136 @@
+.. _quick-start-guide:
+
+=================
+Quick Start guide
+=================
+
+
+Document Overview
+-----------------
+
+This document describes how to install execute Tobiko scenarios test cases
+using Tox. To install Tobiko inside a virtualenv directory please refers to
+:ref:`tobiko-install-guide`.
+
+
+Install Required Packages
+-------------------------
+
+Make sure Gcc, Git and base Python packages are installed on your system.
+For instance on RHEL Linux you could type::
+
+    sudo yum install -y gcc git python python-devel
+
+Make sure pip and setuptools are installed and up-to date::
+
+    wget https://bootstrap.pypa.io/get-pip.py
+    sudo python get-pip.py
+    sudo pip install --upgrade setuptools
+
+Make sure tox, virtualenv and wheel are installed and up to date::
+
+    sudo pip install --upgrade tox virtualenv wheel
+
+
+Get Tobiko
+----------
+
+Get Tobiko source code using Git::
+
+    git clone https://opendev.org/x/tobiko.git
+    cd tobiko
+
+
+Configure Tobiko Credentials
+----------------------------
+
+In order to run the tests successfully you'll need to set up OpenStack
+credentials. You can do it in one of below ways:
+
+- :ref:`credentials-from-env`
+- :ref:`credentials-from-config`
+
+
+.. _credentials-from-env:
+
+Set Tobiko Credentials Via Environment Variables
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use an existing shell rc file that is valid for Python OpenStack
+client::
+
+    source openstackrc
+
+An example of 'openstackrc' file could looks like below::
+
+    export API_VERSION=2
+    export OS_USERNAME=admin
+    export OS_PASSWORD=secret
+    export PROJECT_NAME=admin
+    export OS_USER_DOMAIN_NAME=Default
+    export OS_PROJECT_DOMAIN_NAME=admin
+    export OS_AUTH_URL=https://my_cloud:13000/v3
+
+
+.. _credentials-from-config:
+
+Set Tobiko Credentials Via 'tobiko.conf' File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Create a file at ~/.tobiko/tobiko.conf adding a section like below::
+
+    [keystone]
+    api_version = 2
+    username = admin
+    password = secret
+    project_name = admin
+    user_domain_name = admin
+    project_domain_name = admin
+    auth_url = http://my_cloud:13000/v3
+
+
+Create Required Resources
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Install Python OpenStack client::
+
+    source overcloudrc
+    sudo pip install python-openstackclient \
+                     python-novaclient \
+                     python-glanceclient
+
+Create an image for Nova instances created by Tobiko::
+
+    wget http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img
+    openstack image create "cirros" \
+      --file cirros-0.3.5-x86_64-disk.img \
+      --disk-format qcow2 \
+      --container-format bare \
+      --public
+
+Create a flavor to be used with above image::
+
+    openstack flavor create --id 0 --vcpus 1 --ram 64 --disk 1 m1.tiny
+
+Add reference to above resources into your `tobiko.conf` file::
+
+    [nova]
+    image = cirros
+    flavor = m1.tiny
+
+
+Configure Public Network Name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Add reference to the network where Tobiko should create floating IP instances::
+
+    [neutron]
+    floating_network = public
+
+
+Run Test Cases
+--------------
+
+Run Tobiko scenario test cases using Tox::
+
+    tox -e scenario

doc/usage.md

@@ -1,12 +0,0 @@
-# Tobiko Usage Examples
-
-
-## Faults
-
-Use `tobiko-fault` to run only faults, without running resources population or tests.
-
-Note: `tobiko-fault` can executed only from undercloud node.
-
-To restart openvswitch service, run the following command:
-
-    tobiko-fault --fault "restart openvswitch service"