Merge pull request #217 from climbfuji/update_doc_envvars

release/public-v1: update documentation, update Externals.cfg

Externals.cfg

@@ -2,16 +2,14 @@
 schema_version = 1.0.0
 
 [model]
-# branch = release/public-v1
-hash = 5bea16b
+tag = ufs-v1.1.0
 protocol = git
 repo_url = https://github.com/ufs-community/ufs-weather-model/
 local_path = src/model
 required = True
 
 [cime]
-# branch = ufs-release-v1.1 
-hash = cac6a3e
+tag = ufs-v1.1.0
 protocol = git
 repo_url = https://github.com/ESMCI/cime.git
 local_path = cime
@@ -28,8 +26,7 @@ required = True
 # FV3GFS - this should be merged into the NOAA-EMC/fv3atm
 # repository so this extra repo is not needed
 [fv3gfs_interface]
-# branch = ufs-release-v1.1
-hash = 523f22e
+tag = ufs-v1.1.0
 protocol = git
 repo_url = https://github.com/ESCOMP/fv3gfs_interface.git
 local_path = src/model/FV3/cime

docs/UsersGuide/source/faq.rst

@@ -6,15 +6,15 @@ FAQ
 
 How can I set required environment variables?
 =============================================
-The best practice to set environment variables (``UFS_SCRATCH``, ``UFS_INPUT``,
-``UFS_DRIVER``, ``CIME_MODEL``, and ``PROJECT``) is
-to put them into the ``.bashrc`` (Bash shell) or ``.tcshrc`` (Tcsh shell) files.
-These files are executed when a user opens a new shell or logs in to the server
-(including compute nodes) so that their environment is set correctly. In platforms
-that are not preconfigured, the NCEPLIBS-provided shell script (``setenv_nceplibs.sh|.csh``)
-should be sourced in the same way.
+The best practice is to set environment variables (``UFS_SCRATCH``, ``UFS_INPUT``,
+``UFS_DRIVER``, ``CIME_MODEL``, and ``PROJECT``) in the user's enviroment. Some systems
+(in particular Stampede2) require to to export them in the ``.bashrc`` (Bash shell) or
+``.tcshrc`` (Tcsh shell) files for the batch jobs to function. These environment
+variables are then set automatically when a user opens a new shell or logs in to the server
+(including compute nodes). In platforms that are not preconfigured, the NCEPLIBS-provided
+shell script (``setenv_nceplibs.sh|.csh``) must be sourced in the same way.
 
-**BASH (edit ~/.bashrc):**
+**BASH:**
 
 .. code-block:: console
 
@@ -25,7 +25,7 @@ should be sourced in the same way.
  export CIME_MODEL=ufs
  source /path/to/nceplibs/bin/setenv_nceplibs.sh
 
-**BASH (edit ~/.tcshrc):**
+**TCSH:**
 
 .. code-block:: console
 
@@ -36,10 +36,6 @@ should be sourced in the same way.
  setenv CIME_MODEL ufs
  source /path/to/nceplibs/bin/setenv_nceplibs.csh
 
-.. note::
-
- The user might need to create the ``~/.bashrc`` or ``~/.tcshrc`` file.
-
 How can I see/check the steps in my workflow?
 =============================================
 

docs/UsersGuide/source/quickstart.rst

@@ -276,17 +276,18 @@ On `platforms that are not pre-configured <https://github.com/ufs-community/ufs/
  # CSH or TCSH shells
  source $NCEPLIBS_DIR/bin/setenv_nceplibs.csh
 
-The recommended best practice to set the ``$UFS_SCRATCH`` and
+The recommended best practice is to set the ``$UFS_SCRATCH`` and
 ``$UFS_INPUT`` environment variables and source the NCEPLIBS provided
-shell script ``setenv_nceplibs.sh|.csh`` is to add the above commands
-to a startup script such as ``$HOME/.bashrc`` (Bash shell) or
-``$HOME/.tcshrc`` (Tcsh shell). These files are executed automatically
-when you start a new shell so that you do not need to re-define them
-during each login.
+shell script ``setenv_nceplibs.sh|.csh`` in the user environment before
+creating the case and running the setup, build and submit steps.
 
 .. important::
- On some platforms (in particular Stampede2) this practice is **required** to ensure the
- environment variables are properly set on compute nodes accessed by the workflow.
+ On some platforms (in particular Stampede2) it is **required** to export
+ `UFS_INPUT`, `UFS_SCRATCH` and `NCEPLIBS_DIR` in the user's shell
+ startup scripts, such as ``$HOME/.bashrc`` (Bash shell) or
+ ``$HOME/.tcshrc`` (Tcsh shell). These environment variables are
+ then set automatically when you start a new shell or run a job through
+ the scheduler.
 
 Create a case
 ==============