ORNL · shakedregev · Mar 12, 2026 · Mar 9, 2026 · Mar 9, 2026 · Mar 9, 2026
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
@@ -5,6 +5,7 @@ FROM python:3.13.0a1-alpine
 RUN pip3 install --no-cache-dir \
         sphinx \
         docutils \
+        setuptools \
         sphinx_rtd_theme \
         breathe \
         m2r2

diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -14,13 +14,14 @@ jobs:
           submodules: true
       - uses: actions/setup-python@v4
         with:
-          python-version: '3.12' 
+          python-version: '3.12'
       - name: Install pip dependencies
         run: pip3 install --no-cache-dir \
                   sphinx \
                   docutils \
                   sphinx_rtd_theme \
                   breathe \
+                  setuptools \
                   m2r2
       - name: Install apt packages
         uses: awalsh128/cache-apt-pkgs-action@latest

diff --git a/docs/conf.py b/docs/conf.py
@@ -44,14 +44,15 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    #'setuptools',
     'sphinx.ext.graphviz',
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'sphinxcontrib.jquery',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.mathjax',
-    'm2r2'
+    'sphinx.ext.mathjax'#,
+    #'m2r2'
 ]
 
 # The main toctree document.

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,6 +1,6 @@
-*******
+*********
 Re::Solve
-*******
+*********
 
 Re::Solve is an open-source library that provides GPU-resident linear solvers. 
 It contains iterative and direct solvers designed to run on NVIDIA and AMD

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,6 @@
 docutils
+setuptools
 sphinx==6.2.1
 sphinx-rtd-theme==1.2.2
-breathe 
+breathe
 m2r2
diff --git a/docs/sphinx/developer_guide/build_system.rst b/docs/sphinx/developer_guide/build_system.rst
@@ -1,6 +1,8 @@
+Build System
+================
 
-CMake Build System
-------------------
+CMake Configuration
+-------------------
 
 Our ``cmake`` folder contains some basic CMake modules that help manage resolve:
 

diff --git a/docs/sphinx/developer_guide/documentation.rst b/docs/sphinx/developer_guide/documentation.rst
@@ -46,7 +46,7 @@ Prerequisites
 
 
 Build Container
-^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^
 
 The build info for this container is in `.devcontainer/`. There is a Dockerfile and
 json file associated with the configuration.
@@ -71,40 +71,41 @@ Devcontainer Configuration
 ----------------------------
 
 ``Dockerfile``
-~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Installs pip and apt dependencies in Python container for doc development.
 
 ``devcontainer.json``
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Configures devcontainer through devcontainer features and sets up extensions.
 
 ``renderDocs.sh``
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Small shell script that renders documentation and hosts it for quick development.
 
+
 GitHub Actions
 ----------------------------
 
 This is a quick summary of the workflows performed in each GitHub Action. For more information see the ``.github/workflows`` folder where each file is located.
 
 ``documentation.yml``
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``ornl_ascent_mirror.yml``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Pushes to ORNL GitLab and triggers CI/CD pipelines there that are posted back to GitHub through commit messages.
 
 ``ornl_crusher_mirror.yml``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Pushes to ORNL Crusher GitLab...
 
 ``pnnl_mirror.yml``
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Pushes to PNNL GitLab...
 
@@ -114,40 +115,40 @@ GitLab Pipelines
 This is a quick summary of the workflows performed in each GitLab Pipeline. For more information see the ``yml`` file for each associated pipeline.
 
 ``ornl/crusher.gitlab-ci.yml``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Defines CI/CD for Crusher at ORNL.
 
 ``.gitlab-ci.yml``
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Located in the root git directory, this defines the CI/CD pipelines for Ascent at ORNL.
 
 ``pnnl/.gitlab-ci.yml``
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Since single GitLab repo triggers many pipelines as downstream dependents, we need a core config file to kick all of these builds off.
 
 ``pnnl/base.gitlab-ci.yml``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Describes core config shared across each job. This could be in ``pnnl/.gitlab-ci.yml`` but we keep it separate for clarity.
 
 ``pnnl/deception.gitlab-ci.yml``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Deception specific CI.
 
 ``pnnl/incline.gitlab-ci.yml``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Incline specific CI.
 
 Quick How-To guides
 -------------------
 
 Re-build Spack tcl modules on CI platforms
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can rebuild dependencies and spack tcl modules on CI platforms by doing the following using automated CI/CD:
 
@@ -184,7 +185,7 @@ Each cluster also supports submitting this job to the job scheduler by doing the
 * ``sbatch ./buildsystem/spack/<cluster>/install.sh`` to submit the workflow to the job scheduler
 
 Update Re::Solve spack package
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In order to test any modifications to the spack package, it is suggested that you use the above automated workflows to make testing as seamless as possible.
 
@@ -202,7 +203,7 @@ Typically this is done as a part of the release process, so also make sure that
 Note that spack enforces it's own styling, so consider leveraging spack-bot in order to help out. Comment ``@spackbot help`` to get a list of commands, such as ``@spackbot fix style`` to have it try and automatically style your PR for you!
 
 Refresh GitHub/GitLab Secrets
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are several secrets throughout CI/CD:
 

diff --git a/docs/sphinx/developer_guide/git_guidelines.rst b/docs/sphinx/developer_guide/git_guidelines.rst
@@ -23,25 +23,25 @@ with respect to `develop` to keep it up to date.
 
 
 Creating a GitHub Issue
-------------
+-----------------------
 
 When creating an issue, check that it is not a duplicate.
 Provide a clear and concise description, using the issue template.
 
 GitHub Pull Requests 
-------------
+--------------------
 
 When creating a pull request (PR), make sure to select the correct base branch.
 If there are merge conflicts, use ``git rebase`` to resolve them before requesting a review.
 
 Detail changes made in your PR in the description.
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 1. What new features were added?
 2. What bugs were fixed?
 3. What tests were added?
 
 When reviewing a PR consider the following:
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 1. Does the PR address the issue?
 2. Do existing and new tests pass on all supported platforms?
 3. Is the code clean, readable, and properly documented?
@@ -57,7 +57,7 @@ Add a comment to the PR with the minor concern and request the author to address
 
 
 Major concern options:
-^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 1. Suggest a change with the Github suggest feature within the PR for the author to commit before merging.
 2. Request the author to make the change and wait to approve the merge.
 3. Branch off the PR, make the change, and submit a new PR with the change. Make the assignee the author of the current PR and request the author to merge the new PR.

diff --git a/docs/sphinx/user_guide/index.rst b/docs/sphinx/user_guide/index.rst
@@ -42,7 +42,7 @@ and then try some of Re::Solve's `examples <https://github.com/ORNL/ReSolve/tree
 The examples will emulate nonlinear solver calling the linear solver repeatedly.
 
 To use the Re::Solve library in your own project
-----------------------------------------------
+------------------------------------------------
 
 Make sure Resolve library is installed (see above)
 
@@ -147,12 +147,12 @@ issue <https://github.com/ORNL/ReSolve/issues>`__.
 
 
 Re::Solve General API Description 
----------------------------
+---------------------------------
 Users are encouraged to look at the examples and tests for guidance on how to use the library. 
 When there is any conflict between the examples/tests and this documentation, the examples/tests are correct.
 
 Solver Subroutines
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 For direct solvers, the following functions are provided and must be called in this order:
 
@@ -167,7 +167,7 @@ Subsequent systems only require calls to ``refactorize()`` and ``solve()`` if th
 Note some examples do not reuse the factorization from the 0-th iteration because the numeric sparsity structure changes and that's how the matrices are stored. In a practical application, the sparsity structure is likely to remain the same. If it does not, it is the user's responsibility to reallocate memory and call ``analyze()`` and ``factorize()`` again. The user should enforce that symbolic nonzeros are stored explicitly, even if they are numerically zero.
 
 Function Requirements
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Functions must be used as in the examples and tests:
 
@@ -187,7 +187,7 @@ Functions in ReSolve that take pointers as arguments will have the following req
 * Pointers that are marked as const must point to memory that is readable.
 
 Memory Synchronization
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 * For CPU solvers, memory is always in sync.
 * For GPU solvers, the user must synchronize memory manually.