Merge branch 'master' of https://srccontrol.orr.noaa.gov/gnome/pygnome

InstallingWithAnaconda.rst

@@ -1,10 +1,12 @@
-Building / Installing GNOME with the Anaconda python distribution
-=================================================================
+Building / Installing GNOME with the conda / Anaconda python distribution
+=========================================================================
 
 `Anaconda <https://store.continuum.io/cshop/anaconda/>`__ is a Python
 distribution that has most of the difficult-to-build packages that
 ``py_gnome`` needs already built in. Thus it's a nice target for running
-GNOME on your own system.
+GNOME on your own system. "conda" is the pacakg manager used to manage the system.
+
+py_gnome CAN be used with any Python distribution, but you will need to find or build a number of pacakges that are not easy to manage. If you are familiar with complex python packaging, then you can probably make it work. But conda makes it much easier, and that's what we support.
 
 Anaconda vs miniconda:
 ----------------------
@@ -15,7 +17,15 @@ Anaconda vs miniconda:
 
 Either will work fine with ``py_gnome``.
 
-NOTE: be sure to get the python2 version of Anaconda.
+**NOTES:**
+
+Be sure to get the python2 version of Anaconda.
+
+Anaconda (and miniconda?) can be installed in either single-user or multi-user mode:
+
+https://docs.continuum.io/anaconda/install
+
+We (and Continuum) recommend single-user mode -- that way, administrator privileges are not required for either initial installation or maintaining the system.
 
 Windows:
 ........
@@ -24,6 +34,7 @@ You want the Windows 64 bit Python 2.7 version. Installing with the
 defaults works fine. You probably want to let it set the PATH for you --
 that's a pain to do by hand.
 
+
 OS-X:
 .....
 
@@ -72,7 +83,6 @@ Enter the following on the command-line::
 
 will update the conda package manager itself (and its dependencies)
 
-
 Setting up anaconda.org channels
 ................................
 
@@ -89,10 +99,10 @@ The "conda-forge" project:
 
 https://conda-forge.github.io/
 
-Is a community project to build a wide variety of pacakges for conda -- it supports
+Is a community project to build a wide variety of packages for conda -- it supports
 most of what PyGNOME needs.
 
-However, there a few NOAA-spcific packages that are not (yet) on conda-forge, so we
+However, there a few NOAA-specific packages that are not (yet) on conda-forge, so we
 have set up `our own anaconda channel <https://anaconda.org/noaa-orr-erd>`__
 where we put various packages needed for ``py_gnome``.
 
@@ -103,13 +113,21 @@ Add the NOAA-ORR-ERD channel::
 
     > conda config --add channels NOAA-ORR-ERD
 
-to add conda-forge::
+Add the conda-forge channel::
 
     > conda config --add channels conda forge
 
 When you add a channel to conda, it puts it at the top of the list. So now when you
 install a package, conda will first look in conda-forge, then NOAA-ORR-ERD, and
-then in the default channel. This order should work well for PyGNOME.
+then in the default channel. This order should work well for PyGNOME. Be sure to add the channels in the order we specify. You can see what channels you have with::
+
+    > conda config --get channels
+
+It should return something like this::
+
+    --add channels 'defaults'   # lowest priority
+    --add channels 'NOAA-ORR-ERD'
+    --add channels 'conda-forge'   # highest priority
 
 
 conda environments
@@ -121,9 +139,11 @@ see:
 
 http://conda.pydata.org/docs/using/envs.html
 
-If you are using Anaconda for other projects that might depend on
-specific versions of specific libraries (like numpy, scipy, etc), then
-you may want create an environment for PyGNOME::
+IF you are only going to use Python / Anaconda for PyGNOME, then you
+can ignore this. However, if you are using Anaconda for other projects
+that might depend on specific versions of specific libraries
+(like numpy, scipy, etc), then you may want create an environment
+for PyGNOME::
 
     conda create --name gnome python=2
 
@@ -150,7 +170,7 @@ and kept separate from your main Anaconda install.
 You will need to activate the environment any time you want to work with
 ``py_gnome`` in the future
 
-**NOTE:** if you are only using Python / Anaconda for GNOME, there is not reason to deal with the complications of environments.
+**NOTE:** Again, if you are only using Python / Anaconda for GNOME, there is not reason to deal with the complications of environments.
 
 Download GNOME
 --------------
@@ -216,6 +236,29 @@ This should install all the packages required by ``py_gnome``.
 (make sure you are in the correct conda environment, and you have the
 conda-forge and NOAA-ORR-ERD channels enabled.)
 
+If installing conda_requirements.txt fails:
+...........................................
+
+If you get an error about a particular package not being able to be installed, then conda will not install ANY of the packages in the file. We try hard to make sure everything is available on one of the channels we recommend. If however, a package of that particular version is missing, you can try:
+
+Edit the conda_requirements.txt file and comment out the offending package by putting a "#" at the start of the line::
+
+    ...
+    scipy>=0.17
+    py_gd>=0.1.5
+    # libgd>=2.2.2
+    gsw>=3.0.3
+    ...
+
+That will disable that particular package, and hopefully everything else will install.
+
+YOu can then try installing the offending package without a version specification::
+
+    > conda install libgd
+
+And it may work for you.
+
+
 The Oil Library
 ---------------
 
@@ -379,3 +422,32 @@ are not on the internet, this will fail. And of course if you have a
 slow connection, these files could take a while to download. Once the
 tests are run once, the downloaded files are cached for future test
 runs.
+
+Running scripts
+---------------
+
+There are some example scripts in the ``scripts`` directory. You should be able to run these scripts in the same way as any Python script (with an IDE such as Spyder or PyCharm, or at the command line).
+
+To run a script on the command line::
+
+    cd py_gnome/scripts
+    cd script_boston
+
+as an example -- there are quite a few.
+
+If you are using a conda environment:
+
+    source activate gnome
+
+or on Windows::
+
+    activate gnome
+
+Run the script::
+
+    python script_boston.py
+
+Each of the scripts exercised different features of py_gnome -- they are hopefully well commented to see how they work.
+
+
+

conda_requirements.txt

@@ -3,43 +3,47 @@
 #  This should be the minimal conda install
 #  install with:
 #  conda install --file conda_requirements.txt
-# These pacakgesld all be in one of the follwoing channels:
+# These packages would all be in one of the following channels:
 # defaults
 # conda-forge
 # NOAA-ORR-ERD
 
-python=2.7*
+python=2.7.*
 setuptools>=23.0
-numpy>=1.11
-scipy>=0.17
-netCDF4>=1.2.2
-py_gd>=0.1.5
-libgd>=2.2.2
-gsw>=3.0.3
-pyzmq>=15.2
-cython=0.24.1
+numpy=1.11.*
+scipy>=0.18.*
+gsw=3.0.3
 psutil>=4.3
 progressbar>=2.3
+pyzmq>=16
 six>=1.10
-geojson>=1.3.2
-repoze.lru >= 0.6
-unit_conversion>=2.5.2
+geojson>=1.3
+repoze.lru>=0.6
 colander>=1.2
 sqlalchemy>=0.7.6
 zope.interface>=4.1
 zope.sqlalchemy>=0.7.6
-gdal>=2.0
+gdal>=2.1.1
+netCDF4=1.2.7
 awesome-slugify>=1.6
 regex>=2014.12
 unidecode>=0.04.19
-cell_tree2d>=0.1.3
-pyugrid>=0.2.1
-pysgrid>=0.3.1
 pyshp>=1.2
+pyugrid>=0.2.2
+pysgrid>=0.3.3
+
+# NOAA maintained packages
+unit_conversion=2.5.5
+cell_tree2d>=0.3.0
+py_gd>=0.1.5 # libgd should get brought in automatically
+
+# required for building
+cython=0.24.1
 
 # nice to have for development, not required to run
 pytest
 testfixtures
 matplotlib
 sphinx
 ipython
+