Clean commit of new install docs (conda environments and astropy-dev)

tutorials/01-conda_astropy_install.rst

@@ -0,0 +1,148 @@
+Installing Astropy and Related Packages with Anaconda
+=====================================================
+
+Pre-requisites
+--------------
+
+**Mac** Have the latest version of `Xcode
+developer <https://developer.apple.com/xcode/>`__ tools installed
+
+**Windows** Be able to access a terminal, either through a `Linux
+subsystem <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`__
+or by installing the `Linux bash
+shell <https://www.howtogeek.com/249966/how-to-install-and-use-the-linux-bash-shell-on-windows-10/>`__
+
+Step 1: Download Anaconda
+-------------------------
+
+The Anaconda Python distribution can be downloaded from
+https://www.anaconda.com/download
+
+-  The scientific computing community is now using Python 3 as a
+   default.
+
+**But my code only runs in Python 2** Please see the next tutorial: *An
+Astropy User's Guide to Managing Conda Environments*
+
+-  When the download is finished, click on the package and follow the
+   installation instructions.
+
+-  Open a terminal window to check that the Anaconda installation will
+   work for you:
+
+   ::
+
+       which conda
+
+   should return something like ``/anaconda3/bin/conda`` and
+
+   ::
+
+       which python
+
+   should return a Python path that is in the same directory as
+   Anaconda: ``/anaconda3/bin/python``
+
+Step 2: Install core packages
+-----------------------------
+
+The default Anaconda installation comes with many packages that
+astronomers use frequently: *numpy*, *scipy*, and *matplotlib*
+
+We can use the ``conda install`` command to install everything else we
+need. Anaconda will automatically check, update, and install any python
+packages that your desired package depends on.
+
+-  Below, we give an example of installing astropy along with some common 
+   scientific, statistical, and visualization packages. You can install them all
+   individually or in one line:
+
+::
+
+    conda install astropy matplotlib scikit-learn pandas
+
+Step 3: Install affiliated packages
+-----------------------------------
+
+Many `Astropy affiliated
+packages <https://www.astropy.org/affiliated/>`__ can be found on
+*astropy* channel, maintained by AURA and STScI. To add this channel
+to Anaconda's package search list, run the following command:
+
+::
+
+    conda install --channel "astropy" package
+
+Some astronomical packages are also available in the *conda-forge*
+channel. There is no wrong choice between installing a package from
+*astropy* versus *conda-forge*. However, a package that is available
+in the *astropy* channel may not be available in *conda-forge*.
+
+Note also that there is an `*astroconda* channel managed by STScI
+<https://astroconda.readthedocs.io/en/latest/installation.html#configure-conda-to-use-the-astroconda-channel>`__
+that includes IRAF/pyraf and several other modern packages.
+
+To see what channels you have available:
+
+::
+
+    conda config --show channels
+
+`More information on managing channels in
+Anaconda <https://conda.io/docs/user-guide/tasks/manage-channels.html>`__
+is available on the main documentation pages.
+
+-  Here's an example for downloading a few commonly used Astropy
+   affiliated packages, directly from the *astropy* channel:
+
+   ::
+
+       conda install -c astropy photutils specutils
+
+**Note:** If you plan to use the ``astroquery`` package, we recommend using ``pip install`` instead of ``conda install``. See the *Conda vs Pip* discussion, below.
+
+Additional materials
+====================
+
+How to upgrade a package or install a specific version
+------------------------------------------------------
+
+To upgrade to the latest version of Astropy:
+
+::
+
+    conda update astropy
+
+You can choose a specific Astropy version using:
+
+::
+
+    conda install astropy=2.0
+
+Conda vs Pip
+------------
+
+Anaconda is one of several package management systems that you might use
+for Python. The `Python Package Index <https://pypi.org/>`__ project
+also provides a package management program called `pip <https://pypi.org/project/pip/>`__.
+
+Generally, you should pick one package management system and stick to
+it. However, there may be cases where a package is available with
+``pip`` and not ``conda``, or vice versa.
+
+With Anaconda, you can still use ``pip`` to download and install
+software within the conda environment of your choice. However,
+conflicts will arise if you ``pip install`` a package that has already
+been installed with ``conda``, or vice versa. So once you use ``pip``
+to install a package, you should use ``pip`` to update and manage that
+package.
+
+**In particular, we recommend using `pip` to manage the `astroquery`
+  package.** This library is under continuous development. The latest
+  versions and bug-fixes are more readily available with ``pip``,
+  because it takes a long time for the ``conda`` distribution to
+  update.
+
+Further documentation on this topic is available on the `conda package
+management documentation
+page <https://conda.io/docs/user-guide/tasks/manage-pkgs.html>`__.

tutorials/02-conda_envs.rst

@@ -0,0 +1,115 @@
+An Astropy User's Guide to Managing Conda Environments and Jupyter Notebook
+===========================================================================
+
+
+    Help! My code library works in Python 2 and I don't have time to
+    make it work in Python 3
+
+Do not fear! This tutorial will teach you how to use conda environments
+to create a *separate* installation of Python 2.7. With conda
+environments, you can switch between Python 2 and 3 without having to
+worry about version conflicts.
+
+Step 1: Set up a Python 2 environment
+-------------------------------------
+
+-  Create a new ``conda`` environment
+
+   ::
+
+       conda create -n python2 python=2.7 anaconda 
+
+**NOTE:** By adding ``anaconda`` at the end, the complete Anaconda Python distribution will be installed. Omitting ``anaconda`` or choosing ``miniconda`` will install a much smaller library of Python packages. You can install any additional packages you need for that environment, after activating it. `Some information about the differences between Anaconda and Miniconda can be found in the conda document pages <https://conda.io/docs/user-guide/install/download.html#anaconda-or-miniconda>`__
+
+-  Activate the Python 2 environment and install any additional packages
+   you need to run your favorite code library. Here, we show you how to 
+   install the base version of Astropy. 
+
+    ::
+
+        source activate python2
+        conda install astropy
+
+**NOTE:** If you want to install Astropy and **all** affiliated packages, you can use `` conda install stsci``
+
+-  When you are ready to return to your default environment:
+
+   ::
+
+       source deactivate
+
+**NOTE:** Some newer versions of Anaconda use ``conda activate`` and
+``conda deactivate``. In that case, both ``source`` and ``conda`` will work 
+interchangeably when activating or deactivating your chosen environment.
+
+When you want to see all of your available environments:
+
+::
+
+    conda env list
+
+Step 2: Check that your code runs in the new environment
+--------------------------------------------------------
+
+-  Now you are ready to work in Python 2! Here's a generic example for
+   switching to your Python 2 environment, running your Python 2 script,
+   and exiting the environment.
+
+    ::
+
+        cd ~/my-python2-library
+        source activate python2
+        python my_python2_script.py
+        source deactivate
+
+Step 3: Set up a Jupyter Notebook for the new environment
+---------------------------------------------------------
+
+-  Activate your custom Python 2 environment:
+
+   ::
+
+       source activate python2
+
+-  Check that you have ipykernel installed
+
+   ::
+
+       conda list | grep ipykernel
+
+If you do not see any output, install it with
+``conda install ipykernel``
+
+-  Install that environment for Jupyter notebook. In this case, we are
+   choosing a display name, "python2", that matches the environment name, 
+   but you may choose something else.
+
+    ::
+
+        python -m ipykernel install --user --name python2 --display-name "python2"`
+
+- Now leave that environement
+
+    ::
+
+        source deactivate
+
+-  Start a Jupyter Notebook session
+
+   ::
+
+       jupyter notebook
+
+-  When you click on *New*, you should see a drop down list of options
+   that include "python2", the environment display name we chose above.
+
+-  If you would like to change the environment for an existing Jupyter
+   Notebook, click on *Kernel*, then *Change kernel*, and select the
+   environment you would like to use.
+
+-  In general, you can view your available Jupyter Notebook kernels by
+   running
+
+   ::
+
+       jupyter kernelspec list