Skip to content

Commit

Permalink
polish installation instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@stargaser
stargaser committed May 24, 2021
1 parent 21a7800 commit ad11e34
Show file tree
Hide file tree
Showing 2 changed files with 105 additions and 56 deletions.
139 changes: 94 additions & 45 deletions 00-Install_and_Setup/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,13 @@
# Getting Started with Python and Anaconda
# Setup and Installation Instructions for Workshop

To run all the workshop notebooks on your own computer, please be sure your machine is
configured with the packages in the
[installation check file](https://github.com/astropy/astropy-workshop/blob/main/00-Install_and_Setup/).
These packages are the ones we use to verify that the notebooks are working as expected.

These instructions describe setup using `git` and `Miniconda`. It is not strictly necessary
to use either of these.

Please come to the workshop with a laptop already configured as described below.
If you have any problems with any of these steps, please check if your problem has
already been reported at [the issue tracker](https://github.com/astropy/astropy-workshop/issues/). If not,
[ask your question in the issue tracker](https://github.com/astropy/astropy-workshop/issues/new?assignees=&labels=workshop-question&template=question-from-workshop-participant.md&title=%5BQuestion%5D+Summarize+your+question+here).
Expand All @@ -9,38 +16,76 @@ For the commands shown, `%` (and anything to the left of it) represents the
terminal prompt. You do not need to copy it; instead only copy the command to the
right of `%`.

## 1. Clone This Repository

Download the workshop folder using
[git](https://help.github.com/articles/set-up-git/):

% git clone https://github.com/astropy/astropy-workshop.git

If you don't have git installed, you can download the ZIP file by pressing the
green *Clone or download* button at
https://github.com/astropy/astropy-workshop and selecting *Download ZIP*.
However, this option is not recommended because it impedes the ability to
update your copy of the repository if updates are made.

## 2. Install Miniconda (if needed)
## 1. Install Miniconda (if needed)

*Miniconda is a free minimal installer for conda. It is a small, bootstrap
version of Anaconda that includes only conda, Python, the packages they depend
on, and a small number of other useful packages, including pip, zlib and a few
others. Note, though, that if you have either Miniconda or the full Anaconda
already installed, you can skip to the next step.*

Check if Miniconda is already installed.
In a terminal window, check if Miniconda is already installed.

% conda info

If Miniconda is not already installed, follow these instructions for your
operating system: https://docs.conda.io/en/latest/miniconda.html
operating system: https://conda.io/projects/conda/en/latest/user-guide/install/index.html.
Please be sure to install a **64-bit version** of Miniconda to ensure all packages work correctly.


On Windows, you might also need
[additional compilers](https://github.com/conda/conda-build/wiki/Windows-Compilers).

## 3. Create a conda environment for the workshop

## 2. Open the conda command prompt

*Miniconda includes an environment manager called conda. Environments
allow you to have multiple sets of Python packages installed at the same
time, making reproducibility and upgrades easier. You can create,
export, list, remove, and update environments that have different versions of
Python and/or packages installed in them. For this workshop, we will configure the
environment using the conda command prompt.*

On MacOS or Linux, open a terminal window and verify that conda is working:

% conda info

If you are having trouble, check your shell in a terminal window:

% echo $SHELL

then run the initialization if needed, in that same terminal window:

% conda init $SHELL

On Windows, open the `Anaconda Prompt` terminal app.

*(An alternative to using conda is [mamba](https://github.com/mamba-org/mamba) which is
a reimplementation of the conda package manager in C++.)*

## 3. Install git (if needed)

At the prompt opened in the previous step, enter this command to see whether git is already installed and accessible to this shell:

% git --version

If the output shows a git version, proceed to the next step. Otherwise install git by entering the following command and following the prompts:

% conda install git

## 5. Clone this repository, or download a ZIP file

If using `git`, clone the workshop repository using
[git](https://help.github.com/articles/set-up-git/):

% git clone https://github.com/astropy/astropy-workshop.git

If you elect not to use `git`, you can download the ZIP file by opening the
green *Code* button at
https://github.com/astropy/astropy-workshop and selecting *Download ZIP*.

## 6. Create a conda environment for the workshop

*Miniconda includes an environment manager called conda. Environments
allow you to have multiple sets of Python packages installed at the same
Expand All @@ -52,12 +97,7 @@ Python and/or packages installed in them.*
The python version and all needed packages, including astropy, are listed in the
[environment.yml](https://github.com/astropy/astropy-workshop/blob/main/00-Install_and_Setup/environment.yml) file.

On Mac or Linux, open your terminal and verify your shell environment:

% echo $SHELL

If the output text does not contain `bash`, switch to the bash shell before
being able to run anything related to conda.
On Mac or Linux, open your terminal.

On Windows, open the `Anaconda Prompt` terminal app.

Expand All @@ -75,74 +115,83 @@ On Windows:

And finally, on any platform, to install and activate the astropy-workshop environment, type:

% conda env create -n astropy-workshop --file environment.yml
% conda activate astropy-workshop
% conda env create --file environment.yml
% conda activate astropy-env

Note, you will need conda version 4.6 and later. If you need to update your version use `conda update conda`.

## 4. Check Installation
## 7. Check Installation

The name of the new conda environment created above should be displayed next
to the terminal prompt: `(astropy-workshop) %`
to the terminal prompt: `(astropy-env) %`

Run the `check_env.py` script to check the Python environment and some of the
required dependencies:
In the terminal you used in the preceding step, inside the `astropy-workshop/00_Install_and_Setup/`
directory, run the `check_env.py` script to
check the Python environment and some of the required dependencies:

(astropy-workshop) % python check_env.py
(astropy-env) % python check_env.py

If the script reports that some of the versions do not match, check first
whether the package was installed using conda or pip, then update accordingly.
The example below a fake package called `packagename`; replace it with the
actual package that you need to update.

(astropy-workshop) % conda list packagename
(astropy-env) % conda list packagename

If it was installed with conda, you will see (the channel column might or
might not be populated):

# packages in environment at .../miniconda/envs/astropy-workshop:
# packages in environment at .../miniconda/envs/astropy-env:
#
# Name Version Build Channel
packagename X.Y.Z py37hf484d3e_1000

Otherwise, if it was installed with pip, you will see the channel stating the
name `pypi`:

# packages in environment at .../miniconda/envs/astropy-workshop:
# packages in environment at .../miniconda/envs/astropy-env:
#
# Name Version Build Channel
packagename X.Y.Z pypi_0 pypi

To update the reported package with conda:

(astropy-workshop) % conda update packagename
(astropy-env) % conda update packagename

Otherwise, to update with pip:

(astropy-workshop) % pip install packagename --upgrade
(astropy-env) % pip install packagename --upgrade

The exception to this is if the `astroquery` package is reported as
out-of-date, always update to its pre-release version with pip:

(astropy-workshop) % pip install astroquery --pre --upgrade
(astropy-env) % pip install astroquery --pre --upgrade

## 5. Check Jupyter Notebook
## 8. Starting Jupyter Notebook

In the conda environment created above, go into the directory
of one of the chapters with notebooks (files ending with `.ipynb`)
and start Jupyter notebook:
In the terminal window you used with the the conda environment created above,
change directory to the top level `astropy_workshop` directory.

(astropy-workshop) % jupyter notebook
(astropy-env) % cd ..

Make sure the current directory in your terminal contains all the numbered notebook
directories. Then start Jupyter notebook:

(astropy-env) % jupyter notebook

If successful, your browser would open a new page/tab pointing to
`localhost` and show you a listing of the directory.
Click on a notebook and wait for it to launch. On the top right corner,
`localhost` and show you a listing of the directory including all the numbered
notebook subdirectories.

Click into one of the notebook directories such as `02-PythonIntro`.
Double-click on a notebook such as `01. Numbers, String, and Lists.ipynb`
and wait for it to launch. On the top right corner,
if you see a blue "Kernel Ready" message appear and disappear,
then all is well. However, if you see a red "Kernel Error," click on it
and scroll down to see the error message. If it says `FileNotFoundError`,
shut down the notebook server on your terminal and run this command:

(astropy-workshop) % python -m ipykernel install --user
(astropy-env) % python -m ipykernel install --user

Now, try run `jupyter notebook` again as above, and the "Kernel Error"
should be gone. Just to be sure, run the first cell (usually an `import`)
Expand Down
22 changes: 11 additions & 11 deletions 00-Install_and_Setup/UPDATING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ directory you had.

## 2. Double-checking your Conda environment

Assuming you properly installed your astropy-workshop conda environment, you
Assuming you properly installed your astropy-env conda environment, you
should be able to:

a. activate that conda environment, and
Expand All @@ -55,22 +55,22 @@ c. check to see if your environment still meets the requirements.

Let's do that now. Start by activating the conda environment:

% conda activate astropy-workshop
% conda activate astropy-env

You will notice a change in your prompt; e.g., `(astropy-workshop) %`.
You will notice a change in your prompt; e.g., `(astropy-env) %`.
Then, switch to the directory containing the installer by doing the following.

On a Mac/Linux (your directory path may be different):

(astropy-workshop) % cd astropy-workshop/00-Install_and_Setup/
(astropy-env) % cd astropy-workshop/00-Install_and_Setup/

On Windows (your directory path may be different):

(astropy-workshop) % cd astropy-workshop\00-Install_and_Setup\
(astropy-env) % cd astropy-workshop\00-Install_and_Setup\

Next, we check if the environment is still up to date:

(astropy-workshop) % python check_env.py
(astropy-env) % python check_env.py

If this check reports a problem with a package, see what to do below.

Expand All @@ -80,23 +80,23 @@ If the `check_env.py` script reports that some package called `packagename`
is not of a recent enough build, we need to check where the package came from
(replace `packagename` with the real package name):

(astropy-workshop) % conda list packagename
(astropy-env) % conda list packagename

If the "Build" of the package does *NOT* say `pypi`, you can then update the
package using:

(astropy-workshop) % conda update packagename
(astropy-env) % conda update packagename

If the package was installed from PyPI with pip, you can update it to the
latest PyPI release using:

(astropy-workshop) % pip install packagename --upgrade
(astropy-env) % pip install packagename --upgrade

If you know you need the pre-release version from PyPI (e.g., `astroquery`),
use:

(astropy-workshop) % pip install packagename --pre --upgrade
(astropy-env) % pip install packagename --pre --upgrade

Once you have performed the updates, check your installation again using:

(astropy-workshop) % python check_env.py
(astropy-env) % python check_env.py

0 comments on commit ad11e34

Please sign in to comment.