Merge pull request #646 from enthought/feature/update-docs-for-0.6

Update docs for 0.6

Author: bgrant

docs/sphinx/source/build-the-docs.rst

@@ -3,8 +3,7 @@ Building the docs
 
 Dependencies to build the documentation:
 
-* Sphinx
-* sphinxcontrib.napoleon
+* Sphinx >= 1.3
 * sphinxcontrib.programoutput
 
 If you have the dependencies listed above, and you want to build the

docs/sphinx/source/conf.py

@@ -45,7 +45,9 @@
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-needs_sphinx = '1.3'
+needs_sphinx = '1.3'  # so we have sphinx.ext.napoleon
+                      # otherwise you could install and use
+                      # sphinxcontrib.napoleon
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.

docs/sphinx/source/environment-modules-notes.rst

@@ -1,6 +1,18 @@
 Notes on building environment-modules
 =====================================
 
+Update 2015-10-05
+-----------------
+Below are Mark Kness' notes on building and using ``environment-modules``.  I
+have since found lmod_ to be a slightly better documented and supported
+alternative.
+
+- Bob Grant
+
+.. _lmod: https://www.tacc.utexas.edu/research-development/tacc-projects/lmod
+
+Environment Modules
+-------------------
 environment-modules is a tool, written with Tcl, that makes it convenient to
 switch environment settings.  It is not required to use DistArray, but we find
 it useful in development.  It is a difficult name to google.  I had to build it

docs/sphinx/source/getting-started.rst

@@ -4,6 +4,7 @@ Getting Started
 To see some examples of what DistArray can do, check out our IPython notebooks
 on nbviewer (also in the ``examples`` directory of the DistArray source).
 
-* `DistArray Features <http://nbviewer.ipython.org/github/enthought/distarray/blob/master/examples/features.ipynb>`_ 
+* `DistArray Features <http://nbviewer.ipython.org/github/enthought/distarray/blob/master/examples/features.ipynb>`_
 * `Seismic Volume <http://nbviewer.ipython.org/github/enthought/distarray/blob/master/examples/seismic_volume/seismic_volume.ipynb>`_
 * `Julia Set <http://nbviewer.ipython.org/github/enthought/distarray/blob/master/examples/julia_set/julia_set.ipynb>`_
+* `Gaussian Elimination <http://nbviewer.ipython.org/github/enthought/distarray/blob/master/examples/gauss_elimination/ge_notebook.ipynb>`_

docs/sphinx/source/hdf5-notes.rst

@@ -1,6 +1,26 @@
 Building HDF5 and h5py for DistArray
 ====================================
 
+If you want to use DistArray's parallel IO capabilities on HDF5 files,
+parallel-enabled HDF5 and h5py installations are required.  Unfortunately,
+installing these can be somewhat of a pain.
+
+Update 2015-10-05
+-----------------
+
+The "Original Notes" below are pretty old at this point.  Recently I have had
+success installing a parallel-enabled HDF5 (1.8.15) using Homebrew on OS X::
+
+    $ brew install hdf5 --with-mpi
+
+The instructions for building ``h5py`` on top of a parallel hdf5 have also
+changed, but are available
+`here <http://docs.h5py.org/en/latest/mpi.html#building-against-parallel-hdf5>`_.
+
+
+Original Notes
+--------------
+
 These are notes from trying to build HDF5 1.8.12 and h5py 2.2.1 against mpi4py
 1.3 and openmpi-1.6.5 on OS X 10.8.5.
 
@@ -43,7 +63,7 @@ directory::
 This gives me an error about "MPI Message" addressed here::
 
     https://github.com/h5py/h5py/issues/401
-   
+
 After patching api_compat.h as suggested, it builds.  One could also use the
 ``master`` version of h5py from GitHub instead of the latest release.
 

docs/sphinx/source/history.rst

@@ -2,6 +2,5 @@ History
 -------
 
 DistArray was started by Brian Granger in 2008 and is currently being developed
-at Enthought by a team led by Kurt Smith, in partnership with Bill Spotz from
-Sandia's (Py)Trilinos project and Brian Granger and Min RK from the IPython
-project.
+by Enthought in partnership with Bill Spotz from Sandia's (Py)Trilinos project
+and Brian Granger and Min RK from the IPython project.

docs/sphinx/source/installation.rst

@@ -3,13 +3,13 @@ Installation
 
 DistArray requires the following Python libraries:
 
-* `NumPy`_,
-* `IPython`_, and
-* `Mpi4Py`_.
+* `numpy`_,
+* `ipyparallel`_, and
+* `mpi4py`_.
 
-.. _NumPy: http://www.numpy.org
-.. _IPython: http://ipython.org
-.. _Mpi4Py: http://mpi4py.scipy.org
+.. _numpy: http://www.numpy.org
+.. _ipyparallel: https://github.com/ipython/ipyparallel
+.. _mpi4py: http://mpi4py.scipy.org
 
 Optionally, DistArray can make use of:
 
@@ -28,17 +28,27 @@ or::
     pip install distarray
 
 
+Experimental conda-quickstart
+-----------------------------
+
+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.
+
+
 Testing Your Installation
 -------------------------
 
 To test your installation, you will first need to start an IPython.parallel
-cluster with MPI enabled.  The easist way is to use use the ``dacluster``
-command that comes with DistArray::
+cluster with MPI enabled.  The easist way is to use the ``dacluster`` command
+that comes with DistArray::
 
     dacluster start
 
 See ``dacluster``'s help for more::
-    
+
     dacluster --help
 
 You should then be able to run all the tests from the DistArray source