From e8efae76758e5e2adbe81413d1321e139c31a1fc Mon Sep 17 00:00:00 2001
From: Andrew Annex <ama6fy@virginia.edu>
Date: Thu, 17 Jun 2021 10:11:37 -0400
Subject: [PATCH] Update readme to include conda env config vars option (#4515)

* Update readme to include conda config var option

First step for issue #4499

Updates readme step 7 of install to include steps for using `conda env
config vars` to set environment variables as option 2.

there are a few things to work out:

1. Is ISISTESTDATA actually required?
2. What about ALEDATA?
3. Update miniconda/anaconda version mentioned to a more recent release
4. Remove mentions of isis version < 4.2.0, as older readmes contain
   install directions
5. Verify I got the update command correct.
6. See why the markdown doesn't indent for options 1 and 2.

* Update README.md

removing direct mentions of ISIS 4.2.0 from env steps, added isis 5.0.0 readme link.

* remove direct mention of ISISTESTDATA from readme
---
 README.md | 63 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 48 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index ae6b3d21f7..70545977de 100644
--- a/README.md
+++ b/README.md
@@ -38,8 +38,8 @@ This installation guide is for ISIS users interested in installing ISIS (3.6.0)+
 1.  Download either the Anaconda or Miniconda installation script for your OS platform. Anaconda is a much larger distribtion of packages supporting scientific python, while Miniconda is a minimal installation and not as large: [Anaconda installer](https://www.anaconda.com/download), [Miniconda installer](https://conda.io/miniconda.html)
 2.  If you are running on some variant of Linux, open a terminal window in the directory where you downloaded the script, and run the following commands. In this example, we chose to do a full install of Anaconda, and our OS is Linux-based. Your file name may be different depending on your environment.
 
-        chmod +x Anaconda3-5.2.0-Linux-x86_64.sh
-        ./Anaconda3-5.2.0-Linux-x86_64.sh
+        chmod +x Anaconda3-5.3.0-Linux-x86_64.sh
+        ./Anaconda3-5.3.0-Linux-x86_64.sh
 
 
     This will start the Anaconda installer which will guide you through the installation process.
@@ -91,30 +91,63 @@ This installation guide is for ISIS users interested in installing ISIS (3.6.0)+
 
 7.  Finally, setup the environment variables:
 
-    To use the default values for: `$ISISROOT, $ISISDATA, $ISISTESTDATA`, run the ISIS variable initialization script with default arguments.
+    ISIS requires several environment variables to be set in order to run correctly. 
+    The variables include: ISISROOT and ISISDATA. 
 
-    To do this, for versions of ISIS 4.2.0 and earlier, use:
+    More information about the ISISDATA environment variable and the ISIS Data Area can be found [here]("#The-ISIS-Data-Area"). 
+    
+    The following steps are only valid for versions of ISIS after 4.2.0.   
+    For older versions of ISIS follow the instructions in [this readme file.](https://github.com/USGS-Astrogeology/ISIS3/blob/adf52de0a04b087411d53f3fe1c9218b06dff92e/README.md)
 
-        python $CONDA_PREFIX/scripts/isis3VarInit.py
+    There are two methods to configure the environment variables for ISIS:
 
-    For versions of ISIS after 4.2.0, use:
+    7.1 Using the provided isisVarInit.py script:
 
-        python $CONDA_PREFIX/scripts/isisVarInit.py
+      To use the default values for: `$ISISROOT` and `$ISISDATA`, run the ISIS variable initialization script with default arguments:
+  
+          python $CONDA_PREFIX/scripts/isisVarInit.py
+  
+      Executing this script with no arguments will result in $ISISROOT=$CONDA\_PREFIX and $ISISDATA=$CONDA\_PREFIX/data. The user can specify different directories for `$ISISDATA` using the optional value:
+  
+          python $CONDA_PREFIX/scripts/isisVarInit.py --data-dir=[path to data directory]  
+  
+      Now every time the isis environment is activated, $ISISROOT and $ISISDATA will be set to the values passed to isisVarInit.py. 
+      This does not happen retroactively, so re-activate the isis environment with one of the following commands:
+  
+          for Anaconda 3.4 and up - conda activate isis
+          prior to Anaconda 3.4 - source activate isis
 
-    Executing this script with no arguments will result in $ISISDATA=$CONDA\_PREFIX/data, and $ISISTESTDATA=$CONDA\_PREFIX/testdata. The user can specify different directories for both of these optional values:
+    7.2 Using `conda env config vars`
 
-    For ISIS 4.2.0 and earlier, use:
+      Conda has a built in method for configuring environment variables that are specific to a conda environment since version 4.8.
+      This version number applies only to the conda package, not to the version of miniconda or anaconda that was installed. 
 
-        python $CONDA_PREFIX/scripts/isis3VarInit.py --data-dir=[path to data directory]  --test-dir=[path to test data directory]
+      To determine if your version of conda is recent enough run:
 
-    For versions of ISIS after 4.2.0, use:
+          conda --version
 
-        python $CONDA_PREFIX/scripts/isisVarInit.py --data-dir=[path to data directory]  --test-dir=[path to test data directory]
+      If the version number is less than 4.8, update conda to a newer version by running:
+
+          conda update -n base conda 
+
+      The version number should now be greater than 4.8. 
+
+      To use the built in environment variable configuration feature, first activate the environment by first running:
+
+          conda activate isis 
+
+      After activation, the environment variables can be set using the syntax: `conda config vars set KEY=VALUE`.
+      To set all the environment variables ISIS requires, run the following command, updating the path to `ISISDATA` as needed:
+
+          conda env config vars set ISISROOT=$CONDA_PREFIX ISISDATA=[path to data directory] 
+      
+      To make these changes take effect, re-activate the isis environment by running:
+
+          conda activate isis
+
+      The environment variables are now set and ISIS is ready for use every time the isis environment is activated.
 
-    More information about the ISISDATA environment variable and the ISIS Data Area can be found [here]("#The-ISIS-Data-Area"). Now everytime the isis environment is activated, $ISISROOT, $ISISDATA, and $ISISTESTDATA will be set to the values passed to isisVarInit.py. This does not happen retroactively, so re-activate the isis envionment with one of the following commands:
 
-        for Anaconda 3.4 and up - conda activate isis
-        prior to Anaconda 3.4 - source activate isis
 
 ### Installation with Docker
 The ISIS production Dockerfile automates the conda installation process above.
-- 
GitLab