From d98e6dcff9fa47f40998fe3807d4bb5af6dbcac1 Mon Sep 17 00:00:00 2001
From: Gregory Haynes <greg@greghaynes.net>
Date: Sun, 12 Apr 2015 16:07:51 +0000
Subject: [PATCH] Update install docs to be more user friendly

Our install docs are out of date and not very user friendly. Lets fix
that.

Change-Id: Idaff33096bf32865020b85ee776abd6691ac45ad
---
 doc/source/user_guide/installation.rst | 67 +++++++++++++++++++++-----
 1 file changed, 56 insertions(+), 11 deletions(-)

diff --git a/doc/source/user_guide/installation.rst b/doc/source/user_guide/installation.rst
index 363886cb6..ecfdaac4d 100644
--- a/doc/source/user_guide/installation.rst
+++ b/doc/source/user_guide/installation.rst
@@ -1,24 +1,69 @@
 Installation
 ============
 
-Diskimage-builder is run directly out of the source repository.
+Diskimage-builder can either be run directly out of the source repository or
+installed via pip. If you plan on doing development on diskimage-builder or
+the elements then we recommend you run the tool out of the source repository
+as this installation requires minimal extra effort and does not require an
+extra install step for your changes to take effect.
+
+Once installed, you will be able to `build images <building_an_image>` using
+disk-image-create and the elements included in the main diskimage-builder
+repository.
+
 
 Requirements
 ------------
 
-If you have 4GB of available physical RAM (As reported by
-/proc/meminfo MemTotal), or more, diskimage-builder will create a tmpfs mount
-to build the image in. This will improve image build time by building in RAM.
+Most image formats require the qemu-img tool which is provided by the
+qemu-utils package on Ubuntu/Debian or the qemu package on
+Fedora/RHEL/opensuse.
+
+Some image formats, such as VHD, may require additional tools. Please see
+the disk-image-create help output for more information.
+
+Individual elements can also have additional dependencies for the build host.
+It is recommended you check the documentation for each element you are using
+to determine if there are any additional dependencies.
+
+
+Source Installation
+-------------------
+
+Clone the diskimage-builder and dib-utils repositories locally:
+
+::
+
+    git clone https://git.openstack.org/openstack/diskimage-builder
+    git clone https://git.openstack.org/openstack/dib-utils
+
+
+Add the bin dirs to your path:
+
+::
+
+    export PATH=$PATH:$(pwd)/diskimage-builder/bin:$(pwd)/dib-utils/bin
+
+
+Pip Installation
+----------------
+
+Installing via pip is as simple as:
+
+::
+
+    pip install diskimage-builder
+
+
+Speedups
+--------
+
+If you have 4GB of available physical RAM (As reported by /proc/meminfo
+MemTotal), or more, diskimage-builder will create a tmpfs mount to build the
+image in. This will improve image build time by building in RAM.
 This can be disabled completely by passing --no-tmpfs to disk-image-create.
 ramdisk-image-create builds a regular image and then within that does ramdisk
 creation. If tmpfs is not used, you will need enough room in /tmp to store two
 uncompressed cloud images. If you do have tmpfs, you will still need /tmp space
 for one uncompressed cloud image and about 20% of that for working files.
 
-Installation
-------------
-
-* Clone the repository locally, then add bin to your path.
-
-* Make sure you have qemu-img (qemu-utils package on Ubuntu/Debian,
-  qemu on Fedora/RHEL/openSUSE) and kpartx installed.