Tweak the quickstart

.travis.yml

@@ -35,7 +35,7 @@ before_install:
   - conda config --set always_yes yes --set changeps1 no
   - conda update -q conda
   - conda info -a
-  - travis_wait $TRAVIS_BUILD_DIR/quickstart --pyversion $PYVERSION --name distarray-env --yes
+  - travis_wait $TRAVIS_BUILD_DIR/quickstart/conda-quickstart --pyversion $PYVERSION --name distarray-env --yes
   - source activate distarray-env
   - pip install codecov pelican
   - |

docs/sphinx/source/installation.rst

@@ -28,14 +28,14 @@ or::
     pip install distarray
 
 
-Experimental conda-quickstart
------------------------------
+Experimental quickstart scripts
+-------------------------------
 
-Alternatively, we have an experimental `conda-quickstart` script in the
-``quickstart`` directory of the root of this source tree.  Given an Anaconda
-installation, this script will attempt to install create a conda environment
-for you, installing MPI, mpi4py, and the above Python dependencies as
-necessary.  See ``README.rst`` in that directory for more information.
+Alternatively, we have experimental installation scripts in the ``quickstart``
+directory of the root of this source tree.  Given a Canopy or Anaconda
+installation and a couple of other prerequisites, these scripts attempt to
+install DistArray and its dependencies for you.  See the readme files in that
+directory for more information.
 
 
 Testing Your Installation
@@ -56,6 +56,7 @@ directory with::
 
     make test
 
-or from anywhere with::
+If you've installed DistArray with ``python setup.py develop``, you should be
+able to run the tests  from anywhere with::
 
     python -m distarray.run_tests

quickstart → quickstart/conda-quickstart

@@ -1,45 +1,41 @@
 #!/usr/bin/env bash
 
+INSTALL_MODE=install
+PROMPT_USER=true
+
 PY_VER=2
 CONDA_ENV=distarray
-INSTALL_MODE=install
-PROMPT_USER=false
-TEST_INSTALL=false
 
 usage() {
-    echo "usage: quickstart [options] <inputs>"
+    echo "usage: conda-quickstart [options] <inputs>"
     echo "-------------------------------------------------------------------------"
     echo "OPTIONS"
-    echo "--pyversion <arg>     select which version of python to use options = (2, 3) DEFAULT 2"
     echo "-h | --help           display usage message"
+    echo "--pyversion <arg>     select which version of python to use options = (2, 3) DEFAULT 2"
     echo "-n | --name <arg>     set name of created conda environment to <arg> DEFAULT distarray"
     echo "-d | --develop        perform a development install of distarray"
     echo "-y | --yes            do not ask for confirmation"
-    echo "-t | --test           test distarray after installation"
 }
 
 while [[ "$1" != "" ]]; do
     case $1 in
-    -n | --name )
-                shift
-                CONDA_ENV=$1
-                ;;
-    -d | --develop )
-                INSTALL_MODE=develop
-                ;;
     -h | --help )
                 usage
                 exit
                 ;;
-    -y | --yes )
-                PROMPT_USER=true
-                ;;
     --pyversion )
                 shift
                 PY_VER=$1
                 ;;
-    -t | --test )
-                TEST_INSTALL=true
+    -n | --name )
+                shift
+                CONDA_ENV=$1
+                ;;
+    -d | --develop )
+                INSTALL_MODE=develop
+                ;;
+    -y | --yes )
+                PROMPT_USER=false
                 ;;
              *  )
                 usage
@@ -57,8 +53,8 @@ install_openmpi() {
         brew install openmpi
         return 0
     else
-        echo "Could not install OpenMPI: no working installation of homebrew or macports found."
-        return 1
+        echo "Could not install OpenMPI: no working installation of homebrew"
+        echo "or macports found."
     fi
 }
 
@@ -90,9 +86,10 @@ resolve_conda() {
 install_osx() {
     conda create -n $CONDA_ENV python=$PY_VER numpy ipyparallel notebook cython sphinx=1.3 mock matplotlib
     source activate $CONDA_ENV
-    pip install mpi4py
-    pip install sphinxcontrib-programoutput
+    pip install mpi4py sphinxcontrib-programoutput
+    pushd ..
     python setup.py $INSTALL_MODE
+    popd
     source deactivate
     return 0
 }
@@ -101,14 +98,17 @@ install_linux() {
     conda create -n $CONDA_ENV python=$PY_VER mpi4py numpy ipyparallel notebook cython sphinx=1.3 mock matplotlib
     source activate $CONDA_ENV
     pip install sphinxcontrib-programoutput
+    pushd ..
     python setup.py $INSTALL_MODE
+    popd
     source deactivate
     return 0
 }
 
 exit_install() {
     if [[ $1 != 0 ]]; then
-        echo "Aborting DistArray quickstart install. Please refer to the quickstart instructions for troubleshooting"
+        echo "Aborting DistArray quickstart install. Please refer to the"
+        echo "quickstart instructions for troubleshooting."
         exit 1
     else
         return 0
@@ -124,11 +124,13 @@ test_install() {
 }
 
 prompt_user() {
-    echo "Press any key to continue installation with the provided options. Ctrl+C to abort."
+    echo "Press any key to continue installation with the provided options."
+    echo "Ctrl+C to abort."
     read -n 1
 }
 
-cat docs/quickstart-readme.txt
+cat conda-readme.rst
+echo
 usage
 
 if [[ "$(uname)" == "Darwin" ]]; then
@@ -150,7 +152,6 @@ if [[ "$(uname)" == "Darwin" ]]; then
     exit_install $r_stat
 else
 
-    echo "Linux support for DistArray quickstart is experimental and may not produce desired results."
     if [ "$PROMPT_USER" = true ] ; then
         prompt_user
     fi
@@ -164,16 +165,11 @@ else
     exit_install $r_stat
 fi
 
-if [ "$TEST_INSTALL" = true ] ; then
-    echo "Install Complete. Testing DistArray"
-    echo "--------------------------------------------------------------------------------------"
-    test_install
-    echo "--------------------------------------------------------------------------------------------"
-    echo "Installation complete. Use source activate $CONDA_ENV to begin working with DistArray."
-    echo "--------------------------------------------------------------------------------------------"
-else
-    echo "--------------------------------------------------------------------------------------------"
-    echo "Installation complete. Use source activate $CONDA_ENV to begin working with DistArray."
-    echo "Test your installation by running dacluster start followed by python -m distarray.run_tests."
-    echo "--------------------------------------------------------------------------------------------"
-fi
+echo "-------------------------------------------------------------------------------"
+echo "Installation complete. Use source activate $CONDA_ENV to begin working."
+echo "with DistArray."
+echo
+echo 'If you performed a development installation (with --develop), you can'
+echo 'test DistArray by running "dacluster start" followed by'
+echo '"python -m distarray.run_tests".'
+echo "-------------------------------------------------------------------------------"

quickstart/conda-readme.rst

@@ -0,0 +1,53 @@
+conda-quickstart
+================
+
+[OS X or Linux]
+
+Note: this script is currently *experimental*.
+
+The ``conda-quickstart`` script attempts to create a new conda environment that
+includes DistArray, its dependencies, and the dependencies required to build
+the DistArray docs.
+
+This script does *not* attempt to install parallel versions of hdf5 or h5py,
+which are optional dependencies.
+
+``conda-quickstart`` is intended to be run from within this directory
+
+Depending on system hardware and the prior availability of dependencies, the
+script can take anywhere from less than a minute up to a few hours to run. If
+the installation is interrupted for any reason, delete the created conda
+environment (``conda env remove -n <env-name>``) and re-run the script.
+
+Prerequisites
+-------------
+
+Prerequisites for using ``conda-quickstart`` are:
+
+- A working Anaconda or Miniconda installation
+
+Additionally, OSX users will need:
+
+- A working MPI distribution that provides the ``mpicc`` compiler wrapper
+- *OR* a working copy of HomeBrew or MacPorts to install MPI (MacPorts users will
+  need 'sudo' privileges)
+
+Notes on OS X
+-------------
+
+On OSX, ``conda-quickstart`` will install
+
+- Open MPI with MacPorts or Homebrew, if ``mpicc`` isn't found,
+- several Python dependencies using ``conda``, and finally
+- a couple of Python dependencies (those not installable with ``conda``)
+  through ``pip``.
+
+Notes on Linux
+--------------
+
+On Linux, ``conda-quickstart`` will install
+
+- Several Python dependencies using ``conda`` (including MPICH2 and mpi4py),
+  and
+- a couple of Python dependencies (those not installable with ``conda``)
+  through ``pip``.