From 5bd6f7627ae0826e65296565ee04ac5b3c7c2419 Mon Sep 17 00:00:00 2001
From: Chandan Singh <csingh43@bloomberg.net>
Date: Thu, 23 Aug 2018 23:23:45 +0100
Subject: doc: Add instructions to install BuildStream via PyPI

Add instructions to install and update BuildStream python package via
PyPI, and also make it the recommended method.

Part of https://gitlab.com/BuildStream/buildstream/issues/587.
---
 doc/source/install_linux_distro.rst | 41 ++++++++++++++++++++++++++++++++-----
 1 file changed, 36 insertions(+), 5 deletions(-)

diff --git a/doc/source/install_linux_distro.rst b/doc/source/install_linux_distro.rst
index 0d21bfd46..8a0d536e0 100644
--- a/doc/source/install_linux_distro.rst
+++ b/doc/source/install_linux_distro.rst
@@ -152,8 +152,29 @@ for advice on this.
 
 Installing
 ~~~~~~~~~~
-Once you have the base system dependencies, you can clone the BuildStream
-git repository and install it as a regular user::
+Once you have the base system dependencies, you can install the BuildStream
+python package as a regular user.
+
+Via PyPI (recommended)
+++++++++++++++++++++++
+::
+
+  pip3 install --user BuildStream
+
+This will install latest stable version of BuildStream and its pure python
+dependencies into your user's homedir in ``~/.local``.
+
+Keep following the instructions below to ensure that the ``bst``
+command is in your ``PATH`` and to enable bash completions for it.
+
+.. note::
+
+  If you want a specific version of BuildStream, you can install it using
+  ``pip install --user BuildStream==<version-number>``
+
+Via Git checkout
+++++++++++++++++
+::
 
   git clone https://gitlab.com/BuildStream/buildstream.git
   cd buildstream
@@ -206,9 +227,19 @@ to your ``~/.bash_completion``:
 
 Upgrading BuildStream
 ~~~~~~~~~~~~~~~~~~~~~
-Assuming you have followed the default instructions above, all
-you need to do to upgrade BuildStream is to update your local git
-checkout::
+
+Via PyPI
+++++++++
+
+If you installed BuildStream from PyPI, you can update it like so::
+
+  pip install --user --upgrade BuildStream
+
+Via Git checkout
+++++++++++++++++
+
+If you installed BuildStream from a local git checkout using ``-e`` option, all
+you need to do to upgrade BuildStream is to update your local git checkout::
 
   cd /path/to/buildstream
   git pull --rebase
-- 
cgit v1.2.1