diff --git a/README.rst b/README.rst
index f2d287a6..4a5f485e 100644
--- a/README.rst
+++ b/README.rst
@@ -1,54 +1,75 @@
-===============================
 python-tempestconf
-===============================
+==================
 
-## Overview
+Overview
+--------
 
-python-tempestconf will automatically generate the tempest configuration based on your cloud.
+python-tempestconf will automatically generate the tempest configuration
+based on your cloud.
 
-* Free software: Apache license
-* Documentation: https://github.com/redhat-openstack/python-tempestconf/blob/master/README.rst
-* Source: https://github.com/redhat-openstack/python-tempestconf
-* Bugs: https://github.com/redhat-openstack/python-tempestconf/issues
+-  Free software: Apache license
+-  Documentation:
+   https://github.com/redhat-openstack/python-tempestconf/blob/master/README.rst
+-  Source: https://github.com/redhat-openstack/python-tempestconf
+-  Bugs: https://github.com/redhat-openstack/python-tempestconf/issues
 
-## Usage
+Usage
+-----
 
-### Git
-[1.] Clone and change to the directory:
+Git
+~~~
+
+1. Clone and change to the directory:
+
+.. code-block:: shell-session
 
     $ git clone https://github.com/redhat-openstack/python-tempestconf
     $ cd python-tempestconf
 
-[2.] Create virtual environment using virtualenv:
+2. Create virtual environment using virtualenv:
+
+.. code-block:: shell-session
 
     $ virtualenv .venv
     $ source .venv/bin/activate
 
-[3.] Source the newly created virtual environment and install requirements:
+3. Source the newly created virtual environment and install
+   requirements:
+
+.. code-block:: shell-session
 
     (.venv) $ pip install -r requirements.txt
     (.venv) $ pip install -r test-requirements.txt
 
-[4.] Source cloud credentials, for example:
+4. Source cloud credentials, for example:
+
+.. code-block:: shell-session
 
     (py27) $ source cloudrc
 
-[5.] Run python-tempestconf to generate tempest configuration file:
+5. Run python-tempestconf to generate tempest configuration file:
+
+.. code-block:: shell-session
 
     (py27) $ python config_tempest/config_tempest.py --debug identity.uri $OS_AUTH_URL \
                 identity.admin_password  $OS_PASSWORD --create
 
-After this, `./etc/tempest.conf` is generated.
+After this, ``./etc/tempest.conf`` is generated.
 
+RPM Installation (RDO)
+~~~~~~~~~~~~~~~~~~~~~~
 
-### RPM Installation (RDO)
+1. python-tempestconf is installed together with openstack-tempest, as
+   a new dependency (starting from the Ocata release)
 
-[1.] python-tempestconf is installed together with openstack-tempest,
-     as a new dependency (starting from the Ocata release)
+.. code-block:: shell-session
 
     # yum -y install openstack-tempest
 
-[2.] Source cloud credentials, initialize tempest and run the discovery tool:
+2. Source cloud credentials, initialize tempest and run the discovery
+   tool:
+
+.. code-block:: shell-session
 
     $ source cloudrc
     $ tempest init testingdir
@@ -56,9 +77,9 @@ After this, `./etc/tempest.conf` is generated.
     $ discover-tempest-config --debug identity.uri $OS_AUTH_URL \
           identity.admin_password  $OS_PASSWORD --create
 
-*Note:* In Ocata release new features were presented. `discover-tempest-config` is the new name
- of the **old** `config_tempest.py` script and it **accepts the same parameters.** More about new
- features can be found
- [here](https://www.rdoproject.org/blog/2017/02/testing-rdo-with-tempest-new-features-in-ocata/)
-
-
+.. note::
+   In Ocata release new features were presented.
+   ``discover-tempest-config`` is the new name of the **old**
+   ``config_tempest.py`` script and it **accepts the same parameters.**
+   More about new features can be found
+   `here <https://www.rdoproject.org/blog/2017/02/testing-rdo-with-tempest-new-features-in-ocata/>`__