Add documentation

.github/workflows/docs.yaml

@@ -0,0 +1,57 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-26.05
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v6
+
+      - name: Build documentation with Sphinx
+        env:
+          SOURCE_DATE_EPOCH: "1767225600"
+        run: |
+          nix shell \
+            --impure \
+            --expr 'with import <nixpkgs> {}; python3.withPackages (ps: [ ps.sphinx ps.furo ])' \
+            -c sphinx-build -b html -W --keep-going doc/sphinx doc/sphinx/_build/html
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: doc/sphinx/_build/html
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

README.md

@@ -1,3 +1,5 @@
+![flecsolve logo](doc/sphinx/_static/flecsolve.svg)
+
 The flecsolve package is a parallel computational framework for
 multi-physics application development using the open source [FleCSI](https://flecsi.github.io/flecsi/)
 programming system.  Flecsolve employs design principles from the [AMP](https://github.com/AdvancedMultiPhysics/AMP)

doc/sphinx/.gitignore

@@ -0,0 +1 @@
+_build/

doc/sphinx/Makefile

@@ -0,0 +1,16 @@
+# Minimal makefile for Sphinx documentation
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+override SOURCE_DATE_EPOCH = 1767225600
+export SOURCE_DATE_EPOCH
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/sphinx/build.rst

@@ -0,0 +1,86 @@
+Build and Install
+=================
+
+flecsolve is a CMake project that requires a C++17 compiler, FleCSI, and
+Eigen. AMP support is enabled by default and requires AMP and its TPLs.
+
+Dependencies
+------------
+
+Required dependencies:
+
+* CMake 3.23 or newer
+* C++17 compiler
+* FleCSI
+* Eigen3
+
+Optional dependencies:
+
+* AMP, enabled with ``FLECSOLVE_ENABLE_AMP``
+* TPLs required by AMP
+
+Configure
+---------
+
+Configure a release build with AMP enabled:
+
+.. code-block:: console
+
+   cmake -S . -B build \
+     -DCMAKE_BUILD_TYPE=Release \
+     -DCMAKE_INSTALL_PREFIX=/path/to/install
+
+Disable AMP support when the AMP-backed wrappers are not needed:
+
+.. code-block:: console
+
+   cmake -S . -B build \
+     -DFLECSOLVE_ENABLE_AMP=OFF
+
+Build and Test
+--------------
+
+Build the library:
+
+.. code-block:: console
+
+   cmake --build build
+
+Enable and run unit tests:
+
+.. code-block:: console
+
+   cmake -S . -B build -DFLECSOLVE_ENABLE_UNIT_TESTS=ON
+   cmake --build build
+   ctest --test-dir build
+
+Build examples:
+
+.. code-block:: console
+
+   cmake -S . -B build -DFLECSOLVE_BUILD_EXAMPLES=ON
+   cmake --build build
+
+Install
+-------
+
+Install the library, headers, and CMake package files:
+
+.. code-block:: console
+
+   cmake --install build
+
+Downstream CMake projects can then use:
+
+.. code-block:: cmake
+
+   find_package(flecsolve REQUIRED)
+   target_link_libraries(my_target PRIVATE flecsolve::flecsolve)
+
+Spack
+-----
+
+The repository includes Spack package definitions under ``spack-repo``.
+The v2 package currently tracks the ``main`` branch and depends on
+FleCSI 2.4 or newer, AMP with Hypre and shared libraries, Stacktrace,
+and Eigen.