Merge pull request #1330 from astrofrog/update-installation

Significantly refactor/improve installation instructions

doc/index.rst

@@ -59,7 +59,7 @@ Using the Glue application
 .. toctree::
    :maxdepth: 2
 
-   installation.rst
+   installation/installation.rst
    getting_started/index.rst
    gui_guide/index.rst
    gui_guide/3d_viewers.rst

doc/installation/app.rst

@@ -0,0 +1,14 @@
+:orphan:
+
+Standalone Application
+======================
+
+**Platforms:** MacOS X
+
+Mac users with OS X >= 10.7 can download Glue as a `standalone program
+<http://mac.glueviz.org>`_. This is a fast way to get started with using
+Glue, but this application includes its own version of Python, and will not
+recognize any packages in other Python installations. If you want to use glue in
+your existing Python installation, follow instructions in the other sections.
+Note that there may be a delay between when a release is announced, and when the
+dmg installer is available.

doc/installation/conda.rst

@@ -0,0 +1,98 @@
+
+Anaconda Python Distribution (Recommended)
+==========================================
+
+**Platforms:** MacOS X, Linux, and Windows
+
+We recommend using the `Anaconda <http://continuum.io/downloads.html>`__ Python
+distribution from Continuum Analytics (or the related Miniconda distribution).
+Anaconda includes all of Glue's main dependencies. There are two ways of
+installing Glue with the Anaconda Python Distribution: :ref:`graphically using the
+Anaconda Navigator <anaconda_gui>`, or :ref:`using the conda command
+<anaconda_cli>` on the command-line, both of which are described
+below.
+
+.. _anaconda_cli:
+
+Command-line installation
+-------------------------
+
+We recommend installing glue using the ``conda`` command on the command-line
+rather than using the :ref:`anaconda_gui`, because errors are more visible on
+the command-line if you run into any issues during the installation. Once
+Anaconda (or Miniconda) is installed, open a terminal, and type::
+
+    conda install -c glueviz glueviz
+
+This will install the latest version of glue from the ``glueviz`` conda channel.
+If you run into any issues, see the `Troubleshooting`_ section below. To update
+glue in future, use the same command.
+
+.. _anaconda_gui:
+
+Graphical User Interface
+------------------------
+
+If you prefer to not use the command-line to install glue, you can also use the
+Anaconda navigator, but be aware that it is harder to diagnose issues when
+things go wrong (the navigator can sometimes silently fail). Once Anaconda is
+installed, go to the **Applications** folder and launch the **Anaconda
+Navigator**:
+
+.. image:: images/navigator_icon.png
+   :align: center
+   :width: 80
+
+If you do not have the Anaconda Navigator icon, but have an Anaconda Launcher,
+you are using an old version of Anaconda, and we recommend that you update to
+the latest version.
+
+Assuming you have the navigator open, before installing glue first click on the
+**Channels** button:
+
+.. image:: images/navigator_channels_button.png
+   :align: center
+   :width: 373
+
+If not already present, add **glueviz** to the list of channels by clicking
+on **Add**, typing **glueviz**, and pressing enter, then click on **Update
+channels**:
+
+.. image:: images/navigator_channels_dialog.png
+   :align: center
+   :width: 414
+
+You can now install the latest version of glue by clicking on **Install**:
+
+.. image:: images/navigator_install.png
+   :align: center
+   :width: 264
+
+Once the installation is complete, you can click on the **Launch** button (which
+will replace the **Install** button). If updates become available in future,
+these should be shown in the Navigator.
+
+Troubleshooting
+---------------
+
+A common source of issues with conda is that there may be conflicts between the
+version of dependencies required by glue and that required by other packages.
+The easiest way to avoid this is to install glue in a separate environment. To
+do this, first create an environment in which you will install glue::
+
+    conda create -n glueviz-env python
+
+This will create an environment called ``glueviz`` in which Python will be
+installed. You only need to create the environment once. Once created, you can
+switch to the environment with::
+
+    source activate glueviz-env
+
+Then, install glue as indicated in :ref:`anaconda_cli` using::
+
+    conda install -c glueviz glueviz
+
+Whenever you open a new terminal, if you want to run glue you should then
+remember to switch to the ``glueviz-env`` environment using the ``source
+activate`` command above. If you want to update glue, run the installation
+command again inside the environment.