Merge 679280c into bf46680

docs/install.rst

@@ -3,15 +3,14 @@
 Installation
 ============
 
-Installing TCRM is intended to be a simple process, requiring only a
-small amount of compilation and basic understanding of command line
-operations. TCRM has been installed and (lightly) tested on a range of
-unix-based systems, Windows and Mac OS/X systems.
+Installing TCRM is intended to be a simple process, requiring only basic
+understanding of command line operations. TCRM has been installed and (lightly)
+tested on a range of unix-based systems, Windows and Mac OS/X systems.
 
 .. _downloading:
 
 Downloading
-----------
+-----------
 
 The TCRM code can be downloaded from the `Geoscience Australia GitHub
 page <https://github.com/GeoscienceAustralia/tcrm>`_.
@@ -28,18 +27,20 @@ TCRM.
 .. _environment:
 
 Setting the environment
-----------------------
+-----------------------
 
 To enable TCRM to run correctly, you may need to change some
 environment settings. The important variable to set is the
 ``PYTHONPATH`` variable. This should be set to the path where you have
 extracted the contents of the zip file. In the examples below, change
 ``/path/to/tcrm`` to the location where you extracted the TCRM files.
+For ``conda`` installation, this may not be necessary.
 
 A complete discussion on environment variables in Python is given in
 the `Python documentation
 <https://docs.python.org/2/using/cmdline.html#environment-variables>`_.
 
+
 Windows
 ~~~~~~~
 
@@ -52,34 +53,31 @@ variables on different Windows systems.
 BASH shell
 ~~~~~~~~~~
 
-::
+.. code-block:: bash
 
     export PYTHONPATH=$PYTHONPATH:/path/to/tcrm:/path/to/tcrm/Utilities
 
 
 CSH/TCSH shell
 ~~~~~~~~~~~~~~
 
-::
+.. code-block:: tcsh
 
     setenv PYTHONPATH $PYTHONPATH:/path/to/tcrm:/path/to/tcrm/Utilities
 
 
-
-
-
 .. _dependencies:
 
 Dependencies
------------
+------------
 
 TCRM relies on a number of additional libraries that are not part of
 the standard library. There are several ways to obtain the required
 libraries -- using Python's recommended tool `pip
 <https://pip.readthedocs.org/en/latest/>`_, installing a distribution
 such as `Python(x,y) package <http://code.google.com/p/pythonxy/>`_
 (for Windows environments) or `Anaconda
-<https://store.continuum.io/cshop/anaconda/>`_ (cross-platform), or
+<https://www.anaconda.com/distribution/#download-section>`_ (cross-platform), or
 installing the libraries from source or binary installers
 (pre-compiled binary Windows installer versions for all the libraries
 (both 32-bit and 64-bit) can be obtained `here
@@ -88,7 +86,7 @@ installing the libraries from source or binary installers
 For detailed instructions on installation of these dependencies,
 please see the documentation for each individual library.
 
-* `Python <https://www.python.org/>`_ - v2.7 preferred
+* `Python <https://www.python.org/>`_ - v3.5 or later
 * `Numpy <http://www.numpy.org/>`_ - v1.6 or later
 * `Scipy <http://www.scipy.org/>`_ - v0.12 or later
 * `Matplotlib <http://matplotlib.org/>`_ v1.2 or later. 
@@ -108,73 +106,55 @@ Using pip
 
 If you have `pip <https://pip.readthedocs.org/en/latest/>`_ installed,
 the required modules can be installed using the following command,
-executed in the main TCRM directory::
+executed in the main TCRM directory
 
-   pip -v install -r requirements.txt
+.. code-block:: bash
+
+    pip -v install -r requirements.txt
 
 This will automatically build the required libraries (listed in the
 ``requirements.txt`` file) and any dependencies. ``pip`` must be on
 the ``$PATH`` for this to work.
 
 .. _compilation:
 
-Compiling the extensions
-------------------------
-
-The model requires a number of C extensions to be compiled before
-execution. These can be built using Python's inbuilt :mod:`distutils`
-module.
-
 
-Unix
-~~~~
-From the base directory, execute the build process::
+Using Anaconda
+~~~~~~~~~~~~~~
 
-    python installer/setup.py build_ext -i
+To install ``tcrm`` in Linux it is preffered to make a new environment (perhaps call tcrm)
 
-Ubuntu
-~~~~~~
-The github branch issue_25 (created from the v2.0 branch) had an environment created by `installing miniconda
-<https://conda.io/docs/install/quick.html#linux-miniconda-install>`_ and executing the following commands::
+.. code-block:: bash
 
-        ~/miniconda2/bin/conda create --name tcrm
-        ~/miniconda2/bin/source activate tcrm
-        ~/miniconda2/bin/conda install numpy
-        ~/miniconda2/bin/conda install scipy
-        ~/miniconda2/bin/conda install matplotlib
-        ~/miniconda2/bin/conda install basemap
-        ~/miniconda2/bin/conda install netcdf4
-        ~/miniconda2/bin/conda install shapely
-        ~/miniconda2/bin/conda install Tornado
-        ~/miniconda2/bin/conda install statsmodel
-        ~/miniconda2/bin/conda install seaborn
-        ~/miniconda2/bin/pip --proxy=http://localhost:3128 install simplejson
+    conda create -n tcrm
 
+After creating the environment user need to move to that environment using the command
 
-The following libraries were needed to compile the C extensions, and run the unit tests::
+.. code-block:: bash
 
-    sudo apt install libgl1-mesa-glx
-    sudo apt-get install python-numpy-dev
+     conda activate tcrm
 
-The C extensions were compiled from the trcm directory with::
+The bash promt will look like::
 
-        (tcrm) user@server:~/tcrm$ python intaller/setup.py build_ext -i
+    (tcrm) user@server:~/tcrm$
 
-An error occurred where the include file seems to have changed paths. It may be a one off,
-or it may reoccur in another version of Linux. The error was in KPDF.c and the change was to
-comment out one line and replace it with another.::
+TCRM depends on several libraries that need to be installed.
 
-        #include "numpy/arrayobject.h"
-        /* #include "arrayobject.h" */
+.. code-block:: bash
 
-A requiremements file was created in the root directory called ``linux_v20.yml`` and should (it hasn't been tested)
-replace the ``conda install`` commands above. The command to use this file is::
+    conda install -c conda-forge gdal==3.0.2
+    conda install -c conda-forge xarray statsmodels scipy seaborn shapely
+    conda install -c conda-forge cartopy netcdf4
+    conda install -c conda-forge tqdm imageio
+    conda install -c conda-forge affine
 
-        conda env create -f linux_v20.yml
+Some libraries are easier to install with `pip
+<https://pip.readthedocs.org/en/latest/>`_.
 
-Activating the environment would be::
+.. code-block:: bash
 
-        source activate linux_v20
+    pip install pyyaml
+    pip install gitpython
 
 
 Windows
@@ -199,15 +179,17 @@ installations.
 .. _testing:
 
 Testing the installation
------------------------
+------------------------
 
 The model code includes a suite of unit tests that ensure elements of
 the code base will work as expected, even if a user makes
 modificaitons to the code.
 
 The test suite can be run from the main directory. On Windows, run the
 ``run_test_all.cmd`` script from the main TCRM directory. On Unix, use
-the command::
+the command
+
+.. code-block:: bash
 
     python ./tests/run.py
 
@@ -254,7 +236,9 @@ system.
 Test the installation
 ~~~~~~~~~~~~~~~~~~~~~
 
-Run this command ::
+Run this command
+
+.. code-block:: bash
 
     docker run olivierdalang/tcrm nosetests --exe
 
@@ -269,7 +253,9 @@ To run TCRM though Docker, you need to mount a folders containing your
 inputs and the output folder in the container.
 
 This can be done like this (assuming you have a my_conf.ini file in
-a folder) ::
+a folder)
+
+.. code-block:: bash
 
     docker run -v /path_to/my_data_folder:/home/src/mount -v /path_to/my_output_folder:/home/src/output olivierdalang/tcrm python tcevent.py -v -c mount/my_conf.ini
 
@@ -283,24 +269,28 @@ take some time.
 Developement
 ~~~~~~~~~~~~
 
-You can also use Docker when developping TCRM by mounting the source::
+You can also use Docker when developping TCRM by mounting the source
+
+.. code-block:: bash
 
     git checkout https://github.com/GeoscienceAustralia/tcrm.git
     cd tcrm
     docker run -v ${PWD}:/home/src olivierdalang/tcrm python tcevent.py -c example/yasi.ini
 
-If you wish to make changes to the builds steps or dependencies, you need to rebuild the image locally ::
+If you wish to make changes to the builds steps or dependencies, you need to rebuild the image locally
 
     docker build -t olivierdalang/tcrm .
 
 Releases
 ~~~~~~~~
 
 For users to be able to use the docker image out of the box without having to rebuild it locally,
-the image must be pushed to the docker hub repository like this ::
+the image must be pushed to the docker hub repository like this
+
+.. code-block:: bash
 
     docker build -t olivierdalang/tcrm .
     docker login
     docker push olivierdalang/tcrm
 
-This can be setup to be done automatically after pushes through docker hub.
+This can be setup to be done automatically after pushes through docker hub.