[DOC] Improved installation instructions

* Update installation docs to include from source, pip, ppa (package),
  development mode.
* Disable manpage generation (Causes dedent errors and not needed)

Change-Id: I307d63c2a758b1715f4c8ce9b243ad9877479a02

doc/conf.py

@@ -228,7 +228,7 @@ latex_documents = [
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [
+#man_pages = [
-    ('index', 'lbaas', u'LBaaS Client',
+#    ('index', 'lbaas', u'LBaaS Client',
-     [u'Andrew Hutchings'], 1)
+#     [u'Andrew Hutchings'], 1)
-]
+#]

doc/installation.rst

@@ -1,28 +1,87 @@
+.. _installation:
+
 Installation
 ============
 
-From Ubuntu Package
+.. _install-ppa:
--------------------
 
-.. code-block:: bash
+From Ubuntu Package via PPA
+---------------------------
 
-   sudo apt-get install python-pip
+1. Install utility
-   sudo pip install python-novaclient --upgrade
-   sudo dpkg -i python-libraclient_1.2.2-1_all.deb
 
-If the last command fails with an unmet dependency run this to fix it:
+::
 
-.. code-block:: bash
+    sudo apt-get install python-software-properties
 
-   sudo apt-get -fy install
+2. Add the PPA
 
-From Source
+::
------------
 
-The python-setuptools package needs to be installed on your system before
+    sudo apt-add-repository ppa:libra-core/ppa
-installing the client from source.
 
-.. code-block:: bash
+3. Update the package indexes
+
+::
+
+    sudo apt-get update
+
+4. Install packages
+
+::
+
+    sudo apt-get install python-libraclient
+
+
+.. _install-pypi:
+
+From PyPI
+---------
+
+The :program:`python-libraclient` package is published on `PyPI <https://pypi.python.org/pypi/python-libraclient/>`_ and so can be installed using the pip tool, which will manage installing all
+python dependencies.
+
+.. note:: The pip tool isn't bundled by default with some versions of the different distributions, please install it typically using a package manager for the platform you use.
+
+.. note:: Needs to be done in a Virtual Environment or as root.
+
+.. code-block:: shell-session
+
+   pip install python-libraclient
+
+.. warning::
+
+    The packages on PyPI may lag behind the git repo in functionality.
+
+.. _install-source:
+
+Setup the client from source
+----------------------------
+If you want the latest version, straight from github:
+
+.. code-block:: shell-session
+
+    git clone git@github.com:stackforge/python-libraclient.git
+    cd python-libraclient
+    virtualenv .venv
+    source .venv/bin/activate
+    pip install -r requirements.txt -r test-requirements.txt
+    python setup.py install
+
+
+.. _install-development:
+
+Setup the client in development mode
+------------------------------------
+Installing in development mode allows your to make changes to the source code & test directly without having to re-run the "python setup.py install"
+step. You can find out more about this in the `Development Mode <http://pythonhosted.org/distribute/setuptools.html#development-mode>`_ online docs.
+
+.. code-block:: shell-session
+
+    git clone git@github.com:stackforge/python-libraclient.git
+    cd python-libraclient
+    virtualenv .venv
+    source .venv/bin/activate
+    pip install -r requirements.txt -r test-requirements.txt
+    python setup.py develop
 
-   sudo apt-get install python-setuptools
-   sudo python setup.py install