Add FAQ page and a caution with using reserved variables (NOAA-EMC#2898)

This PR: - Creates a standalone page for FAQ and Common issues - Adds a block of caution on using variables in a users' `bashrc` Fixes: NOAA-EMC#2850
NOAA-EPIC · Sep 9, 2024 · 0953c0f · 0953c0f
1 parent 49f697a
commit 0953c0f
Show file tree

Hide file tree

Showing 3 changed files with 11 additions and 4 deletions.
diff --git a/docs/source/errors_faq.rst b/docs/source/errors_faq.rst
@@ -2,6 +2,14 @@
 Common Errors Known Issues
 ==========================
 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Error: Reserved Variables Causing Workflow Issues
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Several variables are reserved in the workflow and should not be used as environment variables in your shell. Some of the common ones include (but are not limited to):
+``HOMEgfs``, ``machine``, ``ROTDIR``, ``COMROT``, ``COMROOT``, ``COMOUT``, ``COMIN``, ``STMP``, ``PTMP``, ``DATAROOT``, ``DATA``, ``ACCOUNT``, ``PDY``, ``cyc``, ``RUN``, etc.
+If you are using any of these variables in your shell, you may encounter unexpected behavior in the workflow.
+
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Error: "ImportError" message when running setup script
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -42,4 +50,3 @@ Issue: Directory name change for EnKF folder in ROTDIR
 **Issue:** The EnKF ROTDIR folders were renamed during the GFS v15 development process to remove the period between "enkf" and "gdas": enkf.gdas.$PDY → enkfgdas.$PDY
 
 **Fix:** Older tarballs on HPSS will have the older directory name with the period between 'enkf' and 'gdas'. Make sure to rename folder to 'enkfgdas.$PDY' after obtaining. Only an issue for the initial cycle.
-
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,6 +1,6 @@
 
 ###############
-Global Workflow 
+Global Workflow
 ###############
 
 **Global-workflow** is the end-to-end workflow designed to run global configurations of medium range weather forecasting for the UFS weather model. It supports both development and operational implementations. In its current format it supports the Global Forecast System (GFS) and the Global Ensemble Forecast System (GEFS) configurations
@@ -31,7 +31,7 @@ GitHub updates: Users should adjust their "Watch" settings for this repo so they
 Table of Contents
 =================
 
-.. toctree:: 
+.. toctree::
    :numbered:
    :maxdepth: 3
 
@@ -42,3 +42,4 @@ Table of Contents
    output.rst
    run.rst
    noaa_csp.rst
+   errors_faq.rst
diff --git a/docs/source/run.rst b/docs/source/run.rst
@@ -13,4 +13,3 @@ Here we will show how you can run an experiment using the Global Workflow. The G
    start.rst
    monitor_rocoto.rst
    view.rst
-   errors_faq.rst