From 996c1ae69a497fbf41737678f28e8eea3ee1f90e Mon Sep 17 00:00:00 2001
From: Kyle Fuller <kyle@fuller.li>
Date: Mon, 18 Jun 2018 17:15:37 +0100
Subject: [PATCH] docs(installation): Suggest homebrew formula on macOS

---
 docs/source/index.rst | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/docs/source/index.rst b/docs/source/index.rst
index 44725e9..120c9bb 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -10,16 +10,19 @@ This is an internal tool for supporting development workflow inside `Apiary <htt
 Installation
 ------------
 
-``pip install blackbelt`` if you can, ``easy_install blackbelt`` if
-you must (Mac OS X default).
+On macOS, the easiest way to install blackbelt is via `Homebrew  <https://brew.sh/>`_::
 
-MacOs and Python3 need use `Homebrew  <https://brew.sh/>`_
+	$ brew install apiaryio/formulae/blackbelt
 
-``brew install python3 && pip3 install blackbelt``
+On other platforms you can install Blackbelt with ``pip install blackbelt`` providing you have Python and pip installed. Consult your platform for documentation on how to install Python and pip.
 
 .. note::
    Python 3.6+ is default now and Python 2.7 will be deprecated.
 
+-----
+Setup
+-----
+
 With that, you should have ``bb`` command. Run interactive ``bb init`` and follow instructions. This is going to connect to services we are using in Apiary for futher interaction:
 
 * GitHub
@@ -45,7 +48,14 @@ See `click's documentation <http://click.pocoo.org/3/bashcomplete/>`_ for more i
 Upgrade
 -------
 
-``pip install -U blackbelt``
+If you used Homebrew on macOS, use::
+
+	$ brew update
+	$ brew upgrade
+
+Otherwise::
+
+	$ pip install -U blackbelt
 
 If you get error along the lines of::