Fix documentation structure

Usage section is there twice, it's because the README.rst
is included in doc too and it contains usage section as well.
The patch fixes that by not including the README.rst and
copies the content of README.rst to the documentation,
in order to have at least some, while documentation is being
written or reviewed.

Change-Id: I0247289029cd63b354965242ce7c1eca65f945eb
Story: 2002703
Task: 22543

doc/source/contributor/index.rst

@@ -0,0 +1,8 @@
+Contributor Guide
+=================
+
+.. toctree::
+  :maxdepth: 2
+  :includehidden:
+
+  contributing

doc/source/index.rst

@@ -6,20 +6,22 @@
 Welcome to python-tempestconf's documentation!
 ========================================================
 
+python-tempestconf is a tool for automatic generation of tempest configuration
+based on user's cloud.
+
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-   readme
-   installation
-   usage
-   contributing
+   overview
+   install/index
+   user/index
+   contributor/index
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 

doc/source/install/index.rst

@@ -0,0 +1,8 @@
+Install Guide
+=============
+
+.. toctree::
+  :maxdepth: 2
+  :includehidden:
+
+  installation

doc/source/overview.rst

@@ -0,0 +1,14 @@
+========
+Overview
+========
+
+python-tempestconf will automatically generate the tempest configuration
+based on your cloud.
+
+-  Free software: Apache license
+-  Documentation:
+   http://git.openstack.org/cgit/openstack/python-tempestconf/tree/README.rst
+-  Source: https://git.openstack.org/openstack/python-tempestconf
+-  Bugs: https://storyboard.openstack.org/#!/project/912
+-  Release notes: https://docs.openstack.org/releasenotes/python-tempestconf
+

doc/source/readme.rst

@@ -1 +0,0 @@
-.. include:: ../../README.rst

doc/source/usage.rst

@@ -1,7 +0,0 @@
-========
-Usage
-========
-
-To use python-tempestconf in a project::
-
-    import tempest_config

doc/source/user/index.rst

@@ -0,0 +1,8 @@
+Usage
+=====
+
+.. toctree::
+  :maxdepth: 2
+  :includehidden:
+
+  usage

doc/source/user/usage.rst

@@ -0,0 +1,99 @@
+========
+Usage
+========
+
+To use python-tempestconf in a project::
+
+    import tempest_config
+
+Git
+---
+
+1. Clone and change to the directory:
+
+.. code-block:: shell-session
+
+    $ git clone https://git.openstack.org/openstack/python-tempestconf
+    $ cd python-tempestconf
+
+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:
+
+.. code-block:: shell-session
+
+    (.venv) $ pip install -r requirements.txt
+    (.venv) $ pip install -r test-requirements.txt
+
+4. Source cloud credentials, for example:
+
+.. code-block:: shell-session
+
+    (py27) $ source cloudrc
+
+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.
+
+RPM Installation (RDO)
+----------------------
+
+1. python-tempestconf is installed together with openstack-tempest, as
+   a new dependency (starting from the Ocata release)
+
+.. code-block:: shell-session
+
+    # yum install openstack-tempest
+
+2. Source cloud credentials, initialize tempest and run the discovery
+   tool:
+
+.. code-block:: shell-session
+
+    $ source cloudrc
+    $ tempest init testingdir
+    $ cd testingdir
+    $ 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://blogs.rdoproject.org/2017/02/testing-rdo-with-tempest-new-features-in-ocata/>`__
+
+
+os-client-config support
+------------------------
+
+python-tempestconf supports `os-client-config <https://git.openstack.org/openstack/os-client-config>`__
+so instead of sourcing openstackrc files you can use clouds.yml files. Location where
+these files should be stored and syntax which is used to specify cloud.yaml files
+can be found `here <https://docs.openstack.org/os-client-config/latest/user/configuration.html#config-files>`__
+
+In case of git usage:
+
+.. code-block:: shell-session
+
+    (py27) $ python config_tempest/config_tempest.py --debug --create --os-cloud <name of cloud>
+
+In case of RPM:
+
+.. code-block:: shell-session
+
+    $ tempest init testingdir
+    $ cd testingdir
+    $ discover-tempest-config --debug --create --os-cloud <name of cloud>
+