Update install docs (#206)

* General improvements to the installation instructions
* Add an additional installation method (coda+pip) if creating the environment using conda fails.

Author: loforest

CONTRIBUTING.rst

@@ -63,22 +63,34 @@ Conda quickly installs, runs and updates packages and their dependencies.
 It also allows to easily create, save, load and switch between different
 environments on your local computer.
 
-The developer environment can be created using the
+Before continuing, Mac OSX users also need to install a more recent compiler.
+See instructions here: :ref:`OSX users <install_osx_users>`.
+
+The developer environment can be created from the file
 `environment_dev.yml <https://github.com/pySTEPS/pysteps/blob/master/environment_dev.yml>`_
-file in the project's root directory running the command::
+in the project's root directory by running the command::
 
     conda env create -f environment_dev.yml
 
 This will create the **pysteps_dev** environment that can be activated using::
 
     conda activate pysteps_dev
 
-Once the environment is created, the package can be installed in development
-mode, in such a way that the project appears to be installed,
-but yet is still editable from the source tree.
-See instructions in the :ref:`Installing pysteps <development_mode_install>`
-section.
+Once the environment is activated, the latest version of pysteps can be installed
+in development mode, in such a way that the project appears to be installed,
+but yet is still editable from the source tree::
+
+    pip install -e <path to local pysteps repo>
+
+To test if the installation went fine, you can try launching Python and importing
+pysteps :ref:`Import pysteps <_import_pysteps>`.
+
+**Note**: In case of installation or import errors, you can remove the pysteps_dev environment
+and try starting from an empty environment (adapt the Python version as needed)::
+
+    conda create -n pysteps_dev python=3.8
 
+You can then activate it and install pysteps with pip as exaplained above.
 
 Fork the repository
 ~~~~~~~~~~~~~~~~~~~

doc/source/user_guide/install_pysteps.rst

@@ -38,7 +38,9 @@ Other optional dependencies include:
 * `pandas <https://pandas.pydata.org/>`_ and
   `scikit-image <https://scikit-image.org/>`_ (for more advanced feature tracking)
 
-
+**Important**: If you only want to use pysteps, you can continue reading below.
+But, if you want to contribute to pysteps or edit the package, you need to install
+pysteps in development mode: :ref:`Contributing to pysteps <contributor_guidelines>`.
 
 Anaconda install (recommended)
 ------------------------------
@@ -88,9 +90,10 @@ to adhere to the [PEP517 standards](https://www.python.org/dev/peps/pep-0517/).
 Using `pip` instead of `setup.py` guarantees that all the package dependencies
 are properly handled during the installation process.
 
+.. _install_osx_users:
 
-OSX users
-~~~~~~~~~
+OSX users: gcc compiler
+~~~~~~~~~~~~~~~~~~~~~~~
 
 pySTEPS uses Cython extensions that need to be compiled with multi-threading
 support enabled. The default Apple Clang compiler does not support OpenMP.
@@ -131,15 +134,15 @@ the homebrew installation. For example::
 
 Then, you can continue with the normal installation procedure described next.
 
-Installation
-~~~~~~~~~~~~
+Installation using pip
+~~~~~~~~~~~~~~~~~~~~~~
 
 The latest pysteps version in the repository can be installed using pip by
 simply running in a terminal::
 
     pip install git+https://github.com/pySTEPS/pysteps
 
-Or, from a local copy of the repo (global installation)::
+Or, from a local copy of the repo::
 
     git clone https://github.com/pySTEPS/pysteps
     cd pysteps
@@ -148,18 +151,6 @@ Or, from a local copy of the repo (global installation)::
 The above commands install the latest version of the **master** branch,
 which is continuously under development.
 
-.. _development_mode_install:
-
-Development mode
-################
-
-The latest version can also be installed in Development Mode, i.e.,
-in such a way that the project appears to be installed,
-but yet is still editable from the source tree::
-
-    pip install -e <path to local pysteps repo>
-
-
 Setting up the user-defined configuration file
 ----------------------------------------------
 
@@ -177,6 +168,24 @@ that can be accessed as attributes or as items.
     Set-up the user-defined configuration file <set_pystepsrc>
     Example pystepsrc file <pystepsrc_example>
 
+.. _import_pysteps:
+
+Final test: import pysteps in Python
+------------------------------------
+
+Activate the pysteps environment::
+
+    conda activate pysteps
+
+Launch Python and import pysteps::
+
+    python
+    >>> import pysteps
+
+**Important**: The Python interpreter must be launched outside of the pysteps directory.
+Otherwise, it confuses the name of the directory with the package name.
+See :ref:`Issue 40 <https://github.com/pySTEPS/pysteps/issues/40>`.
+