add installation docs

CHANGELOG

@@ -13,7 +13,7 @@ The rules for this file:
  * accompany each entry with github issue/PR number (Issue #xyz)
 
 ------------------------------------------------------------------------------
-??/??/2019 giacomofiorin, orbeckst
+05/16/2019 giacomofiorin, orbeckst
 
  * 0.5.0
 

doc/source/index.rst

@@ -21,14 +21,33 @@ version 3`_ (see also the files ``COPYING`` and ``COPYING.LESSER`` in
 the source distribution). Releases are available from the Python
 Package index under GridDataFormats_ and source code is available from
 the GitHub repository
-https://github.com/MDAnalysis/GridDataFormats. Please report problems
-and enhancement requests through the `issue tracker`_.
+https://github.com/MDAnalysis/GridDataFormats.
+
+.. rubric:: Participating
+
+Ask questions on the `mdnalysis-discussion mailing list`_ and join the
+discussion.
+
+Please report problems and enhancement requests through the `issue
+tracker`_.
+
+GridDataFormats is open source and welcomes your contributions. Fork
+the `GridDataFormats repository on GitHub`_ and submit a pull request. Participate on the
+`developer mailing list`_.
+
+
 
 .. _`Lesser GNU General Public License, version 3`: 
  https://www.gnu.org/licenses/lgpl-3.0.en.html
 .. _GridDataFormats: https://pypi.python.org/pypi/GridDataFormats/
 .. _issue tracker: https://github.com/MDAnalysis/GridDataFormats/issues
-
+.. _mdnalysis-discussion mailing list:
+ https://groups.google.com/group/mdnalysis-discussion
+.. _developer mailing list:
+ https://groups.google.com/group/mdnalysis-devel
+.. _GridDataFormats repository on GitHub:
+ https://github.com/MDAnalysis/GridDataFormats
+
 .. |zenodo| image:: https://zenodo.org/badge/13219/MDAnalysis/GridDataFormats.svg
  :alt: Zenodo DOI
  :target: https://zenodo.org/badge/latestdoi/13219/MDAnalysis/GridDataFormats
@@ -40,14 +59,14 @@ and enhancement requests through the `issue tracker`_.
  :numbered:
  :maxdepth: 1
 
+ installation 
  gridData/overview
  gridData/basic
  gridData/formats
  gridData/core
 
 
-Indices and tables
-==================
+.. rubric:: Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`

doc/source/installation.rst

@@ -0,0 +1,66 @@
+Installation
+============
+
+GridDataFormats can be easily installed via the :ref:`conda<conda-install>` or
+:ref:`pip<pip-install>` package managers. 
+
+It is a pure-python package but it has a few other packages (namely
+scipy) as dependencies that contain compiled code. For ease of
+installation we recommend :ref:`conda<conda-install>` but
+:ref:`pip<pip-install>` and installation from source are also fully
+supported.
+
+
+
+.. _conda-install:
+
+Installing GridDataFormats with ``conda``
+-----------------------------------------
+
+The `conda`_ package manager installs, runs, and updates whole
+environments with all their dependencies.
+
+Installing *GridDataFormats* from the *conda-forge* channel can be
+achieved by adding "conda-forge" to your channels with::
+
+ conda config --add channels conda-forge
+
+Once the *conda-forge* channel has been enabled, *GridDataFormats* can
+be installed with::
+
+ conda install griddataformats
+
+Any missing dependencies will be automatically downloaded and
+installed in the appropriate versions.
+
+You can later update with ::
+
+ conda update griddataformats
+
+
+.. _conda: https://docs.conda.io/ 
+
+.. _pip-install:
+
+Installing GridDataFormats with ``pip``
+---------------------------------------
+
+Install with `pip`_::
+
+ pip install gridDataFormats
+
+and you can later update with ::
+
+ pip install --upgrade gridDataFormats
+
+
+`pip` also automatically downloads all missing dependencies and will
+attempt to compile them if necessary; this step can fail if you do not
+have the correct build environment with the necessary compilers
+installed. You should then read the pip_ documentation to learn what
+is needed or switch to the :ref:`conda installation<conda-install>`.
+
+
+.. _pip: https://pip.pypa.io/
+
+