Update user guide. (#133)

* Update user guide.

* Reorganize documentation directories

* Add docs on HPCToolkit profiling

* Add rocprof instructions to the documentation.

LICENSE

@@ -2,9 +2,10 @@ Copyright (c) 2023, UT-Battelle, LLC and Battelle Memorial Institute.
 All rights reserved.
 
 ReSolve version 1.0
-
+
+
 Open Source License:
- 
+
 Subject to the conditions of this License, UT-Battelle, LLC and Battelle
 Memorial Institute hereby grant, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), a
@@ -26,16 +27,16 @@ endorse or promote products derived from this Software without their specific
 prior written permission.
 
 3. The Software, with or without modification, must include the following
-acknowledgment:
- "This product includes software produced by UT-Battelle, LLC under Contract
-No. DE-AC05-00OR22725 and Battelle Memorial Institute under Contract 
-No. DE-AC05-76RL01830 with the Department of Energy.”
-
-
-
-******************************************************************************
-DISCLAIMER
+acknowledgment: "This product includes software produced by UT-Battelle, LLC
+under Contract No. DE-AC05-00OR22725 and Battelle Memorial Institute under
+Contract No. DE-AC05-76RL01830 with the Department of Energy.”
 
+
+
+-------------------------------------------------------------------------------
+
+DISCLAIMER:
+
 UT-BATTELLE, LLC, BATTELLE MEMORIAL INSTITUTE, AND THE GOVERNMENT MAKE NO
 REPRESENTATIONS AND DISCLAIM ALL WARRANTIES, BOTH EXPRESSED AND IMPLIED.
 THERE ARE NO EXPRESS OR IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR
@@ -45,4 +46,4 @@ WILL ACCOMPLISH THE INTENDED RESULTS OR THAT THE SOFTWARE OR ITS USE WILL NOT
 RESULT IN INJURY OR DAMAGE.  THE USER ASSUMES RESPONSIBILITY FOR ALL
 LIABILITIES, PENALTIES, FINES, CLAIMS, CAUSES OF ACTION, AND COSTS AND
 EXPENSES, CAUSED BY, RESULTING FROM OR ARISING OUT OF, IN WHOLE OR IN PART
-THE USE, STORAGE OR DISPOSAL OF THE SOFTWARE.
+THE USE, STORAGE OR DISPOSAL OF THE SOFTWARE.

README.md

@@ -1,8 +1,10 @@
 # ReSolve
 
-ReSolve is a library of GPU-resident linear solver. It contains iterative and direct linear solvers designed to run on NVIDIA and AMD GPUs, as well as on CPU devices.
+ReSolve is a library of GPU-resident linear solvers. It contains iterative and direct solvers designed to run on NVIDIA and AMD GPUs, as well as on CPU devices.
+
+The User Guide and developer's documentation is available [online](https://resolve.readthedocs.io/),
+including Doxygen-generated [source code documentation](https://resolve.readthedocs.io/en/develop/doxygen/html/index.html).
 
-ReadTheDocs Documentation lives here https://resolve.readthedocs.io/en/develop/
 
 ## Getting started
 

docs/conf.py

@@ -199,7 +199,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   (master_doc, 'ReSolve', u'ReSolve Documentation',
-   'ReSolve Team', 'ReSolve', 'ReSolve is a library of GPU-resident linear solver.',
+   'ReSolve Team', 'ReSolve', 'ReSolve is a library of GPU-resident linear solvers.',
    'Miscellaneous'),
 ]
 

docs/index.rst

@@ -2,68 +2,86 @@
 ReSolve
 *******
 
-ReSolve is a library of GPU-resident linear solver. It contains iterative and direct linear solvers designed to run on NVIDIA and AMD GPUs, as well as on CPU devices.
+ReSolve is an open-source library that provides GPU-resident linear solvers. 
+It contains iterative and direct solvers designed to run on NVIDIA and AMD
+GPUs, as well as on CPU devices.
+
+ReSolve source code and documentation are available at
+`GitHub <https://github.com/ORNL/ReSolve>`_.
 
-To learn how to get start with resolve please checkout our `User Guide <sphinx/html/guide.html>`_
 
-=============
 Documentation
-=============
+-------------
+
+To get started, please check our `User Guide <sphinx/user_guide/index.html>`_.
+Source code documentation generated in Doxygen is also
+`linked <doxygen/html/index.html>`_ to this site.
 
-Source code documentation are also linked on this site.
-`ReSolve Github Project <https://github.com/ORNL/ReSolve>`_.
-`Source documentation <doxygen/html/index.html>`_
 
 Contributing
 ------------
 
-For all contributions to ReSolve please follow the `developer
-guidelines <sphinx/coding_guide/index.html>`__
+For all contributions to ReSolve please consult 
+`Developer Guide <sphinx/developer_guide/index.html>`_ and follow the 
+`Coding Style Guidelines <sphinx/coding_guidelines/index.html>`_.
 
 Authors and acknowledgment
 --------------------------
 
 Primary authors of this project are:
+
 * Kasia Świrydowicz kasia.swirydowicz@pnnl.gov (PNNL)
 * Slaven Peles peless@ornl.gov (ORNL)
 
 ReSolve project would not be possible without significant contributions
-from (in alphabetic order): 
+from (in alphabetic order):
+
 * Maksudul Alam (ORNL)
 * Ryan Danehy (PNNL)
 * Nicholson Koukpaizan (ORNL)
 * Jaelyn Litzinger (PNNL)
 * Phil Roth (ORNL)
 * Cameron Rutherford (PNNL)
 
-Development of this code was supported by the Exascale Computing Project (ECP), Project Number: 17-SC-20-SC, a collaborative effort of two DOE organizations—the Office of Science and the National Nuclear Security Administration—responsible for the planning and preparation of a capable exascale ecosystem—including software, applications, hardware, advanced system engineering, and early testbed platforms—to support the nation’s exascale computing imperative.
+Development of this code was supported by the Exascale Computing Project (ECP),
+Project Number: 17-SC-20-SC, a collaborative effort of two DOE organizations
+— the Office of Science and the National Nuclear Security Administration —
+responsible for the planning and preparation of a capable exascale ecosystem
+— including software, applications, hardware, advanced system engineering, and
+early testbed platforms — to support the nation’s exascale computing
+imperative.
 
 License
 -------
 
-Copyright © 2023, UT-Battelle, LLC, and Battelle Memorial Institute.
+ReSolve is a free software distributed under a BSD-style license. See
+the `LICENSE <sphinx/license.html>`__ and `NOTICE <sphinx/notice.html>`__
+for more details. All new contributions to ReSolve must be made under the
+same licensing terms.
 
-ReSolve is a free software distributed under a BSD-style license. 
+**Please Note:** If you are using ReSolve with any third party libraries linked
+in (e.g., KLU), be sure to review the respective license of the package as that
+license may have more restrictive terms than the ReSolve license.
 
-See the `LICENSE <sphinx/license.rst>`__ and `NOTICE <sphinx/notice.rst>`__ files for details. All
-new contributions to ReSolve must be made under the same licensing
-terms.
+Copyright © 2023, UT-Battelle, LLC, and Battelle Memorial Institute.
 
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :hidden:
-   :caption: Developer Resources
+   :caption: User Resources
 
-   sphinx/coding_guide/index
-   doxygen/index
-   sphinx/licenses
+   sphinx/user_guide/index
+   sphinx/license
    sphinx/notice 
-   sphinx/developer_guide/index
+
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :hidden:
-   :caption: User Guide
+   :caption: Developer Resources
 
-   sphinx/guide
+   sphinx/coding_guidelines/index
+   doxygen/index
+   sphinx/developer_guide/index
+   sphinx/developer_guide/profiling

docs/sphinx/developer_guide/index.rst

@@ -18,11 +18,18 @@ We also export under the ``ReSolve::`` namespace in our installed CMake configur
 Spack Package
 ---------------
 
-Our current spack package is introduced in https://github.com/spack/spack/pull/40871, and contains support for building Re::Solve with CUDA and HIP/ROCm support.
+Our current Spack package has been introduced
+`upstream <https://github.com/spack/spack/pull/40871>`_, and contains support
+for building Re::Solve with CUDA and HIP/ROCm support.
 
-We also have a custom ``spack`` folder/installation that contains our spack submodule located in ``buildsystem/spack/spack``. This is used to build Re::Solve on CI platforms, as well as support development of the spack package as neccessary.
+We also have a custom ``spack`` folder/installation that contains our spack
+submodule located in ``buildsystem/spack/spack``. This is used to build
+Re::Solve on CI platforms, as well as support development of the spack package
+as neccessary.
 
-See the Quik-How-To section below for more information on how to update the spack package and typical workflows for building Re::Solve with spack on CI platforms for testing.
+See the Quik-How-To section below for more information on how to update the
+spack package and typical workflows for building Re::Solve with spack on CI
+platforms for testing.
 
 
 GitHub Actions 
@@ -83,6 +90,76 @@ Deception specific CI.
 
 Incline specific CI.
 
+
+Writing Documentation
+---------------------
+
+Re::Solve uses Sphynx for the documentation. To write and preview the
+documentation on your local machine use e.g. ``pip`` tool to install following
+Python packages:
+
+.. code:: shell
+    
+    pip install sphinx docutils sphinx_rtd_theme sphinxcontrib-jquery m2r2
+
+If you prefer using Anaconda utilities, getting these packages is 
+slightly different:
+
+.. code:: shell
+    
+    conda install sphinx docutils sphinx_rtd_theme
+    conda install -c conda-forge sphinxcontrib-jquery m2r2
+
+
+Once you have all the required packages, you can build the HTML docs by
+
+.. code:: shell
+
+  git clone git@github.com:ORNL/ReSolve.git
+  sphinx-build -M html ReSolve/docs/ ./build
+
+This will generate HTML documentation and place it in ``build``
+subdirectory in your current directory. 
+
+
+Using Dev Container for Writing Documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In case you cannot install Sphynx and other dependencies on your machine,
+Re::Solve provides scripts for building development container with all
+tools required for Sphynx documentation generation. To create container
+for documentation development follow these straightforward steps:
+
+Prerequisites
+"""""""""""""
+
+#. install Docker Desktop and launch the app
+#. install the "Remote Development" extension in VSCode
+#. open your local clone of resolve in VSCode
+
+
+Build Container
+"""""""""""""""
+
+The build info for this container is in `.devcontainer/`. There is a Dockerfile and
+json file associated with the configuration.
+
+#. if connected, disconnect from the PNNL VPN
+#. launch the container build  
+
+    * `cmd shift p` to open the command pallette in vscode
+    * click `> Dev Container: rebuild and reopen container`
+    * this will start building the container, taking about 40 minutes
+    * click on the pop up with `(show log)` to view the progress
+
+#. Open new terminal within Visual Studio Code and run the renderDocs.sh (note this takes a minute)
+#. Open the link that was served to you after step 3
+
+.. note:: Pushing/pulling from git is not supported in a devcontainer,
+          and should be done separately.
+
+
+
 Devcontainer Configuration
 ----------------------------