Added docs to cmake build

Author: platipodium

.github/copilot-instructions.md

@@ -14,10 +14,13 @@ Quick orientation (big picture)
 
 What to assume when editing/building
 - SCHISM is expected to be pre-built. The build system requires `SCHISM_BUILD_DIR` to point
-  to a SCHISM build (contains `include/` and `lib/` with `libhydro.a` etc.). See `CMakeLists.txt`.
+  to a SCHISM build (contains `include/` and `lib/` with SCHISM libraries). See `CMakeLists.txt`.
+  Required SCHISM libraries: `libcore.a`, `libhydro.a`, `libturbulence.a`, `libyaml.a`, `libparmetis.a`, `libmetis.a`
 - ESMF is discovered via an `esmf.mk` file; provide it via the environment variable `ESMFMKFILE`
   (or let `cmake/FindESMF.cmake` locate it). The CMake helper `cmake/FindESMF.cmake` parses the
   ESMF makefile and exposes include/lib variables and an `ESMF::ESMF` target.
+- **CRITICAL**: ESMF must be built with real MPI support (`ESMF_COMM=mpich` or `openmpi`), NOT `mpiuni` (MPI stub).
+  Check with: `grep ESMF_COMM $ESMFMKFILE`
 
 Build and test commands (concrete)
 - Fast: set env vars, configure, build
@@ -28,8 +31,13 @@ Build and test commands (concrete)
   cmake ..
   cmake --build . -- -j$(nproc)
   ```
-- **macOS-specific**: use Homebrew-installed gfortran and explicitly set the Fortran compiler
+- **macOS-specific**: Install ESMF with MPI support, use Homebrew/conda gfortran
   ```bash
+  # Install ESMF with MPI (choose one MPI implementation)
+  mamba install -c conda-forge "esmf=8.9.0=mpi_mpich*"
+  # or
+  mamba install -c conda-forge "esmf=8.9.0=mpi_openmpi*"
+  
   export ESMFMKFILE=/path/to/esmf.mk
   export SCHISM_BUILD_DIR=/path/to/schism/build
   mkdir -p build && cd build
@@ -44,10 +52,17 @@ Build and test commands (concrete)
 
 CI-ready checklist (for automated builds)
 1. Ensure `ESMFMKFILE` points to a valid `esmf.mk` (check existence: `test -f "$ESMFMKFILE"`).
-2. Ensure `SCHISM_BUILD_DIR` points to a pre-built SCHISM (check lib: `test -f "$SCHISM_BUILD_DIR/lib/libhydro.a"`).
-3. Set `CMAKE_Fortran_COMPILER` to an MPI-aware wrapper (e.g., `mpif90`, `esmpifort`) — CMake will warn if you use a bare compiler.
-4. Run CMake configure with explicit compiler flags and capture stderr for "FATAL_ERROR" or "WARNING" messages.
-5. Run `cmake --build . -- VERBOSE=1` to see full compile/link commands and catch missing symbols early.
+2. **Verify ESMF has MPI support**: `grep ESMF_COMM "$ESMFMKFILE" | grep -v mpiuni` (must show `mpich` or `openmpi`).
+3. Ensure `SCHISM_BUILD_DIR` points to a pre-built SCHISM with all required libraries:
+   ```bash
+   test -f "$SCHISM_BUILD_DIR/lib/libhydro.a" && \
+   test -f "$SCHISM_BUILD_DIR/lib/libcore.a" && \
+   test -f "$SCHISM_BUILD_DIR/lib/libturbulence.a" && \
+   test -f "$SCHISM_BUILD_DIR/lib/libyaml.a"
+   ```
+4. Set `CMAKE_Fortran_COMPILER` to an MPI-aware wrapper (e.g., `mpif90`, `esmpifort`) — CMake will warn if you use a bare compiler.
+5. Run CMake configure with explicit compiler flags and capture stderr for "FATAL_ERROR" or "WARNING" messages.
+6. Run `cmake --build . -- VERBOSE=1` to see full compile/link commands and catch missing symbols early.
 6. Optional: run a quick smoke test by executing `./main_esmf --help` or similar (if applicable) to verify linkage.
 
 **Automated validation**: Run `.github/test-cmake-instructions.sh` to validate your environment against this checklist.
@@ -64,7 +79,13 @@ Important patterns & conventions
   modules directory (`CMAKE_Fortran_MODULE_DIRECTORY` configured to `build/modules`). When adding
   new modules, ensure consumers see the `target_include_directories(...)` or that targets are linked
   in the correct CMake subdirectory (see `src/CMakeLists.txt`).
-- SCHISM libraries expected in `${SCHISM_BUILD_DIR}/lib` with names found by `find_library` for `core` and `hydro`.
+- **Shared source pattern**: Common Fortran sources used by multiple targets (e.g., `schism_bmi.F90`, 
+  `schism_esmf_util.F90`) are compiled once in a separate library (`schism_interface_common`) to avoid 
+  parallel build race conditions. See `src/schism/CMakeLists.txt` for the pattern.
+- SCHISM dependency chain: CMake discovers and links in this order:
+  1. SCHISM core libraries: `libcore.a`, `libhydro.a`
+  2. SCHISM dependencies: `libturbulence.a`, `libyaml.a`, `libparmetis.a`, `libmetis.a`
+  3. MPI libraries: `find_package(MPI REQUIRED)` provides `${MPI_Fortran_LIBRARIES}`
 - Optional integrations: PDAF (data assimilation) and MOSSCO are optional — guard changes so they compile
   when absent. See `scripts/Readme.md` and `src/` subdirs referencing PDAF and MOSSCO.
 
@@ -97,4 +118,4 @@ If anything here is unclear or you'd like me to expand a section (build matrix,
 
 ### Style to consider
 
-Always use camelcase for naming the ReadMe.md files in each directory.
+Always use camelcase for naming the ReadMe.md files in each directory. Same with BuildTroubleshooting.md and TestReadMe.md and other markdown files.

.github/test-cmake-instructions.sh

@@ -101,6 +101,24 @@ else
             version=$(grep "ESMF_VERSION_STRING" "$ESMFMKFILE" | head -1 | cut -d= -f2 | tr -d ' ')
             print_test INFO "ESMF Version" "$version"
         fi
+        
+        # Check ESMF_COMM (critical for build success)
+        if grep -q "ESMF_COMM" "$ESMFMKFILE"; then
+            esmf_comm=$(grep "^ESMF_COMM=" "$ESMFMKFILE" | head -1 | cut -d= -f2 | tr -d ' ')
+            print_test INFO "ESMF MPI Implementation" "$esmf_comm"
+            
+            if [[ "$esmf_comm" == "mpiuni" ]] || [[ "$esmf_comm" =~ "nompi" ]]; then
+                print_test FAIL "ESMF has real MPI support" "ESMF_COMM=$esmf_comm (stub MPI, not compatible with SCHISM)"
+                print_test INFO "Fix (conda)" "mamba install -c conda-forge 'esmf=*=mpi_mpich*'"
+                print_test INFO "Fix (spack)" "spack install esmf+mpi"
+            elif [[ "$esmf_comm" == "mpich" ]] || [[ "$esmf_comm" == "openmpi" ]]; then
+                print_test PASS "ESMF has real MPI support" "$esmf_comm"
+            else
+                print_test WARN "ESMF MPI implementation unknown" "$esmf_comm"
+            fi
+        else
+            print_test FAIL "ESMF_COMM variable found" "Cannot determine MPI implementation"
+        fi
     else
         print_test FAIL "esmf.mk appears invalid" "Missing ESMF_VERSION_MAJOR"
     fi
@@ -144,11 +162,103 @@ else
     if [[ -f "$SCHISM_BUILD_DIR/lib/libcore.a" ]]; then
         print_test PASS "libcore.a exists"
     else
-        print_test WARN "libcore.a exists" "Optional library not found"
+        print_test FAIL "libcore.a exists" "Core library not found"
+    fi
+    
+    # Check for additional required dependencies
+    required_libs=("libturbulence.a" "libyaml.a")
+    optional_libs=("libparmetis.a" "libmetis.a")
+    
+    missing_required=()
+    for lib in "${required_libs[@]}"; do
+        if [[ -f "$SCHISM_BUILD_DIR/lib/$lib" ]]; then
+            print_test PASS "$lib exists"
+        else
+            print_test FAIL "$lib exists" "Required dependency not found"
+            missing_required+=("$lib")
+        fi
+    done
+    
+    missing_optional=()
+    for lib in "${optional_libs[@]}"; do
+        if [[ -f "$SCHISM_BUILD_DIR/lib/$lib" ]]; then
+            print_test PASS "$lib exists"
+        else
+            print_test WARN "$lib exists" "Optional library not found (may cause link errors)"
+            missing_optional+=("$lib")
+        fi
+    done
+    
+    if [[ ${#missing_required[@]} -gt 0 ]] || [[ ${#missing_optional[@]} -gt 0 ]]; then
+        print_test INFO "Available SCHISM libraries" "$(ls -1 $SCHISM_BUILD_DIR/lib/*.a 2>/dev/null | xargs -n1 basename || echo 'none')"
+        if [[ ${#missing_required[@]} -gt 0 ]]; then
+            print_test INFO "Fix" "Rebuild SCHISM with: cmake ../src && make"
+        fi
     fi
 fi
 echo ""
 
+# ========================================
+# Test 2.5: Check MPI Libraries
+# ========================================
+echo "Test 2.5: MPI Library Availability"
+echo "-----------------------------------"
+
+# Try to find MPI libraries
+mpi_found=false
+mpi_impl=""
+
+if command -v mpirun &> /dev/null || command -v mpiexec &> /dev/null; then
+    print_test PASS "MPI runtime found"
+    mpi_found=true
+    
+    # Detect MPI implementation
+    if command -v mpichversion &> /dev/null; then
+        mpi_impl="MPICH"
+        mpi_version=$(mpichversion 2>/dev/null || echo "unknown")
+        print_test INFO "MPI Implementation" "$mpi_impl $mpi_version"
+    elif command -v ompi_info &> /dev/null; then
+        mpi_impl="OpenMPI"
+        mpi_version=$(ompi_info --version 2>/dev/null | head -1 || echo "unknown")
+        print_test INFO "MPI Implementation" "$mpi_impl $mpi_version"
+    else
+        print_test INFO "MPI Implementation" "Unknown (mpirun found)"
+    fi
+else
+    print_test WARN "MPI runtime found" "mpirun/mpiexec not in PATH"
+fi
+
+# Check for MPI libraries in common locations
+mpi_lib_found=false
+if [[ -n "${CONDA_PREFIX:-}" ]]; then
+    if ls "$CONDA_PREFIX/lib"/libmpi*.dylib &>/dev/null || ls "$CONDA_PREFIX/lib"/libmpi*.so &>/dev/null; then
+        print_test PASS "MPI libraries found in conda environment"
+        mpi_lib_found=true
+        print_test INFO "MPI library path" "$CONDA_PREFIX/lib"
+    fi
+elif [[ -n "${SPACK_ROOT:-}" ]]; then
+    # Spack environment - MPI should be in PATH
+    print_test INFO "Spack environment detected" "MPI from spack load"
+    mpi_lib_found=true
+else
+    # Check system locations
+    for libdir in /usr/lib /usr/local/lib /opt/local/lib /opt/homebrew/lib; do
+        if [[ -d "$libdir" ]] && (ls "$libdir"/libmpi*.so &>/dev/null || ls "$libdir"/libmpi*.dylib &>/dev/null); then
+            print_test PASS "MPI libraries found" "$libdir"
+            mpi_lib_found=true
+            break
+        fi
+    done
+fi
+
+if ! $mpi_lib_found && ! $mpi_found; then
+    print_test FAIL "MPI libraries available" "No MPI installation detected"
+    print_test INFO "Fix (conda)" "mamba install -c conda-forge mpich or openmpi"
+    print_test INFO "Fix (system)" "Install OpenMPI or MPICH via package manager"
+fi
+
+echo ""
+
 # ========================================
 # Test 3: Check Fortran compiler
 # ========================================

.github/test-examples.sh

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025 Helmholtz-Zentrum Hereon
+# SPDX-License-Identifier: CC0-1.0
+#
+# Example: How to use the CMake test framework
+
+# This script demonstrates typical usage patterns for the test framework
+
+echo "=========================================="
+echo "CMake Test Framework - Usage Examples"
+echo "=========================================="
+echo ""
+
+# Example 1: Basic test (assumes env vars are set)
+echo "Example 1: Basic Test"
+echo "---------------------"
+echo "Prerequisites: ESMFMKFILE and SCHISM_BUILD_DIR must be set"
+echo ""
+echo "Command:"
+echo "  .github/test-cmake-instructions.sh"
+echo ""
+
+# Example 2: Set env vars inline
+echo "Example 2: Set Environment Variables Inline"
+echo "--------------------------------------------"
+echo "Command:"
+echo "  ESMFMKFILE=/opt/esmf/lib/esmf.mk \\"
+echo "  SCHISM_BUILD_DIR=/path/to/schism/build \\"
+echo "  .github/test-cmake-instructions.sh"
+echo ""
+
+# Example 3: macOS with explicit compilers
+echo "Example 3: macOS with Homebrew Compilers"
+echo "-----------------------------------------"
+echo "Command:"
+echo "  export CMAKE_Fortran_COMPILER=\$(brew --prefix gcc)/bin/gfortran"
+echo "  export CMAKE_C_COMPILER=\$(brew --prefix gcc)/bin/gcc"
+echo "  export ESMFMKFILE=/opt/esmf/lib/esmf.mk"
+echo "  export SCHISM_BUILD_DIR=~/schism/build"
+echo "  .github/test-cmake-instructions.sh"
+echo ""
+
+# Example 4: Run only environment checks (skip CMake config)
+echo "Example 4: Quick Environment Check"
+echo "-----------------------------------"
+echo "To check only env vars without running CMake config,"
+echo "temporarily unset one of the required variables:"
+echo ""
+echo "Command:"
+echo "  SCHISM_BUILD_DIR=/nonexistent \\"
+echo "  .github/test-cmake-instructions.sh"
+echo ""
+
+# Example 5: Integration with build script
+echo "Example 5: Integration with Build Script"
+echo "-----------------------------------------"
+echo "#!/usr/bin/env bash"
+echo "set -e"
+echo ""
+echo "# Validate environment before building"
+echo ".github/test-cmake-instructions.sh"
+echo ""
+echo "# If tests pass, proceed with build"
+echo "mkdir -p build && cd build"
+echo "cmake .."
+echo "cmake --build . -- -j\$(nproc)"
+echo ""
+
+# Example 6: CI/CD usage
+echo "Example 6: CI/CD Integration"
+echo "-----------------------------"
+echo "In your CI config file:"
+echo ""
+echo "GitHub Actions:"
+echo "  - name: Validate build environment"
+echo "    run: .github/test-cmake-instructions.sh"
+echo "    env:"
+echo "      ESMFMKFILE: \${{ env.ESMFMKFILE }}"
+echo "      SCHISM_BUILD_DIR: \${{ env.SCHISM_BUILD_DIR }}"
+echo ""
+echo "GitLab CI:"
+echo "  test:"
+echo "    script:"
+echo "      - .github/test-cmake-instructions.sh"
+echo ""
+
+echo "=========================================="
+echo "For more details, see:"
+echo "  .github/TEST_README.md"
+echo "=========================================="

.github/workflows/docs.yml

@@ -0,0 +1,74 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main, cmake ]
+  pull_request:
+    branches: [ main, cmake ]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build-docs-cmake:
+    name: "CMake docs build (DOCS_ONLY)"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install doc dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material
+
+      - name: Configure (DOCS_ONLY)
+        run: |
+          cmake -S . -B build -DDOCS_ONLY=ON -DBUILD_DOCS=ON
+
+      - name: Build docs target
+        run: |
+          cmake --build build --target docs -- -j2
+
+      - name: Archive built site (from CMake)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: cmake-docs-site
+          path: build/docs
+
+  deploy-docs:
+    name: "Deploy MkDocs site to GitHub Pages"
+    needs: build-docs-cmake
+    if: github.event_name == 'push' && contains('refs/heads/main refs/heads/cmake', github.ref)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install doc dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs mkdocs-material
+
+      - name: Build MkDocs site
+        run: mkdocs build --strict
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          publish_branch: gh-pages
+          force_orphan: true