diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile index 5770ab57a..0c2bdb183 100644 --- 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 index c320c2367..f81990fb6 100644 --- 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 index 4534d06ce..e7a22ce1d 100644 --- 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 index a1efa9603..5496c0f83 100644 --- 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 index e4a9e26ac..f070b271b 100644 --- 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 index 71fb1cc54..f2cd4fcb1 100644 --- 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 index 55dcc2a97..0d1affe74 100644 --- 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,32 +115,32 @@ 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. @@ -147,7 +148,7 @@ 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//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 index 5bc5f8f7a..673ee0289 100644 --- 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 index 63bddd11c..fb232652a 100644 --- 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 `__. 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.