[docs] Made additional updates to Tobiko documentation

Also reorganized a few things in a way I think makes them
a bit clearer, feel free to leave feedback in reviews

Change-Id: I879cb957ef35f9b6e1176a4528d8f9f5f33a4c90

doc/source/user/config.rst

@@ -27,11 +27,11 @@ Configure Tobiko Framework
 
 In order to make sure Tobiko tools can connect to OpenStack services via Rest
 API configuration parameters can be passed either via environment variables or
-via a ini configuration file (referred here as :ref:`tobiko-conf`). Please look
+via an INI configuration file (referred here as :ref:`tobiko-conf`). Please look
 at :ref:`authentication-methods` for more details.
 
 To be able to execute scenario test cases there some OpenStack resources that
-has to be created before running test cases. Please look at
+have to be created before running test cases. Please look at
 :ref:`setup-required-resources` for more details.
 
 
@@ -40,7 +40,7 @@ has to be created before running test cases. Please look at
 tobiko.conf
 ~~~~~~~~~~~
 
-Tobiko tries to load :ref:`tobiko-conf` file from one of below locations:
+Tobiko tries to load :ref:`tobiko-conf` file from one of the below locations:
 
 * current directory::
 
@@ -58,8 +58,8 @@ Tobiko tries to load :ref:`tobiko-conf` file from one of below locations:
 Configure Logging
 ~~~~~~~~~~~~~~~~~
 
-Tobiko can configure logging system to write messages to a log file. You can
-edit below options in :ref:`tobiko-conf` to enable it as below::
+Tobiko can configure a logging system to write messages to a log file. You can
+edit the below options in :ref:`tobiko-conf` to enable it as below::
 
     [DEFAULT]
     # Whenever to allow debugging messages to be written out or not
@@ -132,18 +132,19 @@ Currently supported variables are::
 
 .. _authentication-configuration:
 
-Autentication Configuration
-+++++++++++++++++++++++++++
+Authentication Configuration
+++++++++++++++++++++++++++++
 
 You can also configure the same authentication parameters by editing 'keystone'
 section in :ref:`tobiko-conf` file. For example::
 
     [keystone]
+
     # Identity API version
     api_version = 3
 
-    # URL to be used to connect to OpenStack Irentity Rest API service
-    auth_url=http://10.0.0.109:5000/v3
+    # URL to be used to connect to OpenStack Identity REST API service
+    auth_url = http://10.0.0.109:5000/v3
 
     # Authentication username (name or ID)
     username = admin
@@ -160,7 +161,7 @@ section in :ref:`tobiko-conf` file. For example::
     # Domain name or ID containing user
     user_domain_name = default
 
-    # Domain name or ID containing prject
+    # Domain name or ID containing project
     project_domain_name = default
 
     # ID of the trust to use as a trustee user
@@ -172,10 +173,10 @@ section in :ref:`tobiko-conf` file. For example::
 Proxy Server Configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The first thing to make sure is Tobiko can reach OpenStack services. In case
+The first thing to do is make sure Tobiko can reach OpenStack services. In case
 OpenStack is not directly accessible from where test cases or Tobiko CLI are
-executed it is possible to use an HTTP proxy server running on a network that
-is able to reach all OpenStack Rest API service. This can be performed
+executed, it is possible to use an HTTP proxy server running on a network that
+is able to reach all OpenStack REST API service. This can be performed
 by using below standard environment variables::
 
     export http_proxy=http://<proxy-host>:<proxy-port>/
@@ -190,7 +191,7 @@ For convenience it is also possible to specify the same parameters via
     https_proxy = http://<proxy-host>:<proxy-port>/
     no_proxy = 127.0.0.1,...
 
-Because Tobiko test cases could execute local commands (like for example ping)
+Because Tobiko test cases might execute local commands (like for example ping)
 to reach network services we have to specify in tobiko.conf file a shell
 (like OpenSSH client) to be used instead of the default local one
 ('/bin/sh')::
@@ -215,7 +216,7 @@ Setup Required Resources
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 To be able to execute Tobiko scenario test cases there some OpenStack
-resources that has to be created before running test cases.
+resources that have to be created before running test cases.
 
 Install required Python OpenStack clients::
 
@@ -241,16 +242,16 @@ in :ref:`tobiko-conf` file::
 Skipping resources creation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In some cases, for example when Tobiko is run after upgrade of cloud, it may be expected
-that resources used for tests should be already created. Tobiko should not try to create
-resources than and just run tests using what is already created.
-To configure Tobiko to not create test resources, environment variable ``TOBIKO_PREVENT_CREATE``
+In some cases, for example when Tobiko is run after an upgrade of a cloud, it may be expected
+that resources used for tests have already been created. Tobiko should not try to create
+resources than and just run tests using what has already been created.
+To configure Tobiko to not create test resources, the environment variable ``TOBIKO_PREVENT_CREATE``
 can be used::
 
     export TOBIKO_PREVENT_CREATE=True
 
 If this is set to ``True`` or ``1`` then Tobiko will not try to create resources like VMs,
-networks, routers or images and just run validation of what is exists in the cloud already.
+networks, routers, or images and just run validations of what exists in the cloud already.
 
 What's Next
 -----------

doc/source/user/install.rst

@@ -9,7 +9,7 @@ Document Overview
 -----------------
 
 This document describes how to install Tobiko inside a
-`Python Virtualenv <https://virtualenv.pypa.io/en/latest/>`__.
+`Python virtualenv <https://virtualenv.pypa.io/en/latest/>`__.
 
 .. sidebar:: See also
 
@@ -21,27 +21,27 @@ This document describes how to install Tobiko inside a
     To run Tobiko scenario test cases please look at
     :ref:`tobiko-test-case-execution-guide`.
 
-Install Tobiko Using Virtualenv
+Install Tobiko Using virtualenv
 -------------------------------
 
-Make sure Gcc, Git and base Python packages are installed on your system.
+Make sure gcc, Git and base Python packages are installed on your system.
 
-For instance on RHEL Linux 7.6 or CentOS 7 you could type::
+For instance on a RHEL7 or CentOS 7 machine you could type::
 
     sudo yum install -y gcc git python python-devel wget
 
-For instance on RHEL Linux 8 or CentOS 8 you could type::
+For instance on a RHEL8 or CentOS 8 machine you could type::
 
     sudo dnf install -y gcc git python3 python3-devel wget
     sudo alternatives --set python /usr/bin/python3
 
-Make sure pip is installed and up-to date::
+Make sure pip is installed and up-to-date::
 
     wget https://bootstrap.pypa.io/get-pip.py
     sudo python get-pip.py
     PIP=$(which pip)
 
-Make sure setuptools, virtualenv and wheel are installed and up to date::
+Make sure setuptools, virtualenv, and wheel are installed and up-to-date::
 
     sudo $PIP install --upgrade setuptools virtualenv wheel
 
@@ -50,8 +50,8 @@ Get Tobiko source code using Git and enter into Tobiko source folder::
     git clone https://opendev.org/x/tobiko.git
     cd tobiko
 
-To install Tobiko and its dependencies is safer to create a clean Virtualenv
-where to install it. Create a Virtualenv and activate it::
+To install Tobiko and its dependencies it's safest to create a clean virtualenv
+to install it. Create a virtualenv and activate it::
 
     virtualenv .tobiko-env
     source .tobiko-env/bin/activate

doc/source/user/quick-start.rst

@@ -208,6 +208,15 @@ Setup Required Resources
 A public Neutron network is required to be able to execute Tobiko scenario test
 cases by creating a floating IP port on it.
 
+To execute commands from a virtualenv created by Tox you can type as below::
+
+    tox -e venv -- <your-commands>
+
+You need to make sure :ref:`authentication-environment-variables` are properly
+set so you can list available public networks::
+
+    tox -e venv -- openstack network list
+
 If there isn't any valid public network, you need to create one before running
 Tobiko OpenStack test cases. Please refer to the `Neutron documentation <https://docs.openstack.org/neutron/latest/>`__
 for additional information.
@@ -220,15 +229,6 @@ please add a reference to the network in
     [neutron]
     floating_network = public
 
-To execute commands from a virtualenv created by Tox you can type as below::
-
-    tox -e venv -- <your-commands>
-
-You need to make sure ref:`authentication-environment-variables` are properly
-set so you can list available public netoworks::
-
-    tox -e venv -- openstack network list
-
 Running Test Cases
 ------------------
 

doc/source/user/run-test-cases.rst

@@ -11,7 +11,7 @@ This document describes how to execute Tobiko scenario test cases.
     For a quick and simpler start you can jump to the
     :ref:`tobiko-quick-start-guide`.
 
-    To install Tobiko inside a virutalenv please read
+    To install Tobiko inside a virtualenv please read
     :ref:`tobiko-installation-guide`.
 
     To configure Tobiko please read :ref:`tobiko-configuration-guide`.
@@ -20,9 +20,9 @@ This document describes how to execute Tobiko scenario test cases.
 Prepare Your System
 ~~~~~~~~~~~~~~~~~~~
 
-Before running Tobiko test cases you need to be sure you are doing it from
-Tobiko source files folder and that you have actived a Virtualenv where Tobiko
-and its requirements are installed. Please refers to
+Before running Tobiko test cases, you need to be sure you are doing it from
+Tobiko source files folder and that you have activated a virtualenv where Tobiko
+and its requirements are installed. Please refer to
 :ref:`tobiko-installation-guide` and :ref:`tobiko-configuration-guide` to know
 how to setup your system before running test cases.
 
@@ -34,6 +34,6 @@ To run test cases you need a test runner able to execute Python test cases.
 Test cases delivered with Tobiko has been tested using
 `stestr <https://stestr.readthedocs.io/en/latest/>`__
 
-From Tobiko source folder you can run scenario test cases using below command::
+From the Tobiko source folder you can run scenario test cases using the below command::
 
     stestr run --test-path tobiko/tests/scenario/

tobiko.conf.example

@@ -73,12 +73,12 @@
 # Username (string value)
 #username = <None>
 
-# Project name (string value)
-#project_name = <None>
-
 # Password (string value)
 #password = <None>
 
+# Project name (string value)
+#project_name = <None>
+
 # Domain name (string value)
 #domain_name = <None>