Merge pull request #11 from tsutterley/documentation

updated install documentation

doc/source/Citations.md

@@ -0,0 +1,22 @@
+Citation Information
+====================
+
+#### References
+The programs included in this software have contributed most recently to the following work:
+
+1. Ben Smith, Helen A. Fricker, Alex S. Gardner, Brooke Medley, Johan Nilsson,
+    Fernando S. Paolo, Nicholas Holschuh, Susheel Adusumilli, Kelly Brunt, Bea Csatho,
+    Kaitlin Harbeck, Thorsten Markus, Thomas Neumann, Matthew R. Siegfried, H. Jay Zwally,
+    "Pervasive ice sheet mass loss reflects competing ocean and atmosphere processes."
+    *Science*, 368(6496), 1239–1242, 2020.
+    [doi: 10.1126/science.aaz5845](https://doi.org/10.1126/science.aaz5845)
+
+#### Dependencies
+This software is also dependent on other commonly used Python packages:
+- [numpy: Scientific Computing Tools For Python](https://numpy.org)
+- [scipy: Scientific Tools for Python](https://docs.scipy.org/doc//)
+- [matplotlib: Python 2D plotting library](https://matplotlib.org/)
+- [h5py: Python interface for Hierarchal Data Format 5 (HDF5)](http://h5py.org)
+- [netCDF4: Python interface to the netCDF C library](https://unidata.github.io/netcdf4-python/netCDF4/index.html)
+- [gdal: Pythonic interface to the Geospatial Data Abstraction Library (GDAL)](https://pypi.python.org/pypi/GDAL)
+- [pyproj: Python interface to PROJ library](https://pypi.org/project/pyproj/)

doc/source/Install.md

@@ -1,18 +1,36 @@
-Installation
-============
+Setup and Installation
+======================
 
-Presently pointCollection is only available for use as a [github repository](https://github.com/SmithB/pointCollection).
+Presently pointCollection is only available for use as a [GitHub repository](https://github.com/SmithB/pointCollection).
 The contents of the repository can be download as a [zipped file](https://github.com/SmithB/pointCollection/archive/master.zip)  or cloned.
-To use this repository, please fork into your own account and then clone onto your system.  
+To use this repository, please fork into your own account and then clone onto your system.
 ```bash
 git clone https://github.com/SmithB/pointCollection.git
 ```
-Can then install using `setuptools`
+#### Dependencies
+pointCollection is dependent on some open source programs:
+- [gdal](https://gdal.org/index.html)
+- [pyproj](https://download.osgeo.org/proj)
+- [HDF5](https://www.hdfgroup.org)
+- [netCDF](https://www.unidata.ucar.edu/software/netcdf)
+
+The version of GDAL used within pointCollection will match the version of the installed C program.  The path to the C program that will be used with pointCollection is given by:
+```bash
+gdal-config --datadir
+```
+The pointCollection installation uses the `gdal-config` routines to set the GDAL package version.  
+
+#### Installation
+Can then install using `setuptools`:
 ```bash
 python setup.py install
 ```
-or `pip`
+or `pip`:
 ```bash
 python3 -m pip install --user .
 ```
+Alternatively can install the pointCollection utilities directly from GitHub with `pip`:
+```
+python3 -m pip install --user git+https://github.com/SmithB/pointCollection.git
+```
 Executable versions of this repository can also be tested using [Binder](https://mybinder.org/v2/gh/SmithB/pointCollection/master) and [Pangeo](https://binder.pangeo.io/v2/gh/SmithB/pointCollection/master).

doc/source/index.rst

@@ -8,3 +8,4 @@ Python utilities for organizing and manipulating point data
     :caption: Getting Started:
 
     Install.md
+    Citations.md

environment.yml

@@ -11,6 +11,6 @@ dependencies:
   - netCDF4
   - h5py
   - gdal
+  - pip
   - pip:
-     - git+https://github.com/suzanne64/ATL11.git
      - git+https://github.com/tsutterley/pyTMD.git

setup.py

@@ -1,8 +1,42 @@
+import os
+import sys
+import logging
+import subprocess
 from setuptools import setup, find_packages
 
+logging.basicConfig(stream=sys.stderr, level=logging.INFO)
+log = logging.getLogger()
+
+# get long_description from README.md
 with open("README.md", "r") as fh:
     long_description = fh.read()
 
+# get install requirements
+with open('requirements.txt') as fh:
+    install_requires = fh.read().splitlines()
+
+# list of all scripts to be included with package
+scripts = [os.path.join('scripts',f) for f in os.listdir('scripts')]
+
+# run cmd from the command line
+def check_output(cmd):
+    return subprocess.check_output(cmd).decode('utf')
+
+# check if GDAL is installed
+gdal_output = [None] * 4
+try:
+    for i, flag in enumerate(("--cflags", "--libs", "--datadir", "--version")):
+        gdal_output[i] = check_output(['gdal-config', flag]).strip()
+except:
+    log.warning('Failed to get options via gdal-config')
+else:
+    log.info("GDAL version from via gdal-config: {0}".format(gdal_output[3]))
+# if setting GDAL version from via gdal-config
+if gdal_output[3]:
+    # add version information to gdal in install_requires
+    gdal_index = install_requires.index('gdal')
+    install_requires[gdal_index] = 'gdal=={0}'.format(gdal_output[3])
+
 setup(
     name='pointCollection',
     version='1.0.0.0',
@@ -22,7 +56,7 @@
         'Programming Language :: Python :: 3.6',
     ],
     packages=find_packages(),
-    install_requires=['numpy','scipy','pyproj','h5py','netCDF4','matplotlib','gdal'],
-    dependency_links=['https://github.com/suzanne64/ATL11/tarball/master',
-        'https://github.com/tsutterley/pyTMD/tarball/master'],
+    install_requires=install_requires,
+    dependency_links=['https://github.com/tsutterley/pyTMD/tarball/master'],
+    scripts=scripts,
 )