Skip to content

Commit

Permalink
DOC: refreshing some conda instructions, and updating link.
Browse files Browse the repository at this point in the history
  • Loading branch information
bsipocz committed Dec 12, 2024
1 parent 0807deb commit 71ac570
Showing 1 changed file with 27 additions and 31 deletions.
58 changes: 27 additions & 31 deletions 00_SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,25 @@ These directions walk through installing miniconda, a lightweight distribution o

## 0. (Only for Windows) Install WSL

*This step is is only for Windows users and is adapted from [step 0 of the Astropy Workshop instructions](https://github.com/astropy/astropy-workshop/blob/main/00-Install_and_Setup/README.md#0-only-for-windows-install-wsl).*
If you are not using Windows, proceed to step 1.

*If you are using Windows, we now recommend using the Windows Subsystem for Linux (WSL) instead of using native Windows tools. WSL is now fully supported by Microsoft and tends to result in fewer install headaches, and lets you use tools that were developed for Linux seamlessly in Windows. Since installing WSL requires admin privileges, this approach is suitable if you already have WSL installed or have admin privileges. If neither of those is true, you may still have success using the Windows-native installation of Miniconda in step 1, but can also run and save all the workshop content via a web browser using the [Running on Sciserver instructions](https://github.com/NASA-NAVO/navo-workshop#running-on-sciserver).*
*This step is is only for Windows users and is adapted from [step 0 of the Astropy Workshop instructions](https://github.com/astropy/astropy-workshop/blob/main/00-Install_and_Setup/README.md#0-only-for-windows-install-wsl).*

If you are not using Windows, proceed to step 1.
*If you are using Windows, we now recommend using the Windows Subsystem for Linux (WSL) instead of using native Windows tools.
WSL is now fully supported by Microsoft and tends to result in fewer install headaches, and lets you use tools that were developed for Linux seamlessly in Windows.
Since installing WSL requires admin privileges, this approach is suitable if you already have WSL installed or have admin privileges.
If neither of those is true, you may still have success using the Windows-native installation of Miniconda in step 1, but can also run and save all the workshop content via a web browser using the [Running on Sciserver instructions](https://github.com/NASA-NAVO/navo-workshop#running-on-sciserver).*

If WSL is already installed with Ubuntu, proceed to step 1 and follow the instructions using WSL as if you were fully on Ubuntu Linux.

To install WSL, you should follow the instructions Microsoft provides here: https://docs.microsoft.com/en-us/windows/wsl/install. While you may choose an alternative Linux distribution from the default Ubuntu, the instructions below have been tested on Ubuntu, so unless you have a specific reason, we suggest you stick with the default. Once you reach the point in the instructions with a working Linux terminal prompt, you can proceed to step 1 of these instructions.
To install WSL, you should follow the instructions Microsoft provides here: https://docs.microsoft.com/en-us/windows/wsl/install.
While you may choose an alternative Linux distribution from the default Ubuntu, the instructions below have been tested on Ubuntu, so unless you have a specific reason, we suggest you stick with the default.
Once you reach the point in the instructions with a working Linux terminal prompt, you can proceed to step 1 of these instructions.

## 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.*
*Miniconda is a free minimal installer for conda 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 Miniconda already installed, you can skip to the next step.*

Check if Miniconda is already installed:

Expand All @@ -35,11 +37,10 @@ On Windows, you might also need

## 2. Update conda version

*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.*
*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.*

Open a terminal window and verify that conda is working:

Expand All @@ -55,8 +56,8 @@ then run the initialization if needed, in that same terminal window:

You should open a new terminal window after `conda init` is run.

It is advisable to update your conda to the latest version. We recommend a minimum
version of 23.10.0. Check your conda version with:
It is advisable to update your conda to the latest version.
We recommend a minimum version of 23.10.0. Check your conda version with:

% conda --version

Expand All @@ -77,7 +78,8 @@ At the prompt opened in the previous step, enter this command to see whether git
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:
If the output shows a git version, proceed to the next step.
Otherwise install git by entering the following command and following the prompts:

```console
conda install git
Expand All @@ -97,9 +99,8 @@ git clone https://github.com/NASA-NAVO/navo-workshop
*For this workshop, the python version and all needed packages are listed in the
[environment.yml](https://github.com/NASA-NAVO/navo-workshop/blob/main/environment.yml) file.*

Navigate to the workshop directory in the terminal. For example, if you installed
the navo-workshop directory in your home directory, you could type the
following:
Navigate to the workshop directory in the terminal.
For example, if you installed the navo-workshop directory in your home directory, you could type the following:

```console
cd navo-workshop
Expand All @@ -116,24 +117,21 @@ The creation of the environment can take some time to run.

## 6. Check Installation

The name of the new conda environment created above should be displayed next
to the terminal prompt:
The name of the new conda environment created above should be displayed next to the terminal prompt:

```console
(navo-env)
```

Run the `check_env.py` script to check the Python environment and some of the
required dependencies:
Run the `check_env.py` script to check the Python environment and some of the required dependencies:

```console
python check_env.py
```

## 7. Starting Jupyterlab

From the top-level directory of the repository, change directory to the
`content/` subdirectory:
From the top-level directory of the repository, change directory to the `content/` subdirectory:

```console
cd content
Expand All @@ -151,11 +149,9 @@ the notebooks.

## 8. Handling Notebooks in MyST-Markdown format

The Jupyter notebooks in this repository are in
[MyST-Markdown format](https://myst-nb.readthedocs.io/en/v0.13.2/use/markdown.html).
The [jupytext](https://jupytext.readthedocs.io/en/latest/index.html) package is
included in your `navo-env` environment to work with these notebooks. Note that
the `jupytext` package has to be installed before your Jupyterlab session starts.
The Jupyter notebooks in this repository are in [MyST-Markdown format](https://myst-nb.readthedocs.io/en/stable/).
The [jupytext](https://jupytext.readthedocs.io/en/latest/index.html) package is included in your `navo-env` environment to work with these notebooks.
Note that the `jupytext` package has to be installed before your Jupyterlab session starts.

To open one of these notebooks (in the `content/reference_notebooks` and the
`content/use_case_notebooks` subdirectories), in the Jupyterlab file panel,
Expand Down

0 comments on commit 71ac570

Please sign in to comment.