Update information on installing and getting started

Author: mwaskom

doc/install.rst

@@ -1,15 +1,33 @@
 .. _install:
 
-Installation and Dependencies
-=============================
+Installing and Getting Started
+==============================
 
-Installing PySurfer is quite simple with easy_install_::
+Installing PySurfer is quite simple with pip_::
 
-    easy_install -U pysurfer
+    pip install pysurfer
 
-or pip_::
+If you already have PySurfer installed, you can also use pip to update it::
 
-    pip install pysurfer
+    pip install -U pysurfer
+
+If you'd like to install the development version, you have two options. You can
+use pip::
+
+    pip install git+git://github.com/nipy/pysurfer.git#egg=pysurfer
+
+Or you can clone the `git repository <https://github.com/nipy/PySurfer>`_ and
+install from the source directory::
+
+    python setup.py install
+
+If you don't have pip, you can also install PySurfer with easy_install_, or use
+easy_install to get pip.
+
+Dependencies
+~~~~~~~~~~~~
+
+PySurfer requires Python 2.7, and it does not work on Python 3.
 
 To use PySurfer, you will need to have the following Python packages:
 
@@ -19,17 +37,42 @@ To use PySurfer, you will need to have the following Python packages:
 * nibabel_
 * mayavi_
 * matplotlib_
-* PIL_
 
-An easy option to get all of these packages is to use the Enthought
-Python Distribution (EPD_) which is free for academic use.
+Some functions also make use of the Python Imaging Library (PIL_), although
+it's not mandatory.
 
-.. include:: links_names.txt
+An easy option to set up this environment is the Anaconda_ distribution, which
+is free and ships with many of the required packages. If you use Anaconda,
+you'll need to install Mayavi separately. This can be done using the ``conda``
+command::
+
+    conda install mayavi
 
-.. note::
+You'll also need to install nibabel, which can be done using ``pip`` as above.
+
+Another option for getting set up is the Enthough Canopy_ environment, which is
+similar to Anaconda and free for academic use.
+
+Getting started
+~~~~~~~~~~~~~~~
+
+PySurfer generally works out of the box on Linux systems. Getting started on
+OSX can be a bit more difficult. We have had success using the Anaconda
+distribution with the additional step of setting the environment variable
+``QT_API`` to ``pyqt``::
+
+    export QT_API=pyqt
+
+If you want to use PySurfer interactively, you should do so in ipython_. After
+starting ipython (either in the terminal, qtconsole, or notebook), you have to
+activate the correct GUI backend, which is probably qt::
+
+    %gui qt
+
+This will allow you to have an open PySurfer window while still being able to
+execute code in the console/notebook.
+
+If you are having trouble getting started using PySurfer, please describe the problem on the `nipy mailing list`_.
+
+.. include:: links_names.txt
 
-    For optimal results and performance make sure IPython is invoked using the
-    best GUI back end. In an EPD environment on Mac OS X this would be WX,
-    so `ipython --pylab wx`. On Linux Debian / Ubuntu (Neurodebian) QT seems
-    to be more appropriate, so `ipython --pylab qt`. Reports for other platforms
-    and distributions are appreciated.

doc/links_names.txt

@@ -75,6 +75,8 @@
 .. _EPD: http://www.enthought.com/products/epd.php
 .. _Traits: http://code.enthought.com/projects/traits/
 .. _PIL: http://www.pythonware.com/products/pil/
+.. _Anaconda: https://store.continuum.io/cshop/anaconda/
+.. _Canopy: https://www.enthought.com/products/canopy/
 
 .. Python imaging projects
 .. _PyMVPA: http://www.pymvpa.org

setup.py

@@ -77,6 +77,7 @@ def check_dependencies():
           zip_safe=False,  # the package can run out of an .egg file
           classifiers=['Intended Audience :: Science/Research',
                        'Intended Audience :: Developers',
+                       'Programming Language :: Python :: 2.7',
                        'License :: OSI Approved',
                        'Programming Language :: Python',
                        'Topic :: Software Development',