Support devcontainer, refactor GitHub acitons, add documentation (#92)

* Document Spack packaging

* Document CI/CD configuration and build scripts

* Address duplicate license and copyright notice files

* Remove unused makefiles

* Add devcontainer working build and pipeline for docs without action.

* add instructions for dev container

* remove documentation pipeline from running everytime

* fix missing doxygen stylesheet

* fix dotfile path

---------

Co-authored-by: [email protected] <[email protected]>
Co-authored-by: [email protected] <[email protected]>

Author: 3 people

.devcontainer/Dockerfile

@@ -0,0 +1,19 @@
+# Container image that runs your code
+FROM python:3.13.0a1-alpine
+
+# Sphinx
+RUN pip3 install --no-cache-dir \
+        sphinx \
+        docutils \
+        sphinx_rtd_theme \
+        breathe \
+        m2r2
+
+# Tex
+RUN apk update && \
+    apk add --no-cache \
+        git \
+        cmake \
+        doxygen \
+        graphviz \
+        ttf-freefont

.devcontainer/devcontainer.json

@@ -0,0 +1,33 @@
+{
+	"name": "Documentation Container",
+	"build": {
+		"dockerfile": "Dockerfile",
+		"context": ".."
+	},
+
+	"features": {
+		"ghcr.io/devcontainers/features/common-utils:2": {
+			"username": "automatic",
+			"uid": "automatic",
+			"gid": "automatic",
+			"installZsh": false,
+			"installOhMyZsh": false,
+			"upgradePackages": false,
+			"nonFreePackages": false
+		}
+	},
+    "customizations": {
+		"vscode": {
+			"extensions": [
+				"ms-azuretools.vscode-docker",
+				"github.vscode-github-actions",
+				"ms-vscode.cpptools-extension-pack",
+				"GitHub.copilot",
+                "ms-vscode.cpptools",
+                "ms-vscode.cmake-tools"
+			]
+		}
+	},
+    "workspaceFolder": "/home/app/",
+    "workspaceMount": "source=${localWorkspaceFolder},target=/home/app/,type=bind,consistency=cached"
+}

.github/workflows/documentation.yml

@@ -1,6 +1,6 @@
 name: documentation
 
-on: [pull_request]
+on: workflow_dispatch 
 
 permissions:
   contents: write
@@ -9,14 +9,30 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - name: Doxygen Build
-        uses: ryandanehy/sphinx-doxygen@v1
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - uses: actions/setup-python@v4
         with:
-           sphinx-path: './sphinx/_build'
-           working-directory: 'docs'
-           doxyfile-path: './doxygen/Doxyfile.in'
-      - uses: actions/setup-python@v3
+          python-version: '3.12' 
+      - name: Install pip dependencies
+        run: pip3 install --no-cache-dir \
+                  sphinx \
+                  docutils \
+                  sphinx_rtd_theme \
+                  breathe \
+                  m2r2
+      - name: Install apt packages
+        uses: awalsh128/cache-apt-pkgs-action@latest
+        with: 
+          packages: doxygen graphviz git graphviz ttf-freefont cmake
+          version: 1.0.0
+      - name: Doxygen Build
+        run: |
+          pushd docs
+          sphinx-build . ./sphinx/_build
+          doxygen ./doxygen/Doxyfile.in
+          popd
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         if: ${{ github.event_name == 'pull_request' }}

.gitignore

@@ -11,3 +11,5 @@ spack-env-*/
 spack-build-*
 spack_install.*
 spack-configure-*
+docs/dox.warnings
+docs/@[email protected]

LICENSE

@@ -53,5 +53,3 @@ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- 
-******************************************************************************

README.md

@@ -2,7 +2,7 @@
 
 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.
 
-ReadTheDocs Documentation lives here https://ornl.github.io/ReSolve/
+ReadTheDocs Documentation lives here https://resolve.readthedocs.io/en/develop/
 
 ## Getting started
 

docs/conf.py

@@ -38,16 +38,9 @@
 # Get current directory
 conf_directory = os.path.dirname(os.path.realpath(__file__))
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration ------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -58,91 +51,51 @@
     'sphinxcontrib.jquery',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    'sphinx.ext.mathjax'
+    'sphinx.ext.mathjax',
+    'm2r2'
 ]
 
 # The main toctree document.
 master_doc = 'index'
 
 # Add any paths that contain templates here, relative to this directory.
-# I think this is right:
 templates_path = [os.path.join(conf_directory, 'sphinx/_templates')]
-# Other variations:
 
 # The suffix(es) of source filenames.
-# You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = ['.rst']
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
+source_suffix = ['.rst', '.html', '.md']
 
 project = 'ReSolve'
 copyright = '2023, UT-Battelle, LLC, and Battelle Memorial Institute'
 author = 'Kasia Świrydowicz, Slaven Peles'
 release = '1.0.0'
 
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
+templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+root_doc = 'index'
+
 # -- Option for numbering figures/tables/etc.-----------------------------------
 # Note: numfig requires Sphinx (1.3+)
 numfig = True
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-#version = '0.1'
-# The full version, including alpha/beta/rc tags.
-#release = '0.1'
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
 language = 'English'
 
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = [ 
                      'cmake/blt/docs',
-                     'thirdparty']
-
-# The reST default role (used for this markup: `text`) to use for all
-# documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
+                     'thirdparty',
+                     'doxygen-awesome-css'
+                ]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'default'
 
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-# If true, keep warnings as "system message" paragraphs in the built documents.
-#keep_warnings = False
-
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
@@ -165,91 +118,6 @@
     html_theme_options = {}
     html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-
-# all static files should be in the _build/_static directory
-# readthedocs server checks out the github repo and paths remain the same
-html_static_path = [os.path.join(conf_directory, 'sphinx/_build/_static')]
-
-#html_static_path = ['docs/sphinx/_build/_static/theme_overrides.css']
-
-# Add any extra paths that contain custom files (such as robots.txt or
-# .htaccess) here, relative to this directory. These files are copied
-# directly to the root of the documentation.
-#html_extra_path = []
-
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
-#html_use_smartypants = True
-
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
-
-# Language to be used for generating the HTML full-text search index.
-# Sphinx supports the following languages:
-#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
-#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
-#html_search_language = 'en'
-
-# A dictionary with options for the search language support, empty by default.
-# Now only 'ja' uses this config value
-#html_search_options = {'type': 'default'}
-
-# The name of a javascript file (relative to the configuration directory) that
-# implements a search results scorer. If empty, the default will be used.
-#html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ReSolve'
@@ -258,7 +126,7 @@
 # override wide tables in RTD theme
 # (Thanks to https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html)
 # These folders are copied to the documentation's HTML output
-# html_static_path = ['sphinx/_static']
+html_static_path = ['./sphinx/style']
 
 # These paths are either relative to html_static_path
 # or fully qualified paths (eg. https://...)