Update installation instructions (CrayLabs#262)

The changes here describe how to install SmartSim on a wide
variety of platforms. Some of this material was previously available, but
in general should be easier to follow for users. In particular, this PR 
includes instructions for how to build SmartSim with the GPU-enabled
ML backends and elucidates the process for using 'site-install' of
SmartSim.
[ committed by @ashao ]
[ reviewed by @amandarichardsonn @al-rigazzi @MattToast ]

Author: ashao

codecov.yml

@@ -10,11 +10,11 @@ coverage:
     patch:
       default:
        # Account for some variability in codecov
-       threshold: 0.5% 
+       target: 0%
     project:
       default:
        # Account for some variability in codecov
-       threshold: 0.5% 
+       target: 0%
 
 parsers:
   gcov:

doc/changelog.rst

@@ -276,7 +276,7 @@ Released on May 5, 2021
 
 Description:
 This release was dedicated to making the install process
-easier. SmartSim can be installed from PyPi now and the
+easier. SmartSim can be installed from PyPI now and the
 ``smart`` cli tool makes installing the machine learning
 runtimes much easier.
 

doc/developer.rst

@@ -6,18 +6,62 @@ Developer
 This section details common practices and tips for contributors
 to SmartSim and SmartRedis.
 
+==========================
+Building the Documentation
+==========================
+
+Users can optionally build documentation of SmartSim through ``make docs`` or
+``make docks``.  ``make docs`` requires the user to install the documentation
+build dependencies, whereas ``make docks`` only requires docker. ``make docks``
+is the recommended method for building the documentation locally, due to ease of
+use.
+
+With docker
+===========
+
+.. note::
+
+  To build the full documentation with ``make docks``, users need to install
+  `docker <https://docs.docker.com/desktop/>`_ so that ``docker`` is available
+  on the command line.
+
+.. code-block:: bash
+
+  # From top level smartsim git repository directory
+  make docks
+
+Once the documentation has successfully built, users can open the main documents
+page from ``docs/develop/index.html``.
+
+Without docker
+==============
+
+.. note::
+
+  To build the full documentation via ``make docs``, users need to install
+  ``doxygen 1.9.1``. For Mac OS users, doxygen can be installed through ``brew
+  install doxygen``
+
+.. code-block:: bash
+
+  # From top level smartsim git repository directory
+  git clone https://github.com/CrayLabs/SmartRedis.git smartredis
+  make docs
+
+Once the documentation has successfully built, users can open the main documents
+page from ``doc/_build/html/index.html``
+
 ================
 Testing SmartSim
 ================
 
 .. note::
 
-    This section describes how to run the SmartSim (infrastructure library)
-    test suite. For testing SmartRedis, see below
+    This section describes how to run the SmartSim (infrastructure library) test
+    suite. For testing SmartRedis, see below
 
-SmartSim utilizes ``Pytest`` for running its test suite. In the
-top level of SmartSim, users can run multiple testing commands
-with the developer Makefile
+SmartSim utilizes ``Pytest`` for running its test suite. In the top level of
+SmartSim, users can run multiple testing commands with the developer Makefile
 
 .. code-block:: text
 
@@ -29,27 +73,26 @@ with the developer Makefile
 
 .. note::
 
-  For the test to run, you must have the ``requirements-dev.txt``
-  dependencies installed in your python environment.
+  For the test to run, you must have the ``requirements-dev.txt`` dependencies
+  installed in your python environment.
 
 
 Local
 =====
 
-There are two levels of testing in SmartSim. The first
-runs by default and does not launch any jobs out onto
-a system through a workload manager like Cobalt.
+There are two levels of testing in SmartSim. The first runs by default and does
+not launch any jobs out onto a system through a workload manager like Cobalt.
 
-If any of the above commands are used, the test suite will
-run the "light" test suite by default.
+If any of the above commands are used, the test suite will run the "light" test
+suite by default.
 
 
 PBSPro, Slurm, Cobalt, LSF
 ==========================
 
-To run the full test suite, users will have to be on a system
-with one of the above workload managers. Additionally, users will
-need to obtain an allocation of at least 3 nodes.
+To run the full test suite, users will have to be on a system with one of the
+above workload managers. Additionally, users will need to obtain an allocation
+of at least 3 nodes.
 
 .. code-block:: bash
 
@@ -63,22 +106,21 @@ need to obtain an allocation of at least 3 nodes.
   qsub -n 3 -t 00:10:00 -A account -q queue -I
 
   # for LSF (with jsrun)
-  bsub -Is -W 00:30 -nnodes 3 -P project $SHELL 
+  bsub -Is -W 00:30 -nnodes 3 -P project $SHELL
 
 Values for queue, account, or project should be substituted appropriately.
 
-Once in an iterative allocation, users will need to set the test
-launcher environment variable: ``SMARTSIM_TEST_LAUNCHER`` to one
-of the following values
+Once in an iterative allocation, users will need to set the test launcher
+environment variable: ``SMARTSIM_TEST_LAUNCHER`` to one of the following values
 
  - slurm
  - cobalt
  - pbs
  - lsf
  - local
 
-If tests have to run on an account or project, 
-the environment variable ``SMARTSIM_TEST_ACCOUNT`` can be set.
+If tests have to run on an account or project, the environment variable
+``SMARTSIM_TEST_ACCOUNT`` can be set.
 
 -------------------------------------------------------
 

doc/experiment.rst

@@ -3,14 +3,14 @@
 Experiments
 ***********
 
-The Experiment acts as both a factory class for constructing the
-stages of an experiment (``Model``, ``Ensemble``, ``Orchestrator``, etc.)
-as well as an interface to interact with the entities created by the experiment.
+The Experiment acts as both a factory class for constructing the stages of an
+experiment (``Model``, ``Ensemble``, ``Orchestrator``, etc.) as well as an
+interface to interact with the entities created by the experiment.
 
-Users can initialize an :ref:`Experiment <experiment_api>` at the beginning of a Jupyter notebook,
-interactive python session, or Python file and use the ``Experiment`` to
-iteratively create, configure and launch computational kernels on the
-system through the specified launcher.
+Users can initialize an :ref:`Experiment <experiment_api>` at the beginning of a
+Jupyter notebook, interactive python session, or Python file and use the
+``Experiment`` to iteratively create, configure and launch computational kernels
+on the system through the specified launcher.
 
 .. |SmartSim Architecture| image:: images/ss-arch-overview.png
   :width: 700
@@ -19,21 +19,21 @@ system through the specified launcher.
 |SmartSim Architecture|
 
 
-The interface was designed to be simple, with as little complexity
-as possible, and agnostic to the backend launching mechanism (local,
-Slurm, PBSPro, etc.).
+The interface was designed to be simple, with as little complexity as possible,
+and agnostic to the backend launching mechanism (local, Slurm, PBSPro, etc.).
 
 Model
 =====
 
 ``Model(s)`` are subclasses of ``SmartSimEntity(s)`` and are created through the
-Experiment API. Models represent any computational kernel. Models are flexible enough
-to support many different applications, however, to be used with our clients
-(SmartRedis) the application will have to be written in Python, C, C++, or Fortran.
+Experiment API. Models represent any computational kernel. Models are flexible
+enough to support many different applications, however, to be used with our
+clients (SmartRedis) the application will have to be written in Python, C, C++,
+or Fortran.
 
-Models are given :ref:`RunSettings <rs-api>` objects that specify how a kernel should
-be executed with regard to the workload manager (e.g. Slurm) and the available
-compute resources on the system.
+Models are given :ref:`RunSettings <rs-api>` objects that specify how a kernel
+should be executed with regard to the workload manager (e.g. Slurm) and the
+available compute resources on the system.
 
 Each launcher supports specific types of ``RunSettings``.
 
@@ -45,7 +45,8 @@ Each launcher supports specific types of ``RunSettings``.
 These settings can be manually specified by the user, or auto-detected by the
 SmartSim Experiment through the ``Experiment.create_run_settings`` method.
 
-A simple example of using the Experiment API to create a model and run it locally:
+A simple example of using the Experiment API to create a model and run it
+locally:
 
 .. code-block:: Python
 
@@ -83,9 +84,9 @@ For example with Slurm
 
   print(exp.get_status(model))
 
-The above will run ``srun -n 32 -N 1 echo Hello World!``, monitor it's execution,
-and inform the user when it is completed. This driver script can be executed in
-an interactive allocation, or placed into a batch script as follows:
+The above will run ``srun -n 32 -N 1 echo Hello World!``, monitor its
+execution, and inform the user when it is completed. This driver script can be
+executed in an interactive allocation, or placed into a batch script as follows:
 
 .. code-block:: bash
 
@@ -108,18 +109,18 @@ An ``Ensemble`` can be constructed in three ways:
   2. Replica creation (by specifying ``replicas`` argument)
   3. Manually (by adding created ``Model`` objects) if launching as a batch job
 
-Ensembles can be given parameters and permutation strategies that
-define how the ``Ensemble`` will create the underlying model objects.
+Ensembles can be given parameters and permutation strategies that define how the
+``Ensemble`` will create the underlying model objects.
 
 Three strategies are built in:
   1. ``all_perm``: for generating all permutations of model parameters
   2. ``step``: for creating one set of parameters for each element in `n` arrays
   3. ``random``: for random selection from predefined parameter spaces
 
 Here is an example that uses the ``random`` strategy to intialize four models
-with random parameters within a set range. We use the ``params_as_args``
-field to specify that the randomly selected learning rate parameter should
-be passed to the created models as a executable argument.
+with random parameters within a set range. We use the ``params_as_args`` field
+to specify that the randomly selected learning rate parameter should be passed
+to the created models as a executable argument.
 
 .. code-block:: bash
 
@@ -145,11 +146,11 @@ be passed to the created models as a executable argument.
   exp.start(ensemble, summary=True)
 
 
-A callable function can also be supplied for custom permutation strategies.
-The function should take two arguments: a list of parameter names, and a list of lists
-of potential parameter values. The function should return a list of dictionaries that
-will be supplied as model parameters. The length of the list returned will determine
-how many ``Model`` instances are created.
+A callable function can also be supplied for custom permutation strategies.  The
+function should take two arguments: a list of parameter names, and a list of
+lists of potential parameter values. The function should return a list of
+dictionaries that will be supplied as model parameters. The length of the list
+returned will determine how many ``Model`` instances are created.
 
 For example, the following is the built-in strategy ``all_perm``:
 

doc/index.rst

@@ -7,11 +7,12 @@
    versions
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Getting Started
 
    overview
-   installation
+   installation_instructions/basic
+   installation_instructions/platform
    community
    contributing_examples
 
@@ -54,6 +55,7 @@
    changelog
    code_of_conduct
    developer
+   testing
 
 
 Indices and tables