Update installation guides

Author: ashao

doc/index.rst

@@ -12,8 +12,8 @@
 
    overview
    installation_instructions/basic
-   installation_instructions/install_notes
    installation_instructions/platform
+   installation_instructions/troubleshooting/troubleshooting
    contributing
    smartsim_zoo
 

doc/installation_instructions/basic.rst

@@ -4,7 +4,9 @@
 Basic Installation
 ******************
 
-The following will show how to install both SmartSim and SmartRedis.
+The following instructions serve as a guide for installing both SmartSim and
+SmartRedis. SmartSim, despite being a Python-library, has a second build
+step for Redis and RedisAI. Please follow these instructions carefully.
 
 .. note::
 
@@ -30,30 +32,26 @@ The base prerequisites to install SmartSim and SmartRedis wtih CPU-only support
 
 .. note::
 
-  GCC 9, 11-13 is recommended (here are known issues compiling with GCC 10). For
-  CUDA 11.8, GCC 9 or 11 must be used.
-
-.. warning::
-
-  Apple Clang 15 seems to have issues on MacOS with Apple Silicon. Please modify
-  your path to ensure that a version of GCC installed by brew has priority. Note
-  this seems to be hardcoded to `gcc` and `g++` in the Redis build so ensure that
-  `which gcc g++` do not point to Apple Clang.
-
+  GCC is recommended to build the backends for SmartSim. CUDA 11.8 requires GCC
+  9 or 11, CUDA 12 requires GCC 11 or higher. SmartRedis can be compiled with
+  GCC, Intel, Cray, and Nvidia compilers.
 
 ML Library Support
 ==================
 
-We currently support both Nvidia and AMD GPUs when using RedisAI for GPU inference. The support
-for these GPUs often depends on the version of the CUDA or ROCm stack that is availble on your
-machine. In _most_ cases, the versions backwards compatible. If you encounter problems, please
-contact us and we can build the backend libraries for your desired version of CUDA and ROCm.
+We currently support both Nvidia and AMD GPUs when using RedisAI for GPU
+inference. The support for these GPUs often depends on the version of the CUDA
+or ROCm stack that is availble on your machine. In _most_ cases, the versions of
+the ML frameworks are backwards compatible. If you encounter problems, please
+contact us and we can build the backend libraries for your desired version of
+CUDA and ROCm.
 
 CPU backends are provided for Apple (both Intel and Apple Silicon) and Linux (x86_64).
 
-Be sure to reference the table below to find which versions of the ML libraries are supported for
-your particular platform. Additional, see :ref:`installation notes <install-notes>` for helpful
-information regarding various system types before installation.
+Be sure to reference the table below to find which versions of the ML libraries
+are supported for your particular platform. Additionally, see :ref:`Platform
+Installation Guide <platform-installation>` for helpful information regarding
+for specific systems.
 
 Linux
 -----
@@ -287,8 +285,7 @@ combination.
 
   GPU builds can be troublesome due to the way that RedisAI and the ML-package
   backends look for the CUDA Toolkit and cuDNN libraries. Please see the
-  :ref:`Platform Installation Section <install-notes>` section for guidance.
-
+  :ref:`Install Troubleshooting <installation-troubleshooting>` section for guidance.
 
 .. _dragon_install:
 

doc/installation_instructions/install_notes.rst

@@ -1,3 +1,5 @@
+.. _platform-installation:
+
 Platform Install Guide
 ======================
 
@@ -9,18 +11,10 @@ instructions, please feel free to contribute instructions for your own
 machine.
 
 .. include:: platform/frontier.rst
-
 .. include:: platform/perlmutter.rst
-
-.. include:: platform/cray.rst
-
 .. include:: platform/pml-scylla.rst
-
+.. include:: platform/cray.rst
 .. include:: platform/olcf-summit.rst
 
 .. _site_installation:
-
-.. include:: site-install.rst
-
-
-
+.. include:: site-install.rst

doc/installation_instructions/install_notes/nonroot-linux.rst

@@ -1,5 +1,5 @@
-OLCF Frontier
-=============
+Frontier (OLCF)
+---------------
 
 Known limitations
 ^^^^^^^^^^^^^^^^^
@@ -63,7 +63,7 @@ these instructions, being sure to set the following variables
 
 .. code:: bash
 
-   smart build ^^device=rocm-6
+   smart build --device=rocm-6
 
 **Step 5:** Check that SmartSim has been installed and built correctly:
 
@@ -76,7 +76,7 @@ these instructions, being sure to set the following variables
    mkdir -p $MIOPEN_USER_DB_PATH
 
    # Run the install validation utility
-   smart validate ^^device gpu
+   smart validate --device gpu
 
 The following output indicates a successful install:
 

doc/installation_instructions/platform.rst

@@ -1,6 +1,6 @@
 
-Summit at OLCF
---------------
+Summit (OLCF)
+-------------
 
 Since SmartSim does not have a built PowerPC build, the build steps for an IBM
 system are slightly different than other systems.

doc/installation_instructions/platform/frontier.rst

@@ -1,5 +1,5 @@
-NERSC Perlmutter
-----------------
+Perlmutter (NERSC)
+------------------
 
 One-time Setup
 ^^^^^^^^^^^^^^

doc/installation_instructions/platform/olcf-summit.rst

@@ -1,5 +1,5 @@
-PML Scylla
-----------
+Scylla (PML)
+------------
 
 .. warning::
     As of September 2024, the software stack on Scylla is still being finalized.

doc/installation_instructions/platform/perlmutter.rst

@@ -12,4 +12,4 @@ from source with the following steps replacing ``COMPILER_VERSION`` and
     module use -a /lus/scratch/smartsim/local/modulefiles
     module load cudatoolkit/11.8 cudnn smartsim-deps/COMPILER_VERSION/SMARTSIM_VERSION
     pip install smartsim
-    smart build --skip-backends --device gpu [--onnx]
+    smart build --skip-backends --device gpu