Reorganize the documentation following the new structure

- move api as "reference" guide and reword as Python client;
- consolidate shell and cli as part of the "CLI" guide;
- remove the "how_to_participate" page and use part of
  the content from the old index for a minimal "contributor"
  guide which redirect to the sahara contributor guide
  (no need to duplicate the information);
- remove few references to doc/source/api from tox.ini and
  .gitignore (for some reason the directory was cleaned).

Also, adapt the version-specific links to Pike.

Change-Id: Iff049ab32a7695a7a58bd370a1517b1ed7d2f048
(cherry picked from commit 889cbb56133afe348093c2d289186561a07c83c6)

10 files changed, 47 insertions, 100 deletions

diff --git a/.gitignore b/.gitignore
index 393b55d..d178cdc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,7 +33,6 @@ AUTHORS
 cover
 doc/html
 doc/source/apidoc
-doc/source/api
 doc/build
 *.log
 # Files created by releasenotes build
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
new file mode 100644
index 0000000..100c8a6
--- /dev/null
+++ b/doc/source/cli/index.rst
@@ -0,0 +1,9 @@
+=================
+Sahara CLI client
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   reference
diff --git a/doc/source/shell.rst b/doc/source/cli/intro.rst
index 6c6249e..f2c1cf1 100644
--- a/doc/source/shell.rst
+++ b/doc/source/cli/intro.rst
@@ -1,5 +1,5 @@
-Sahara CLI
-==========
+Introduction
+============
 
 The Sahara shell utility now is part of the OpenStackClient, so all
 shell commands take the following form:
@@ -21,7 +21,7 @@ To get detailed help for the command you can run:
     $ openstack help dataprocessing <command>
 
 For more information about commands and their parameters you can refer to
-:doc:`the Sahara CLI commands <cli>`.
+:doc:`the Sahara CLI commands <reference>`.
 
 For more information about abilities and features of OpenStackClient CLI you
 can refer to `OpenStackClient documentation <http://docs.openstack.org/developer/python-openstackclient/>`_
diff --git a/doc/source/cli.rst b/doc/source/cli/reference.rst
index 62637f0..203cf22 100644
--- a/doc/source/cli.rst
+++ b/doc/source/cli/reference.rst
@@ -1,5 +1,5 @@
-Sahara CLI Commands
-===================
+CLI Reference
+=============
 
 The following commands are currently supported by the Sahara CLI:
 
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
new file mode 100644
index 0000000..a2d2efd
--- /dev/null
+++ b/doc/source/contributor/index.rst
@@ -0,0 +1,16 @@
+Contributing
+============
+
+``python-saharaclient`` is part of the Sahara project.
+It has a separate `launchpad`_ page which should be used to report bugs.
+Like the other projects of the OpenStack community, code contribution happens
+through `gerrit`_.
+
+Please refer to the `Sahara documentation`_ and its
+`How to Participate section`_ for more information on
+how to contribute to the project.
+
+.. _Sahara documentation: https://docs.openstack.org/sahara/pike/
+.. _How to Participate section: https://docs.openstack.org/sahara/pike/contributor/how-to-participate.html
+.. _launchpad: https://launchpad.net/python-saharaclient
+.. _gerrit: https://docs.openstack.org/infra/manual/developers.html#development-workflow
diff --git a/doc/source/how_to_participate.rst b/doc/source/how_to_participate.rst
deleted file mode 100644
index 14c1ee0..0000000
--- a/doc/source/how_to_participate.rst
+++ /dev/null
@@ -1,68 +0,0 @@
-How to Participate
-==================
-
-Getting started
----------------
-
-* Create account on `Github <https://github.com/openstack/sahara>`_
-  (if you don't have one)
-
-  * Make sure that your local git is properly configured by executing
-    ``git config --list``. If not, configure ``user.name``, ``user.email``
-
-* Create account on `Launchpad <https://launchpad.net/sahara>`_
-  (if you don't have one)
-
-* Subscribe to `OpenStack general mail-list <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack>`_
-
-* Subscribe to `OpenStack development mail-list <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>`_
-
-* Create `OpenStack profile <https://www.openstack.org/profile/>`_
-
-* Login to `OpenStack Gerrit <https://review.openstack.org/>`_ with your
-  Launchpad id
-
-  * Sign `OpenStack Individual Contributor License Agreement <https://review.openstack.org/#/settings/agreements>`_
-  * Make sure that your email is listed in `identities <https://review.openstack.org/#/settings/web-identities>`_
-
-* Subscribe to code-reviews. Go to your settings on http://review.openstack.org
-
-  * Go to ``watched projects``
-  * Add ``openstack/sahara``, ``openstack/sahara-dashboard``,
-    ``openstack/sahara-extra``, ``openstack/python-saharaclient``,
-    ``openstack/sahara-image-elements``, ``openstack/horizon``
-
-
-How to stay in touch with the community?
-----------------------------------------
-
-* If you have something to discuss use
-  `OpenStack development mail-list <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev>`_.
-  Prefix mail subject with ``[Sahara]``
-
-* Join ``#openstack-sahara`` IRC channel on `freenode <http://freenode.net/>`_
-
-* Join public weekly meetings on *Thursdays at 18:00 UTC* on
-  ``#openstack-meeting-alt`` IRC channel
-* Join public weekly meetings on *Thursdays at 14:00 UTC* on
-  ``#openstack-meeting-3`` IRC channel
-
-
-How to send your first patch on review?
----------------------------------------
-
-* Checkout Sahara code from `Github <https://github.com/openstack/sahara>`_
-
-* Carefully read https://wiki.openstack.org/wiki/Gerrit_Workflow
-
-  * Pay special attention to https://wiki.openstack.org/wiki/Gerrit_Workflow#Committing_Changes
-
-* Apply and commit your changes
-
-* Make sure that your code passes ``PEP8`` checks and unit-tests
-
-* Send your patch on review
-
-* Monitor status of your patch review on https://review.openstack.org/#/
-
-
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 50a3d08..3ac7aa0 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,9 +1,9 @@
 Python bindings to the OpenStack Sahara API
 ===========================================
 
-This is a client for OpenStack Sahara API. There's :doc:`a Python API
-<api>` (the :mod:`saharaclient` module), and a :doc:`command-line utility
-<shell>` (installed as an OpenStackClient plugin). Each implements the entire
+This is a client for OpenStack Sahara API. There's :doc:`a Python API client
+<reference/index>` (the :mod:`saharaclient` module), and a :doc:`command-line utility
+<cli/index>` (installed as an OpenStackClient plugin). Each implements the entire
 OpenStack Sahara API.
 
 You'll need credentials for an OpenStack cloud that implements the
@@ -13,30 +13,14 @@ You may want to read the `OpenStack Sahara Docs`__  -- the overview, at
 least -- to get an idea of the concepts. By understanding the concepts
 this library should make more sense.
 
- __ http://docs.openstack.org/developer/sahara/
+ __ https://docs.openstack.org/sahara/pike/
 
 Contents:
 
 .. toctree::
    :maxdepth: 2
 
-   api
-   shell
-   cli
-   how_to_participate
-
-Contributing
-============
-
-Code is hosted in `review.o.o`_ and mirrored to `github`_ and `git.o.o`_ .
-Submit bugs to the Sahara project on `launchpad`_ and to the Sahara client on
-`launchpad_client`_. Submit code to the openstack/python-saharaclient project
-using `gerrit`_.
-
-.. _review.o.o: https://review.openstack.org
-.. _github: https://github.com/openstack/python-saharaclient
-.. _git.o.o: http://git.openstack.org/cgit/openstack/python-saharaclient
-.. _launchpad: https://launchpad.net/sahara
-.. _launchpad_client: https://launchpad.net/python-saharaclient
-.. _gerrit: http://docs.openstack.org/infra/manual/developers.html#development-workflow
+   reference/index
+   cli/index
+   contributor/index
 
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
new file mode 100644
index 0000000..be67a9e
--- /dev/null
+++ b/doc/source/reference/index.rst
@@ -0,0 +1,8 @@
+===============
+Reference guide
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   pythonclient
diff --git a/doc/source/api.rst b/doc/source/reference/pythonclient.rst
index f49e663..ef9f741 100644
--- a/doc/source/api.rst
+++ b/doc/source/reference/pythonclient.rst
@@ -1,5 +1,5 @@
-Sahara Client
-=============
+Python Sahara client
+====================
 
 Overview
 --------
diff --git a/tox.ini b/tox.ini
index e88128c..a2594fe 100644
--- a/tox.ini
+++ b/tox.ini
@@ -55,7 +55,6 @@ commands = {posargs}
 [testenv:docs]
 commands =
     rm -rf doc/html doc/build
-    rm -rf doc/source/apidoc doc/source/api
     python setup.py build_sphinx
 whitelist_externals =
     rm