Merging in unidata_18.1.1 documentation updates into unidata_18.2.1

docs/cave/d2d-gridded-models.md

@@ -2,6 +2,14 @@
 
 The Volume Browser provides access to numerical models, other gridded data, sounding data, and selected point data sources, such as RAOB, METAR, and Profiler. Through the Browser interface, you can choose the data source(s), field(s), plane(s), and point(s), and generate a customized list of model graphics or images for display.
 
+The Volume Browser can be accessed from either the **Tools** (alphabetically organized) or **Models** (first option) menus.
+
+![menuBar](../images/menuBar.png)
+
+---
+
+## Visual Overview
+
 The Volume Browser window is divided into four areas:
 
 ![](../images/volumeBrowserLabeled.png)

docs/dev/awips-development-environment.md

@@ -1,8 +1,10 @@
 # AWIPS Development Environment (ADE)
 
-Quick instructions on how to download the latest source code and run CAVE from Eclipse.
+Detailed instructions on how to download the latest source code and run CAVE from Eclipse.
 
-> **Note**: It is important to keep in mind these instructions are intended for a system that is specifically used for developing AWIPS.  It should not be used in conjunction with installed production versions of AWIPS.
+!!! note  "It is important to keep in mind these instructions are intended for a system that is specifically used for developing AWIPS.  It should not be used in conjunction with installed production versions of AWIPS."
+
+!!! note "The following *yum* commands listed in these instructions may need to be run as the *root* user, but the rest of the commands should be run as the local user."
 
 ## 1. Remove AWIPS Instances
 
@@ -26,6 +28,9 @@ Remove the awips2 directory:
 ## 2. Set Up AWIPS Repo
 
 Create a repo file named `/etc/yum.repos.d/awips2.repo`, and set the contents to the following:
+
+    sudo vi /etc/yum.repos.d/awips2.repo
+
 <pre>
 [awips2repo]
 name=AWIPS II Repository
@@ -35,7 +40,8 @@ protect=0
 gpgcheck=0
 proxy=_none_
 </pre>
->**Note**: This file may already exist if AWIPS had been previously installed on the machine, so make sure to edit the baseurl.
+
+!!! note "This file may already exist if AWIPS had been previously installed on the machine, so make sure to edit the baseurl."
         
 ---
 
@@ -46,6 +52,8 @@ Install the AWIPS Development Environment (ADE) using yum.  This will install Ec
     yum clean all
     yum groupinstall awips2-ade
 
+!!! note "Check the libGLU package is installed by running `rpm -qa | grep mesa-libGLU`.  If nothing is returned, install the package via: `yum install mesa-libGLU`."
+
 ---
 
 ## 4. Download the Source Code
@@ -57,71 +65,106 @@ If it's not already installed, install git:
 Next clone all of the required repositories for AWIPS:
     
     git clone https://github.com/Unidata/awips2.git
+    git clone https://github.com/Unidata/awips2-cimss.git
     git clone https://github.com/Unidata/awips2-core.git
     git clone https://github.com/Unidata/awips2-core-foss.git
+    git clone https://github.com/Unidata/awips2-drawing.git
     git clone https://github.com/Unidata/awips2-foss.git
+    git clone https://github.com/Unidata/awips2-goesr.git
+    git clone https://github.com/Unidata/awips2-gsd.git
     git clone https://github.com/Unidata/awips2-ncep.git
     git clone https://github.com/Unidata/awips2-nws.git
-    git clone https://github.com/Unidata/awips2-gsd.git
-    git clone https://github.com/Unidata/awips2-drawing.git
+    
+!!! note "Make sure to run `git checkout` in each repo if you'd wish to develop from a branch different from the default.  It's best to do this before importing the repos into eclipse."
 
 ---
 
-## 5. Set Up Eclipse
+## 5. Configure Eclipse
 
-Open eclipse by running: `/awips2/eclipse/eclipse.sh`
+Open eclipse by running: `/awips2/eclipse/eclipse`
+
+It is fine to choose the default workspace upon starting up.
+
+### Set Preferences
 
 Verify or make the following changes to set up eclipse for AWIPS development:
 
-* Preferences > Java 
+1. Window > Preferences > Java > Installed JREs
     
-    Set to **/awips2/java**
+     * Set to **/awips2/java**
 
-* Preferences > PyDev > Python Interpreter
+1. Window > Preferences > PyDev > Interpreters > Python Interpreter
 
-    Set to **/awips2/python/bin/python**
+      * Set to **/awips2/python/bin/python**
     
-* There might be some unresolved errors.  These should be made to warnings instead.
+        > Note: Add all paths to the SYSTEM pythonpath if prompted
     
-    Preferences > Java > Compiler > Building > **Circular Dependencies** > Change to Warning
-    Preferences > Plug-in Development > API Baselines > **Missing API Baseline** > Change to Warning
+1. There might be some unresolved errors.  These should be made to warnings instead.
 
-* **Turn off automatic building** (you will turn this back on after importing the repos)
+      * Window > Preferences > Java > Compiler > Building > Build path Problems > **Circular Dependencies** > Change to Warning
+      * Window > Preferences > Plug-in Development > API Baselines > **Missing API Baseline** > Change to Warning
     
-    Project > Uncheck "Build Automatically"
+1. **Turn off automatic building** (you will turn this back on after importing the repos)
     
-* File > Import > General > Existing Projects Into Workspace
+      * Project > Uncheck "Build Automatically"
 
-    Import all of the git cloned project folders **EXCEPT** for the main (first) **github.com/Unidata/awips2.git** directory (which should be **~/awips2**).  
-    Select **awips2-core**, **awips2-core-foss**, **awips2-foss**, **awips2-ncep**, etc. > Select All Projects > Finish 
+### Importing Git Repos
 
-    You'll want to import **~/awips2** in two parts to ensure a clean and error-free Eclipse build:
+All of the git repos that were [cloned in the previous step](#4-download-the-source-code) will need to be imported into Eclipse.  **But, be aware the `awips2` repo is done last,** because it requires different steps.
 
-    1. Import **awips2/cave** > Select All Projects > Finish
-    2. Import **awips2/edexOsgi** > Select All Projects > Finish
+1. File > Import > Git > Projects from Git > **Next**
+  ![git import](../images/gitImport1.png)
   
-* Project > Clean
+1. Continue with the default selection, Existing local repository > **Add..** > add each of the git repos (for example `.../awips2-core`) > check the checkbox > **Finish**
+  ![add git repo](../images/gitImport2.png)
   
-    Clean the build and ensure no errors are reported.  
+1. Then for each of the repos (except awips2 right now):
+Select the repo name > **Next** > Continue with default selection (Working Tree) > **Next** > Continue with default selections (all choices selected) > **Finish**
+  ![finish import](../images/gitImport3.png)
   
-* Turn automatic building back on
+1. Finally, for `awips2` repo, follow all the above steps except in the Working Tree, only select:
+    * *cave* > **Next** > **Finish**
+      ![importCave](../images/gitImportCave.png)
+    * *edexOsgi* > **Next** > **Finish**
+      ![importEdexOsgi](../images/gitImportEdexOsgi.png)
 
-    Project > Check "Build Automatically"
+### Final Setup
+
+1. Project > Clean > **OK**
+     * Use default selections: *Clean all projects*, *Start a build immediately*, *Build the entire workspace*
+     * Clean the build and ensure no errors are reported.  
+      ![cleanEclipse](../images/cleanEclipse.png)
+    
+1. Turn automatic building back on
+      * Project > Check "Build Automatically"
     
 ---
 
 ## 6. Run CAVE
     
-Launch CAVE from eclipse using **com.raytheon.viz.product.awips/developer.product**.
+!!! note "CAVE can be ran from eclipse by using the *com.raytheon.viz.product.awips/developer.product*"
 
-Double-click the **developer.product** file to open the Product View in Eclipse.  Select **Overview** > **Synchronize** and then right-click the file in the left-side package explorer:
+Double-click the **developer.product** file to open the Project Explorer in Eclipse.  Select **Overview** > **Synchronize**
 
-Select **Run As** > **Eclipse Application** to launch CAVE in the development environment. 
+![synchronize developer product](../images/synchronizeDeveloperProduct.png)
 
-Select **Debug** > **Eclipse Application** to launch CAVE in in debug mode. 
+Use the **Project Explorer** on the left-hand side of eclipse to run CAVE as a [Java application](#run-application) or in [Debug mode](#debug-application):
+
+### Run Application
+
+Select **Run As** > **Eclipse Application**
+
+![run application](../images/runApplication.png)
+
+### Debug Application
+
+Select **Debug** > **Eclipse Application**
+ 
+![debug application](../images/debugApplication.png)
 
 ---
 
 ## Troubleshooting
 
 * If you are getting a lot of errors, try changing your Java Compiler to 1.7, build the project, then change back to 1.8 and rebuild.
+    * **Window** > Preferences > Java > Compiler > **Compiler compliance level** setting

docs/install/common-problems.md

@@ -1,5 +1,42 @@
 # Common Problems
 
+## General Troubleshooting
+
+Along with closing and restarting CAVE, one of the first things user's should turn to for resolving weird or unexpected behavior is *flushing their local cache*.  The cache lives in a folder called **caveData**, so this process is also referred to as removing or deleting caveData.
+
+### Linux
+
+For Linux users, the easiest way is to open a new terminal and run the following command:
+
+    rm -rf ~/caveData 
+
+### Windows 
+
+For Windows users, simply delete the caveData folder in your home user directory:
+
+![Windows Remove caveData](../images/windowsRemoveCavedata.png)
+
+### Mac
+
+For Mac users, the easiest way is to open a new terminal and run the following command:
+
+    rm -rf ~/Library/caveData
+
+
+---
+
+## Remotely Connecting to CAVE
+
+Since the pandemic began, many users have asked if they can use X11 forwarding or ssh tunneling to remotely connect to CAVE machines.  **This is not recommended or supported**, and CAVE crashes in many different ways and expresses strange behavior as well.
+
+We highly recommend you [download the appropriate CAVE installer](install-cave.md) on your local machine, if that is an option.
+
+If that is not an option, then the only remote access we recommend is using some type of VNC.
+[**RealVNC**](https://www.realvnc.com/en/) and [**nomachine**](https://www.nomachine.com) are two options that are in use with positive outcomes.  [**UltraVNC**](https://www.uvnc.com) may be another option, but may have quite a delay.  There *may* also be other free or paid software available that we are not aware of.
+!!! warning "It is likely that any VNC option you choose will also require some software or configuration to be set on the remote machine, and this will likely require administrative privileges."
+
+---
+
 ## Windows CAVE Start Up Error
 
 One common error some users are seeing manifests itself just after selecting an EDEX server to connect to.  The following error dialogs may show up:
@@ -38,3 +75,26 @@ These errors are actually happening because the Windows machine is using IPv6, w
 **7. Restart CAVE.**
 
 ---
+
+## Products Not Loading Properly in Windows
+
+If the [Windows installation](install-cave.md#download-and-installation-instructions_2) was not completed properly, it is possible to see incorrect behavior when loading certain products.  These are derived products which use the local machine to create and render the data.  This creation is dependent upon python and its required packages working correctly.
+
+The dataset will be available in the menus and product browser, but when loaded, no data is drawn on the editor, but an entry is added to the legend.
+![failed load](../images/failedJepMetarLoad.png)
+
+You may see an error that mentions the python package, **jep**.
+
+Known datasets this can affect (this is not a comprehensive list):
+
+  - Model Winds
+  - Metars Winds
+  - METAR Station Plot
+  - GFS Precip Type
+
+To correct this issue:
+
+  - Uninstall all related software (C++ Build Tools, Miniconda, Python, CAVE, pip, numpy, jep, etc)
+  - Redo all necessary [installation instructions in **steps 1 through 6**](install-cave.md#download-and-installation-instructions_2)
+
+---

docs/install/install-cave.md

@@ -8,13 +8,18 @@ CAVE is the **C**ommon **A**WIPS **V**isualization **E**nvironment that is used
 
 Regardless of what Operating System CAVE is running on, these general requirements are recommended in order for CAVE to perform optimally:
 
+- Local machine
+
+    !!! error "Running CAVE via X11 forwarding or ssh tunneling is **not** supported. Using a [VNC connection is the only remote option](common-problems.md#remotely-connecting-to-cave), and may result in worse performance than running locally."
+  
 - Java 1.8
 - OpenGL 2.0 Compatible Devices
 - At least 4GB RAM
 - At least 2GB Disk Space for Caching
 - NVIDIA Graphics Card
 - [Latest NVIDIA Driver](http://www.nvidia.com/Download/index.aspx?lang=en-us)
-> Note: While other graphics cards *may* work, NVIDIA Quadro graphics card is recommended for full visualization capability
+
+    !!! warning "While other graphics cards *may* work, NVIDIA Quadro graphics card is recommended for full visualization capability"
 
 ---
 
@@ -46,7 +51,7 @@ To run CAVE either:
 For Windows, Unidata offers two installation options: a [**Linux Virtual Machine**](#method-1-linux-virtual-machine), or a [**Direct Windows Installation**](#method-2-direct-windows-install).
 
 Currently, the [virtual machine (VM)](#method-1-linux-virtual-machine) is the recommended form of install for those who do not have administrative priviledges on the machine, or beginners who want a simpler installation process.  
-> Note: At the moment, the VM option may not render all products in CAVE (ex. RGB composites of satellite imagery)
+!!! warning "At the moment, the VM option may not render all products in CAVE (ex. RGB composites of satellite imagery)"
 
 The [direct installation method](#method-2-direct-windows-install) is recommended for those who have administrative priviledges and a little bit of experience installing more software.
 
@@ -79,16 +84,16 @@ Once inside the VM, to run CAVE either:
 ### Method 2: Direct Windows Install
 
 This method is recommended for personal use and requires Administrative priviledges.  It should enable full CAVE capability, but it is a bit lengthy and might take about 20 minutes or so to complete.  
-For additional assistance we have created an [**installation video**](https://www.youtube.com/watch?v=02etW-PuZZ8) that walks through the steps below.
+For additional assistance we have created an [**installation video**](https://youtu.be/QAuBSsSp9Ak) that walks through the steps below.
 
-> Note: It is important to use the exact versions of software that we link to or specify in our instructions.  Deviations may cause installation problems or failures.
+!!! note "It is important to use the exact versions of software that we link to or specify in our instructions.  Deviations may cause installation problems or failures."
 
 #### System Requirements
 
 - 64-bit Miniconda3 (Python3.7 - 4.8.2)
 - Python3 (comes with Miniconda installation)
 - 64-bit Java JDK 1.8 (1.8_181)
-- 64-bit Visual C++ Build Tools 2015 Update 3 (14.1)
+- 64-bit Visual C++ Build Tools 2015 and 2019
 - Numpy (1.15.1)
 - Jep (3.8.2)
 - User Variable PATH must have miniconda3 location
@@ -109,17 +114,26 @@ For additional assistance we have created an [**installation video**](https://ww
     - User Variables: **PYTHONPATH** and **PYTHONHOME**
     - System Variable: **JAVA_HOME**
     ![Env Vars](../images/envVars.png)
-    > Note: If PYTHONHOME is not set, the **gridslice** Python module will not be installed or available
-4. [Download and install 64-bit Microsoft Visual Studio C++ Build Tools](https://my.visualstudio.com/Downloads?q=build%20tools%20c++%203&wt.mc_id=o~msft~vscom~older-downloads)
+    
+        !!! warning "If PYTHONHOME is not set, the **gridslice** Python module will not be installed or available"
+      
+4. [Download and install 64-bit Microsoft Visual Studio C++ Build Tools](https://my.visualstudio.com/Downloads?q=Build%20Tools%20for%20Visual%20Studio%202019%20%28version%2016.9%29&pgroup=)
     - To access the page linked above you will need a Microsoft account
-    - Download 64-bit **Visual C++ Build Tools 2015 Update 3**
-    - When running the installer, choose the **Default** Installation
+    - Download the executable for **Build Tools for Visual Studio 2019 (version 16.9)**
+    - Allow it to run some pre-installations
+    - The installer will pop up as shown below.  Make sure to select the **C++ build tools** (upper left), and then view the **Installation details** on the right
+      - Scroll down and check the **MSVC v140 - VS 2015 C++ build tools**
+    ![buildToolsInstall](../images/buildToolsInstall.png)
 5. Install dependent Python packages
-    - Open a terminal by typing "cmd" into the start bar and hitting enter
-    - Run the following command: `pip install numpy==1.15.1 jep==3.8.2`
+    - Once the installer has finished, close the installer. Another window is present and there is an option to **launch** a command terminal
+    ![launch terminal](../images/buildToolsLaunchTerm.png)
+    - Click that and run the following:
+        - `pip install numpy==1.15.1`
+        - `pip install jep==3.8.2`
+        !!! note "These must be run as two separate commands, as stated above for all derived parameters to display properly."
 6. Download and install: [**awips-cave.msi** <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/awips-cave.msi)
     - In addition to the application directory, the MSI installer will attempt to copy the [*gridslice*](https://github.com/Unidata/gridslice) shared library to `$PYTHONHOME/Dlls/`.  If the `$PYTHONHOME` environmental variable is not defined *gridslice* will not be installed.  You can check to see if it was installed in the Dlls directory after you have completed steps 1-3.
-    > Note: CAVE will still run without gridslice, but certain bundles which use derived parameters, such as [**isentropic analysis**](../images/screenCapture-2016.04.04.13.41.26-20160404_000000.png), will not load.
+    !!! note "CAVE will still run without gridslice, but certain bundles which use derived parameters, such as [**isentropic analysis**](../images/screenCapture-2016.04.04.13.41.26-20160404_000000.png), will not load."
 
 #### Run CAVE
 
@@ -137,7 +151,7 @@ To run CAVE, either:
 - Will need admin privileges to install python package
 - NVIDIA Graphics card is recommended, some Intel Graphics cards will working
 
-> Note: Most AMD graphics cards are not supported
+    !!! warning "Most AMD graphics cards are not supported"
 
 ### Download and Installation Instructions
 1. Download and install: [**awips-cave.dmg** <i class="fa fa-download"></i>](https://www.unidata.ucar.edu/downloads/awips2/awips-cave.dmg)
@@ -165,7 +179,8 @@ To run CAVE, either:
     - This will launch the installer:
 
         ![Python pkg install](../images/macPythonInstall.png)
-> Note: The awips-python.pkg is not necessarily required, and CAVE will still run without it, but any derived data such as barbs, arrows, and various grid products will not render without having **jep** installed (it is assumed to be in /Library/Python/2.7/site-packages/jep/)
+        
+        !!! note "The awips-python.pkg is not necessarily required, and CAVE will still run without it, but any derived data such as barbs, arrows, and various grid products will not render without having **jep** installed (it is assumed to be in /Library/Python/2.7/site-packages/jep/)"
 
 ### Run CAVE