Update README.rst

README.rst

@@ -21,49 +21,75 @@ https://hub.docker.com/repository/docker/coinor/cylp
 
 Otherwise, read on. 
 
-Prerequisites
-=============
+Prerequisites and installation
+==============================
 
-CyLP depends on Numpy (www.numpy.org) and Scipy (www.scipy.org). Please note that 
-Numpy does need to be installed prior to installing CyLP,
-even though it is listed as a dependency in the `setup.py` file.
+On Windows: Installation as a binary wheel
+---------------------------------------
 
+On Windows, a binary wheel is available and it is not necessary to install Cbc.
+Just do::
+
+    $ python -m pip install cylp
+
+On Linux/macOS with conda: Installation from source
+---------------------------------------------------
+
+CyLP depends on `NumPy <https://numpy.org>`_ and `Cython <https://cython.org/`_
+as prerequisites for building from source (`build-system requires`).
 You will also need to install binaries for Cbc. The version should be 2.10 (recommended) or earlier 
 (current master branch of Cbc will not work with this version of CyLP).
-You can install Cbc by either by 
-installing with a package manager, by downloading pre-built binaries,
+
+The following commands will create and activate a new conda environment with all
+these prerequisites installed::
+
+    $ conda create -n cbc coin-or-cbc cython numpy pkg-config scipy -c conda-forge
+    $ conda activate cbc
+
+Now you can install CyLP from PyPI::
+
+    $ pip install --no-build-isolation cylp
+
+(The option `--no-build-isolation` ensures that `cylp` uses the Python packages
+installed by conda in the build phase.)
+
+Alternatively, if you have cloned CyLP from GitHub::
+
+    $ pip install --no-build-isolation .
+
+On Linux/macOS with pip: Installation from source
+-------------------------------------------------
+
+First of all, you will need to install binaries for Cbc. The version should be 2.10 (recommended) or earlier 
+(current master branch of Cbc will not work with this version of CyLP).
+You can install Cbc by either by installing with your system's package manager, by downloading pre-built binaries,
 or by building yourself from source using `coinbrew <https://github.com/coin-or/coinbrew>`_.
 
 1. To install Cbc in Linux, the easiest way is to use a package manager. Install `coinor-libcbc-dev` on Ubuntu/Debian 
-   or `coin-or-Cbc-devel` on Fedora. Cbc is also available on Linux through conda with  
-
-   ``$ conda create -n cbc coin-or-cbc numpy pkg-config -c conda-forge``    
+   or `coin-or-Cbc-devel` on Fedora.
 
-#. On OS X, it is easiest to install Cbc with homebrew:
+#. On macOS, it is easiest to install Cbc with homebrew:
 
    ``$ brew install cbc pkg-config``
 
-   Cbc is also available on OS X through conda with  
-
-   ``$ conda create -n cbc coin-or-cbc numpy pkg-config -c conda-forge``  
-
-#. On Windows, a binary wheel is available and it is not necessary to install Cbc.
-
 You should no longer need to build Cbc from source on any platform unless for some reason, none of the
 above recipes applies to you. If you do need to build from source, please go to the `Cbc <https://github.com/coin-or/Cbc>`_
 project page and follow the instructions there. After building and installing, make sure to 
 either set the `COIN_INSTALL_DIR` variable to point to the installation or set `PKG_CONFIG_PATH` to point to
 the directory where the `.pc` files are installed. You may also need to set either `LD_LIBRARY_PATH` (Linux)
-or `DYLD_LIBRARY_PATH` (OS X).
+or `DYLD_LIBRARY_PATH` (macOS).
 
-Installation
-============
-
-If you are building against the `coin-or-cbc` package installed by conda, be sure to conda install `pkg-config`,
-which is needed to find the Cbc libraries installed by conda. Once Numpy and Cbc are installed, simply do::
+Next, build and install CyLP::
 
     $ python -m pip install cylp
 
+This will build CyLP in an isolated environment that provides the build prerequisites
+and install it together with its runtime dependencies (`install-requires`),
+NumPy and `SciPy <https://scipy.org>`.
+
+Testing your installation
+=========================
+
 Optional step:
     If you want to run the doctests (i.e. ``make doctest`` in the ``doc`` directory)
     you should also define::
@@ -138,17 +164,24 @@ You may access CyLP's documentation:
 1. *Online* : Please visit http://coin-or.github.io/CyLP/
 
 2. *Offline* : To install CyLP's documentation in your repository, you need
-   Sphinx (http://sphinx-doc.org/). You can generate the documentation by
+   Sphinx (https://www.sphinx-doc.org/). You can generate the documentation by
    going to cylp/doc and run ``make html`` or ``make latex`` and access the
    documentation under cylp/doc/build. You can also run ``make doctest`` to
    perform all the doctest.
 
 Who uses CyLP
 ==============
-CyLP is being used in a wide range of practical and research fields. Some of the users include:
 
-#. PyArt, The Python ARM Radar Toolkit, used by Atmospheric Radiation Measurement
-   (U.S. Department of energy). https://github.com/ARM-DOE/pyart
+The following software packages make use of CyLP:
+#. `CVXPY <https://www.cvxpy.org/>`_, a Python-embedded modeling language for
+   convex optimization problems, uses CyLP for interfacing to CBC, which is one
+   of the `supported mixed-integer solvers
+   <https://www.cvxpy.org/tutorial/advanced/index.html#mixed-integer-programs>`_.
+
+CyLP has been used in a wide range of practical and research fields. Some of the users include:
+
+#. `PyArt <https://github.com/ARM-DOE/pyart>`_, The Python ARM Radar Toolkit,
+   used by Atmospheric Radiation Measurement (U.S. Department of energy).
 #. Meteorological Institute University of Bonn.
 #. Sherbrooke university hospital (Centre hospitalier universitaire de Sherbrooke): CyLP is used for nurse scheduling.
 #. Maisonneuve-Rosemont hospital (L'hôpital HMR): CyLP is used for  physician scheduling with preferences.