Final doc check

As all of documenation parts were merged, this patch makes
sure, that all of them uses the same style for marking
commands, arguments, notes, ...
Also a few typos were fixed.

Change-Id: I0239e5241aa854f515fc2d72e7947dc51b3ecb56
Story: 2002703
Task: 22965

doc/source/admin/admin_usage.rst

@@ -42,7 +42,7 @@ resources (`Flavors`_ and `Users`_) if they don't exist already:
 
 ``python-tempestconf`` can also create a minimal accounts file when
 ``--create-accounts-file`` is used. It can be useful when a user doesn't have
-any and wants to create it. It can be done with one call:
+any ``accounts.yaml`` and wants to create it. It can be done with one call:
 
 .. code-block:: shell-session
 
@@ -69,7 +69,7 @@ used, `see here`_. The generated accounts file will look similarly to this one:
       username: admin
 
 .. note::
-    More about accounts file can be in our documentation about
+    More about accounts file can be found in our documentation about
     `Usage with tempest accounts file`_
 
     .. _Usage with tempest accounts file: ../user/usage.html#usage-with-tempest-accounts-file

doc/source/contributor/contributing.rst

@@ -2,8 +2,8 @@
 How to Contribute
 =================
 
-python-tempestconf source code is publicly available. You can contribute code
+``python-tempestconf`` source code is publicly available. You can contribute
-to individual projects, documentation, report bugs and vulnerabilities and
+code to individual projects, documentation, report bugs and vulnerabilities and
 request features.
 
 
@@ -11,14 +11,16 @@ Reporting Bugs
 --------------
 
 We have a `storyboard project <https://storyboard.openstack.org/#!/project/912>`_
-created to track any change required for python-tempest. If you have found any
+created to track any change required for ``python-tempestconf``. If you have
-bug, please, report it `there <https://storyboard.openstack.org/#!/project/912>`_.
+found any bug, please, report it
+`there <https://storyboard.openstack.org/#!/project/912>`_.
 
 **Important** information **to mention**:
 
-  * **System** on which the problem occured (e.g. CentosOS, Ubuntu, ...)
+  * **System** on which the problem occurred (e.g. CentOS, Ubuntu, ...)
-  * The source of python-tempestconf you have used. The **package version number**
+  * The source of ``python-tempestconf`` you have used. The **package version
-    in case of RPM or the **branch used** in case of installation from git.
+    number** in case of RPM or the **branch used** in case of installation from
+    git.
   * The **exact command** with all arguments you have used.
   * It's always better to include the **console output** as well.
 
@@ -40,8 +42,8 @@ Fixing bugs
 -----------
 
 1. If you have found a bug and you know how to fix it, please, check our
-   `storyboard project <https://storyboard.openstack.org/#!/project/912>`_ for any
+   `storyboard project <https://storyboard.openstack.org/#!/project/912>`_ for
-   stories which may relate to the issue. If you haven't find any related
+   any stories which may relate to the issue. If you haven't find any related
    story, please, create one. Check `Reporting Bugs`_.
 
 2. Follow `Contributing Code`_ and submit a code review in
@@ -50,15 +52,15 @@ Fixing bugs
 
 Contributing Code
 -----------------
-Like any other project part of OpenStack, the development of python-tempestconf
+Like any other project part of OpenStack, the development of
-follows the OpenStack guidelines for contribution.
+``python-tempestconf`` follows the OpenStack guidelines for contribution.
 
 Learn `how to contribute into OpenStack <https://wiki.openstack.org/wiki/How_To_Contribute>`_.
 
 If you have made any changes in the source code, **run tests locally before
 posting a review**. You can do so by running tox.
 
-If you've made any changes in the documentation (under `doc/`) run::
+If you've made any changes in the documentation (under ``doc/``) run::
 
     $ tox -edocs
 

doc/source/install/installation.rst

@@ -10,7 +10,7 @@ Git
     $ git clone https://git.openstack.org/openstack/python-tempestconf
     $ cd python-tempestconf
 
-2. Create a virtual environment using `virtualenv`::
+2. Create a virtual environment using :command:`virtualenv`::
 
     $ virtualenv .venv
     $ source .venv/bin/activate
@@ -20,7 +20,7 @@ Git
     (.venv) $ pip install .
 
 4. *(optional)* Instead of manual installation described in steps 2 and 3
-   3 above, tox can be used for installing the requirements as well.
+   above, tox can be used for installing the requirements as well.
    To create python 2.7 environment run following::
 
     $ tox -epy27
@@ -35,11 +35,11 @@ Git
 RPM Installation (RDO)
 ----------------------
 
-* python-tempestconf package can be installed as follows::
+* ``python-tempestconf`` package can be installed as follows::
 
     $ sudo yum install python-tempestconf
 
-* python-tempestconf is installed together with `openstack-tempest`, as
+* ``python-tempestconf`` is installed together with ``openstack-tempest``, as
   a new dependency (starting **from** the **Ocata** release)::
 
     $ sudo yum install openstack-tempest
@@ -48,6 +48,6 @@ RPM Installation (RDO)
 Pip installation
 ----------------
 
-Install `python-tempestconf` via pip as follows::
+Install ``python-tempestconf`` via pip as follows::
 
    $ pip install python-tempestconf

doc/source/user/default.rst

@@ -2,9 +2,9 @@
 Default values
 ==============
 
-``python-tempestconf`` defines some options by default in order to simplify
+``python-tempestconf`` provides sensitive default values for many options in
-general executions, because not so many options need to be defined in each
+order to simplify its usage, reducing the amount of options that needs to be
-run of ``python-tempestconf``, for example in CI.
+specified.
 
 Here is the list of tempest options, which are set by default:
 

doc/source/user/import.rst

@@ -2,31 +2,30 @@
 Use python-tempestconf as Python module
 =======================================
 
-`python-tempestconf` can be imported and used from a different Python project.
+``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
+    The import of config_tempest is possible **only when the version of the
-    from **master branch** or via pip, however, **python-tempestconf-2.0.0.
+    tool is at least 2.0.0**.
-    or newer has to be installed**.
 
 Installation
 ++++++++++++
 
-See our `Install Guide`_ on how to install `python-tempestconf`.
+See our `Install Guide`_ on how to install ``python-tempestconf``.
 
 .. _Install Guide: ../install/installation.html
 
 Import
 ++++++
 
-Import python-tempestconf in your project as follows:
+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
+``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>`_
@@ -55,9 +54,10 @@ the configuration tool:
 
 .. note::
 
-    If `args_namespace` contains **--os-cloud** argument, the `get_cloud_creds`
+    If `args_namespace` contains ``--os-cloud`` argument, the `get_cloud_creds`
-    method returns cloud credentials related to that cloud, otherwise, returns
+    method returns cloud credentials related to that cloud, otherwise, it
-    credentials of the current cloud (according to the sourced credentials).
+    returns credentials of the current cloud (according to the sourced
+    credentials).
 
 
 List of arguments which may be passed to `config_tempest`
@@ -89,7 +89,7 @@ List of arguments which may be passed to `config_tempest`
 Example implementation
 ++++++++++++++++++++++
 
-1. Save following code snippet as `example.py`:
+1. Save following code snippet as ``example.py``:
 
     .. code-block:: Python
 
@@ -99,7 +99,7 @@ Example implementation
         parser = argparse.ArgumentParser(description='Example implementation.')
         args = parser.parse_args()
 
-        # gets credentials of the current cloud according to
+        # get the credentials of the current cloud according to
         # the sourced credentials
         cloud_creds = tempestconf.get_cloud_creds(args)
 
@@ -130,7 +130,7 @@ Example implementation
         $ source overcloud_rc
 
 
-3. Run the `example.py`:
+3. Run ``example.py``:
 
     .. code-block:: Bash
 
@@ -140,8 +140,8 @@ Example implementation
 Example implementation with a named cloud
 +++++++++++++++++++++++++++++++++++++++++
 
-1. Let's say there is a `clouds.yaml` file located in `/etc/openstack/` with
+1. Let's say there is a ``clouds.yaml`` file located in ``/etc/openstack/``
-   the following content:
+   with the following content:
 
     .. code-block:: Bash
 
@@ -160,7 +160,7 @@ Example implementation with a named cloud
             volume_api_version: '2'
 
 
-2. Save following code snippet as an `example.py`:
+2. Save following code snippet as ``example.py``:
 
     .. code-block:: Python
 
@@ -173,14 +173,14 @@ Example implementation with a named cloud
         parser.add_argument('--os-cloud', help='Name of a named cloud.')
         args = parser.parse_args()
 
-        # gets credentials to the devstack cloud
+        # get the 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`:
+3. Run ``example.py``:
 
     .. code-block:: Bash
 
@@ -189,5 +189,5 @@ Example implementation with a named cloud
     .. note::
 
         In this example you **don't need** to source cloud credentials. The
-        credentials are obtained from the `/etc/openstack/clouds.yaml`
+        credentials are obtained from the ``/etc/openstack/clouds.yaml`` file
-        thanks to `--os-cloud` argument.
+        thanks to ``--os-cloud`` argument.

doc/source/user/usage.rst

@@ -25,7 +25,7 @@ Examples of usage with sourced credentials
 step **as a prerequisite**:
 
   * Source your OpenStack RC file containing the cloud credentials. Let's say
-    you have a overcloud_rc file with the following content:
+    you have an overcloud_rc file with the following content:
 
     .. code-block:: shell-session
 
@@ -204,9 +204,9 @@ The generated tempest.conf will look like:
 non-admin argument
 ++++++++++++++++++
 
-If your credentials are **non-admin ones**, which means, you are
+If your credentials are **non-admin ones**, which means that you are
-**not allowed** to create any resources in your cloud, please, specify
+**not allowed** to create any resources in your cloud, then please specify
-``--non-admin`` argument. When the argument is used, ``python-tempestconf``
+``--non-admin`` argument. When this argument is used, ``python-tempestconf``
 will **not create** any resources.
 
 .. code-block:: shell-session
@@ -248,7 +248,8 @@ the following content:
         volume_api_version: '2'
 
 Then if you use ``--os-cloud`` argument you can run
-:command:`discover-tempest-config` **without** sourcing any OpenStack RC file.
+:command:`discover-tempest-config` **without** setting any OS_* environment
+variable (for example by sourcing any OpenStack RC file).
 
 ``--os-cloud`` defines specifies one of the cloud names located in the
 ``clouds.yaml`` file.
@@ -352,7 +353,7 @@ image. Then the image is uploaded to glance again and but
         --image /my/path/to/myImage.img
 
 In the following example, an `override`_  value is used to set
-**conpute.image_ref**, which means, that the image specified by  ``--image`` is
+**compute.image_ref**, which means that the image specified by  ``--image`` is
 uploaded and only **compute.image_alt_ref** is set to the ID of newly created
 image.