From 71ac570d93ce921e2b731f1f2283bfc9f91160ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Wed, 11 Dec 2024 19:50:51 -0800 Subject: [PATCH 1/2] DOC: refreshing some conda instructions, and updating link. --- 00_SETUP.md | 58 +++++++++++++++++++++++++---------------------------- 1 file changed, 27 insertions(+), 31 deletions(-) diff --git a/00_SETUP.md b/00_SETUP.md index 7cd696b..499fe13 100644 --- a/00_SETUP.md +++ b/00_SETUP.md @@ -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: @@ -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: @@ -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 @@ -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 @@ -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 @@ -116,15 +117,13 @@ 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 @@ -132,8 +131,7 @@ 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 @@ -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, From 4debe289167cc4a9667307812b24b5078e1a02e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Brigitta=20Sip=C5=91cz?= Date: Thu, 12 Dec 2024 10:55:18 -0800 Subject: [PATCH 2/2] DOC: using a more appropriate link describing markdown notebooks --- 00_SETUP.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/00_SETUP.md b/00_SETUP.md index 499fe13..f48eb81 100644 --- a/00_SETUP.md +++ b/00_SETUP.md @@ -149,7 +149,7 @@ 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/stable/). +The Jupyter notebooks in this repository are in [MyST-Markdown format](https://mystmd.org/guide/notebooks-with-markdown). 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.