update INSTALL instructions

Signed-off-by: Giampaolo Rodola <g.rodola@gmail.com>

1 files changed, 36 insertions, 35 deletions

diff --git a/INSTALL.rst b/INSTALL.rst
index a4f2bf11..9516a183 100644
--- a/INSTALL.rst
+++ b/INSTALL.rst
@@ -1,17 +1,21 @@
+Install psutil
+==============
+
 Linux, Windows, macOS (wheels)
-==============================
+------------------------------
 
 psutil makes extensive use of C extension modules, meaning a C compiler is
-required.
-For these 3 platforms though, pre-compiled cPython wheels are provided on each
-psutil release, so all you have to do is this::
+required to build the sources.
+Pre-compiled cPython wheels are provided on each release though, so on
+**Linux**, **Windows** and **macOS** all you have to do is::
 
     pip3 install psutil
 
-If wheels are not available and you whish to install from sources, keep reading.
+If wheels are not available for your platform or architecture, or you whish to
+install psutil from sources, keep reading.
 
 Linux (install from sources)
-============================
+----------------------------
 
 Ubuntu / Debian::
 
@@ -24,18 +28,18 @@ RedHat / CentOS::
     pip3 install --user psutil --no-binary :all:
 
 Windows (install from sources)
-==============================
+------------------------------
 
-In order to compile psutil on Windows you'll need **Visual Studio**.
-Here's a couple of guides describing how to do it: `1 <https://blog.ionelmc.ro/2014/12/21/compiling-python-extensions-on-windows/>`__
-and `2 <https://cpython-core-tutorial.readthedocs.io/en/latest/build_cpython_windows.html>`__. And then::
+In order to compile psutil on Windows you'll need **Visual Studio** compiler
+(**MinGW** is not supported).
+Here's a couple of guides describing how to do it: `link <https://blog.ionelmc.ro/2014/12/21/compiling-python-extensions-on-windows/>`__
+and `link <https://cpython-core-tutorial.readthedocs.io/en/latest/build_cpython_windows.html>`__.
+Once VS is installed do::
 
     pip3 install --user psutil --no-binary :all:
 
-Note that MinGW compiler is not supported.
-
 FreeBSD
-=======
+-------
 
 ::
 
@@ -43,7 +47,7 @@ FreeBSD
     python3 -m pip3 install psutil
 
 OpenBSD
-=======
+-------
 
 ::
 
@@ -52,7 +56,7 @@ OpenBSD
     python3 -m pip install psutil
 
 NetBSD
-======
+------
 
 ::
 
@@ -61,10 +65,10 @@ NetBSD
     pkgin install python3 gcc
     python3 -m pip install psutil
 
-Solaris
-=======
+Sun Solaris
+-----------
 
-If ``cc`` compiler is not installed create a symlink to ``gcc``::
+If ``cc`` compiler is not installed create a symbolic link to ``gcc``::
 
     sudo ln -s /usr/bin/gcc /usr/local/bin/cc
 
@@ -73,22 +77,14 @@ Install::
     pkg install gcc
     python3 -m pip install psutil
 
-Testing installation
-====================
-
-::
-
-    python3 -m psutil.tests
 
-Dev Guide
-=========
-
-`Link <https://github.com/giampaolo/psutil/blob/master/docs/DEVGUIDE.rst>`__.
+Troubleshooting
+===============
 
 Install pip
-===========
+-----------
 
-Pip is shipped by default with Python 2.7.9+ and 3.4+.
+**Pip** is shipped by default with Python 2.7.9+ and 3.4+.
 If you don't have it you can install with wget::
 
     wget https://bootstrap.pypa.io/get-pip.py -O - | python3
@@ -98,18 +94,23 @@ If you don't have it you can install with wget::
     python3 < <(curl -s https://bootstrap.pypa.io/get-pip.py)
 
 On Windows, `download pip <https://pip.pypa.io/en/latest/installing/>`__, open
-cmd.exe and install it::
+cmd.exe and install it with::
 
     C:\Python27\python.exe get-pip.py
 
-Permission issues (UNIX)
-========================
+Permission errors (UNIX)
+------------------------
 
 If you bump into permission errors you have two options.
-Install psutil for your user only::
+
+* Install psutil for your user only (non system-wide)::
+
+    pip3 install --user psutil
+
+* Install it as root user (system-wide):
 
     pip3 install --user psutil
 
-...or prepend ``sudo`` and install it at system level::
+* Prepend ``sudo`` (system-wide)::
 
     sudo pip3 install psutil