Merge pull request #470 from ppxasjsm/gh-pages

Adding extended setup instructions

Author: maxim-belkin

setup.md

@@ -24,78 +24,140 @@ title: Setup
 
 
 
-> ## Software
-> [Python](http://python.org) is a popular language for
-> scientific computing, and great for general-purpose programming as
-> well.  Installing all of its scientific packages individually can be
-> a bit difficult, so we recommend an all-in-one installer.
+> ## Installing Python using Anaconda
+> [Python][python] is a popular language for scientific computing, and great for
+> general-purpose programming as well. Installing all of the scientific packages we use in the lesson
+> individually can be a bit cumbersome, and therefore recommend the all-in-one
+> installer [Anaconda][anaconda].
 >
-> For this workshop we use Python version 3.x.
->
-> ### Required Python Packages for this workshop
->
-> * [Pandas](http://pandas.pydata.org/)
-> * [Jupyter notebook](http://jupyter.org/)
-> * [Numpy](http://www.numpy.org/)
-> * [Matplotlib](http://matplotlib.org/)
+> Regardless of how you choose to install it, please make sure you install Python
+> version 3.x (e.g., 3.6 is fine). 
 {: .prereq}
 
-## Install the workshop packages
+### Windows - [Video tutorial][video-windows]
+
+1. Open <https://www.anaconda.com/products/individual> in your web browser.
+
+2. Download the Python 3 installer for Windows.
+
+3. Double-click the executable and install Python 3 using the recommended settings. Make sure that **Register Anaconda as my default Python 3.x** option is checked - it should be in the latest version of Anaconda
+
+
+### Mac OS X - [Video tutorial][video-mac]
+
+1. Visit <https://www.anaconda.com/products/individual> in your web browser.
+
+2. Download the Python 3 installer for OS X. These instructions assume that you use the graphical installer `.pkg` file.
+
+3. Follow the Python 3 installation instructions. Make sure that the install location is set to "Install only for me" so Anaconda will install its files locally, relative to your home directory. Installing the software for all users tends to create problems in the long run and should be avoided.
+
+
+### Linux
+
+Note that the following installation steps require you to work from the terminal (shell). 
+If you run into any difficulties, please request help before the workshop begins.
+
+1.  Open <https://www.anaconda.com/products/individual> in your web browser.
+
+2.  Download the Python 3 installer for Linux.
+
+3.  Install Python 3 using all of the defaults for installation.
+
+    a.  Open a terminal window.
 
-For installing these packages we will use Anaconda or Miniconda.
-They both use [Conda](https://conda.io/en/latest/), the main difference is
-that Anaconda comes with a lot of packages pre-installed.
-With Miniconda you will need to install the required packages.
+    b.  Navigate to the folder where you downloaded the installer
 
-### Anaconda installation
+    c.  Type
 
-Anaconda will install the workshop packages for you.
+    ~~~
+    bash Anaconda3-
+    ~~~
+    {: .language-bash}
 
-#### Download and install Anaconda
+    and press <kbd>Tab</kbd>.  The name of the file you just downloaded should appear.
 
-Download and install [Anaconda](https://www.anaconda.com/distribution/#download-section).
-Remember to download and install the installer for Python 3.x.
+    d.  Press <kbd>Return</kbd>.
 
-#### Download plotting package
+    e.  Follow the text-only prompts.  When the license agreement appears (a colon
+        will be present at the bottom of the screen) press <kbd>Spacebar</kbd> until you see the 
+        bottom of the text. Type `yes` and press <kbd>Return</kbd> to approve the license. Press 
+        <kbd>Return</kbd> again to approve the default location for the files. Type `yes` and 
+        press <kbd>Return</kbd> to prepend Anaconda to your `PATH` (this makes the Anaconda 
+        distribution your user's default Python).
 
-The plotting package plotnine is not installed by default.  From the terminal,
-type:
+
+[anaconda]: https://www.anaconda.com/
+[jupyter]: https://jupyter.org/
+[python]: https://www.python.org/
+[video-mac]: https://www.youtube.com/watch?v=TcSAln46u9U
+[video-windows]: https://www.youtube.com/watch?v=xxQ0mzZ8UvA
+
+## Opening a Conda-enabled Terminal and Verifying the Installation:
+
+### Windows
+Click Start, search, or select Anaconda Prompt from the menu. A window should pop up where you can now type commands such as checking your Conda installation with:
 
 ~~~
-conda install -c conda-forge plotnine
+conda --help
 ~~~
 {: .language-bash}
 
-### Miniconda installation
+### Mac OSX
 
-Miniconda is a "light" version of Anaconda. If you install and use Miniconda
-you will also need to install the workshop packages.
+Click the Launchpad icon in the Dock, type Terminal in the search field, then click Terminal. 
+A window should pop up where you can now type commands such as checking your conda installation with:
 
-#### Download and install Miniconda
+~~~
+conda --help
+~~~
+{: .language-bash}
 
-Download and install [Miniconda](https://docs.conda.io/en/latest/miniconda.html)
-following the instructions. Remember to download and run the installer for
-Python 3.x.
+### Linux
+This depends a bit on your Linux distribution, but often you will have an Applications listing in which you can select a Terminal icon you can click. A window should pop up where you can now type commands such as checking your conda installation with:
 
-#### Check the installation of Miniconda
+~~~
+conda --help
+~~~
+{: .language-bash}
+
+
+## Required Python Packages for this Workshop
+The following are packages needed for this workshop:
+
+* [Pandas](https://pandas.pydata.org/)
+* [Jupyter notebook](https://jupyter.org/)
+* [Numpy](https://numpy.org/)
+* [Matplotlib](https://matplotlib.org/)
+* [Plotnine](https://plotnine.readthedocs.io/en/stable/)
 
-From the terminal, type:
+All packages apart from plotnine will have automatically been installed with Anaconda and we can use anaconda as a package manager to install the missing `plotnine` package:
+You need to open up a *Terminal*, if you are using Mac OSX, or Linux (see instructions above), or launch an *anaconda-promt*, if you are using Windows. In your terminal window type the following: 
 
 ~~~
-conda list
+conda install -y -c conda-forge plotnine
 ~~~
 {: .language-bash}
 
-### Install the required workshop packages with conda
+This will then install the latest version of plotnine into your conda environment. 
 
-From the terminal, type:
+## Installing other Packages (Not required)
+If you want to install any additional packages, you can do so by opening a terminal window and type:
+~~~
+conda install -y package_name
+~~~
+{: .language-bash}
 
+You may need to install the required packages in this way,
+if you opted for installing Miniconda, instead of Anaconda.
+Miniconda is a lightweight version of Anaconda. If you install and use Miniconda
+you will also need to install the workshop packages manually in the following way:
 ~~~
 conda install -y numpy pandas matplotlib jupyter
 conda install -c conda-forge plotnine
 ~~~
 {: .language-bash}
 
+
 ## Launch a Jupyter notebook
 
 After installing either Anaconda or Miniconda and the workshop packages,