Infrastructure for Documentation

.github/workflows/docs.yml

@@ -0,0 +1,65 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: docs (gh-pages)
+
+on:
+  push:
+    branches: ["develop"]
+
+  # For testing only
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.11'
+        cache: 'pip'
+    - name: Install system dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y doxygen graphviz
+    - name: Install Python dependencies
+      run: |
+        python3 -m pip install --upgrade pip
+        pip install -r docs/requirements.txt
+    - name: Build documentation
+      run: |
+        cd docs
+        make html
+      # env:
+      #   SPHINXOPTS: "-W --keep-going"
+    - name: Check for broken links
+      run: |
+        cd docs
+        make linkcheck
+      continue-on-error: true
+    - name: Setup Pages
+      uses: actions/configure-pages@v5
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      if: success()
+      with:
+        path: "docs/build/html"
+        retention-days: 3 # Custom retention for this artifact
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

docs/Doxyfile

@@ -0,0 +1,46 @@
+# Doxyfile for AMS C++ Documentation
+
+PROJECT_NAME           = "AMS"
+PROJECT_BRIEF          = "Autonomous MultiScale Library"
+PROJECT_NUMBER         = 0.1.0
+
+OUTPUT_DIRECTORY       = build
+CREATE_SUBDIRS         = NO
+
+INPUT                  = ../src
+RECURSIVE              = YES
+FILE_PATTERNS          = *.hpp *.h *.cpp
+
+EXCLUDE_PATTERNS       = */tests/* */examples/*
+
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = YES
+
+CLASS_DIAGRAMS         = YES
+HAVE_DOT               = YES
+DOT_NUM_THREADS        = 4
+UML_LOOK               = YES
+TEMPLATE_RELATIONS     = YES
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+
+BUILTIN_STL_SUPPORT    = YES

docs/Makefile

@@ -0,0 +1,35 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile clean doxygen
+
+# Generate Doxygen documentation for C++ code
+doxygen:
+	@echo "Generating Doxygen XML..."
+	@mkdir -p build/xml
+	@doxygen Doxyfile
+
+# Clean all build artifacts
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf build/xml
+	rm -rf source/api
+
+# Build HTML documentation with Doxygen
+html: doxygen
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile doxygen
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/README.md

@@ -0,0 +1,20 @@
+# AMS Documentation
+
+##  Build Instructions
+
+To get setup with a virtual environment run:
+
+```bash
+python3 -m venv -m ams-doc
+. ams-doc/bin/activate
+cd AMS/docs
+pip install -r requirements.txt
+```
+
+Then you can build the documention locally with:
+```bash
+make html
+```
+
+This step can take > 2 minutes due to the use of Exhale which reads all the Doxygen XML files
+and generates a nice Sphinx-like documentation.

docs/requirements.txt

@@ -0,0 +1,10 @@
+# Documentation build dependencies
+sphinx>=7.0.0
+sphinx-rtd-theme>=2.0.0
+sphinx-copybutton>=0.5.2
+breathe>=4.35.0
+exhale>=0.3.0
+myst-parser>=2.0.0
+sphinx-autobuild>=2024.10.3
+sphinx-design>=0.6.1
+furo>=2025.9.25

docs/source/conf.py

@@ -0,0 +1,139 @@
+# Configuration file for the Sphinx documentation builder.
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+
+# -- Project information -----------------------------------------------------
+project = 'AMS'
+copyright = '2023-2025, Lawrence Livermore National Security, LLC'
+author = 'AMS Development Team'
+
+# The version info for the project
+# Read from VERSION file or git
+version = '0.1'
+# release = '0.1.0'
+
+# -- General configuration ---------------------------------------------------
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.graphviz',
+    'breathe',  # For C++ documentation
+    'exhale', # For C++ search + integration
+    'myst_parser',  # For Markdown support
+    'sphinx_copybutton',  # Add copy button to code blocks
+    "sphinx_design" # Furo theme
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+# The suffix(es) of source filenames.
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
+
+# The master toctree document.
+master_doc = 'index'
+
+# -- Options for HTML output -------------------------------------------------
+# html_theme = 'sphinx_rtd_theme'
+html_theme = "furo"
+html_static_path = ['_static']
+
+
+# Tell sphinx what the primary language being documented is.
+primary_domain = "cpp"
+highlight_language = "cpp"
+
+html_context = {
+    "display_github": True,
+    "github_user": "LLNL",
+    "github_repo": "AMS",
+    "github_version": "develop",
+    "conf_py_path": "/docs/source/",
+}
+
+# -- Options for autodoc -----------------------------------------------------
+autodoc_default_options = {
+    'members': True,
+    'member-order': 'bysource',
+    'special-members': '__init__',
+    'undoc-members': True,
+    'exclude-members': '__weakref__'
+}
+
+# -- Options for Napoleon (Google/NumPy style docstrings) -------------------
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = False
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True
+
+# -- Options for Breathe (C++ documentation) ---------------------------------
+breathe_projects = {
+    "AMS": "../build/xml"
+}
+breathe_default_project = "AMS"
+
+# -- Options for intersphinx -------------------------------------------------
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'torch': ('https://pytorch.org/docs/stable/', None),
+}
+
+# Setup the exhale extension
+exhale_args = {
+    "containmentFolder":     "./api",
+    "rootFileName":          "library_root.rst",
+    "doxygenStripFromPath":  "..",
+    # Heavily encouraged optional argument (see docs)
+    # "rootFileTitle":         "API",
+    # "fullApiSubSectionTitle": "",
+    "createTreeView":        True,
+    # TIP: if using the sphinx-bootstrap-theme, you need
+    # "treeViewIsBootstrap": True,
+    "exhaleExecutesDoxygen": True,
+    "exhaleDoxygenStdin":    "INPUT = ../../src"
+}
+
+# -- Options for MyST Parser -------------------------------------------------
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "fieldlist",
+    "html_admonition",
+    "html_image",
+    "linkify",
+    "replacements",
+    "smartquotes",
+    "strikethrough",
+    "substitution",
+    "tasklist",
+]
+
+# -- Options for copybutton --------------------------------------------------
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True

docs/source/index.rst

@@ -0,0 +1,62 @@
+Autonomous MultiScale Library
+=============================
+
+.. image:: https://img.shields.io/badge/license-Apache%202.0%20with%20LLVM%20exceptions-blue.svg
+   :target: https://github.com/LLNL/AMS/blob/develop/LICENSE
+   :alt: License
+
+.. image:: https://img.shields.io/github/stars/LLNL/AMS
+   :target: https://github.com/LLNL/AMS
+   :alt: GitHub Stars
+
+Autonomous MultiScale (AMS) is a framework designed to simplify the integration of machine learning (ML) surrogate models 
+in multiphysics high-performance computing (HPC) codes.
+
+Overview
+--------
+
+AMS provides the end-to-end infrastructure to automate all steps in the process 
+from testing and deploying ML surrogate models in
+scientific applications. With simple code modifications, developers can integrate 
+AMS into their scientific workflows to make multiphysics codes:
+
+* **Faster** - by replacing expensive evaluations with reliable surrogate models 
+  backed by verified fallbacks.
+* **More Accurate** - by increasing the effective fidelity of subscale models 
+  beyond what is currently feasible.
+* **Portable** - by providing a general framework applicable to a wide range of 
+  use cases.
+
+Key Features
+------------
+
+* **Automated Workflow**: Automation of ML surrogate models deployment and testing.
+* **HPC Integration**: Designed for supercomputing environments.
+* **Multiple Backend Support**: CPU, or GPU (CUDA and HIP).
+* **Database Integration**: Support for HDF5 and RabbitMQ.
+* **Surrogate Model Support**: PyTorch.
+* **Performance Monitoring**: Built-in Caliper support.
+
+Quick Links
+-----------
+
+* **GitHub Repository**: https://github.com/LLNL/AMS
+* **Issue Tracker**: https://github.com/LLNL/AMS/issues
+
+Citation
+--------
+
+If you use this software, please cite it as:
+
+.. code-block:: bibtex
+
+   @software{ams2023,
+     author = {Bhatia, Harsh and Patki, Tapasya A. and Brink, Stephanie and 
+               Pottier, Loïc and Stitt, Thomas M. and Parasyris, Konstantinos and 
+               Milroy, Daniel J. and Laney, Daniel E. and Blake, Robert C. and 
+               Yeom, Jae-Seung and Bremer, Peer-Timo and Doutriaux, Charles},
+     title = {Autonomous MultiScale Library},
+     url = {https://github.com/LLNL/AMS},
+     year = {2023},
+     doi = {10.11578/dc.20230721.1}
+   }