Code Documentation Base Template

.github/scripts/build_and_run_tutorials.sh

@@ -0,0 +1,158 @@
+#!/bin/bash
+#
+# Build and run all C++ tutorials in the tutorial/ directory.
+# Captures stdout and artifacts into docs/_tutorial_outputs/<tutorial>/ for inclusion in Sphinx docs.
+#
+# Usage: .github/scripts/build_and_run_tutorials.sh
+#
+# This script is called by the CI workflow (.github/workflows/docs.yaml) before building docs.
+# It can also be run locally to test tutorial rendering.
+#
+
+set -e
+set -o pipefail  # Make pipelines fail if any command fails
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+TUTORIAL_BASE_DIR="$REPO_ROOT/tutorial"
+DOCS_OUTPUT_DIR="$REPO_ROOT/docs/_tutorial_outputs"
+STATIC_OUTPUT_DIR="$REPO_ROOT/docs/_static/tutorials"
+BUILD_BASE_DIR="$REPO_ROOT/build/docs_tutorials"
+
+# Create output directories
+mkdir -p "$DOCS_OUTPUT_DIR"
+mkdir -p "$STATIC_OUTPUT_DIR"
+
+# Counter for reporting
+TUTORIAL_COUNT=0
+BUILT_COUNT=0
+FAILED_COUNT=0
+
+echo "=========================================="
+echo "Building and running C++ tutorials..."
+echo "=========================================="
+echo "Repo root: $REPO_ROOT"
+echo "Tutorial dir: $TUTORIAL_BASE_DIR"
+echo "Output dir: $DOCS_OUTPUT_DIR"
+echo ""
+
+# Iterate over each tutorial subdirectory
+if [ ! -d "$TUTORIAL_BASE_DIR" ]; then
+  echo "Warning: tutorial directory not found at $TUTORIAL_BASE_DIR"
+  echo "Skipping tutorial builds."
+  exit 0
+fi
+
+for tutorial_dir in "$TUTORIAL_BASE_DIR"/*; do
+  if [ ! -d "$tutorial_dir" ]; then
+    continue
+  fi
+
+  tutorial_name=$(basename "$tutorial_dir")
+
+  # Check if CMakeLists.txt exists
+  if [ ! -f "$tutorial_dir/CMakeLists.txt" ]; then
+    echo "Skipping $tutorial_name (no CMakeLists.txt found)"
+    continue
+  fi
+
+  TUTORIAL_COUNT=$((TUTORIAL_COUNT + 1))
+  echo ""
+  echo "--- Building tutorial: $tutorial_name ---"
+
+  BUILD_DIR="$BUILD_BASE_DIR/$tutorial_name"
+  OUTPUT_DIR="$DOCS_OUTPUT_DIR/$tutorial_name"
+
+  # Clean and create build directory
+  rm -rf "$BUILD_DIR"
+  mkdir -p "$BUILD_DIR"
+  mkdir -p "$OUTPUT_DIR"
+
+  # Configure CMake
+  echo "Configuring CMake..."
+  CMAKE_ARGS=(
+    -S "$tutorial_dir"
+    -B "$BUILD_DIR"
+    -DCMAKE_BUILD_TYPE=Release
+  )
+
+  # Add mito_DIR if we can find it
+  if [ -d "/usr/local/mito/share/cmake/mito" ]; then
+    CMAKE_ARGS+=(-Dmito_DIR=/usr/local/mito/share/cmake/mito)
+  fi
+
+  # Add pyre_DIR for CI environment
+  if [ -d "/tmp/pyre-install/share/cmake/pyre" ]; then
+    CMAKE_ARGS+=(-Dpyre_DIR=/tmp/pyre-install/share/cmake/pyre)
+  fi
+
+  if ! cmake "${CMAKE_ARGS[@]}" 2>&1 | tail -20; then
+    echo "Error: CMake configuration failed for $tutorial_name"
+    FAILED_COUNT=$((FAILED_COUNT + 1))
+    continue
+  fi
+
+  # Build
+  echo "Building..."
+  if ! cmake --build "$BUILD_DIR" -- -j$(nproc) 2>&1 | tail -20; then
+    echo "Error: Build failed for $tutorial_name"
+    FAILED_COUNT=$((FAILED_COUNT + 1))
+    continue
+  fi
+
+  # Find and run the executable
+  if [ -x "$BUILD_DIR/main" ]; then
+    exe="$BUILD_DIR/main"
+  else
+    # Try to find the first executable in the build directory
+    exe=$(find "$BUILD_DIR" -maxdepth 1 -type f -executable | head -n 1 || echo "")
+  fi
+
+  if [ -n "$exe" ] && [ -x "$exe" ]; then
+    BUILT_COUNT=$((BUILT_COUNT + 1))
+    echo "Running: $exe"
+    # Run with timeout (300 seconds) and capture output
+    if timeout 300 "$exe" > "$OUTPUT_DIR/output.txt" 2>&1; then
+      echo "✓ Successfully ran $tutorial_name"
+    else
+      EXIT_CODE=$?
+      if [ $EXIT_CODE -eq 124 ]; then
+        echo "⚠ Tutorial $tutorial_name timed out (>300 seconds)"
+        echo "Timeout error" > "$OUTPUT_DIR/output.txt"
+      else
+        echo "⚠ Tutorial $tutorial_name exited with code $EXIT_CODE"
+      fi
+    fi
+  else
+    echo "Error: No executable found for $tutorial_name"
+    FAILED_COUNT=$((FAILED_COUNT + 1))
+  fi
+
+  # Copy generated artifacts (VTU, PNG, etc.) to output directory
+  echo "Copying artifacts..."
+  find "$BUILD_DIR" -maxdepth 2 -type f \( -name "*.vtu" -o -name "*.pvtu" -o -name "*.png" -o -name "*.pdf" \) -exec cp -t "$OUTPUT_DIR" -- {} + 2>/dev/null || true
+
+  # Also copy to _static for direct image serving
+  find "$BUILD_DIR" -maxdepth 2 -type f \( -name "*.png" -o -name "*.svg" \) -exec cp -t "$STATIC_OUTPUT_DIR" -- {} + 2>/dev/null || true
+
+done
+
+echo ""
+echo "=========================================="
+echo "Tutorial build summary:"
+echo "  Total tutorials found: $TUTORIAL_COUNT"
+echo "  Successfully built: $BUILT_COUNT"
+echo "  Failed: $FAILED_COUNT"
+echo "  Outputs saved to: $DOCS_OUTPUT_DIR"
+echo "=========================================="
+
+# Make outputs readable by web server
+chmod -R a+r "$DOCS_OUTPUT_DIR" || true
+
+# Exit with error if any tutorial failed
+if [ $FAILED_COUNT -gt 0 ]; then
+  echo ""
+  echo "Error: $FAILED_COUNT tutorial(s) failed to build"
+  exit 1
+fi
+
+exit 0

.github/workflows/docs.yaml

@@ -0,0 +1,177 @@
+# -*- yaml -*-
+#
+# Copyright (c) 2020-2026, the MiTo Authors, all rights reserved
+#
+
+name: documentation
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    if: github.ref != 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz build-essential cmake gcc-14 g++-14
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Python dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          pip install 'numpy<2.0' pybind11
+
+      - name: Checkout pyre
+        uses: actions/checkout@v4
+        with:
+          repository: pyre/pyre
+          ref: tensor
+          fetch-depth: 0
+          path: pyre-src
+
+      - name: Build and install pyre
+        run: |
+          mkdir -p pyre-build
+          cd pyre-build
+          cmake -DCMAKE_INSTALL_PREFIX=/tmp/pyre-install \
+                -DCMAKE_BUILD_TYPE=Release \
+                -DCMAKE_C_COMPILER=gcc-14 \
+                -DCMAKE_CXX_COMPILER=g++-14 \
+                -DPython_ROOT_DIR=$pythonLocation \
+                -Dpybind11_DIR=$(python3 -c "import pybind11; print(pybind11.get_cmake_dir())") \
+                ../pyre-src
+          make -j$(nproc)
+          make install
+
+      - name: Build and install mito
+        run: |
+          mkdir -p build
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=Release \
+                -DCMAKE_INSTALL_PREFIX=/usr/local/mito \
+                -DCMAKE_CXX_COMPILER=g++-14 \
+                -DMITO_BUILD_TESTING=OFF \
+                -DMITO_BUILD_BENCHMARKS=OFF \
+                -DWITH_MPI=OFF \
+                -DWITH_VTK=OFF \
+                -DWITH_PETSC=OFF \
+                -Dpyre_DIR=/tmp/pyre-install/share/cmake/pyre \
+                -Dpybind11_DIR=$(python3 -c "import pybind11; print(pybind11.get_cmake_dir())") \
+                ..
+          make -j$(nproc)
+          sudo make install
+
+      - name: Build and run C++ tutorials
+        run: chmod +x .github/scripts/build_and_run_tutorials.sh && .github/scripts/build_and_run_tutorials.sh
+
+      - name: Build documentation
+        run: |
+          cd docs
+          doxygen Doxyfile
+          make html
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/build/html
+          retention-days: 2
+
+  build-and-deploy:
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz build-essential cmake gcc-14 g++-14
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Python dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          pip install -r docs/requirements.txt
+          pip install 'numpy<2.0' pybind11
+
+      - name: Checkout pyre
+        uses: actions/checkout@v4
+        with:
+          repository: pyre/pyre
+          ref: tensor
+          fetch-depth: 0
+          path: pyre-src
+
+      - name: Build and install pyre
+        run: |
+          mkdir -p pyre-build
+          cd pyre-build
+          cmake -DCMAKE_INSTALL_PREFIX=/tmp/pyre-install \
+                -DCMAKE_BUILD_TYPE=Release \
+                -DCMAKE_C_COMPILER=gcc-14 \
+                -DCMAKE_CXX_COMPILER=g++-14 \
+                -DPython_ROOT_DIR=$pythonLocation \
+                -Dpybind11_DIR=$(python3 -c "import pybind11; print(pybind11.get_cmake_dir())") \
+                ../pyre-src
+          make -j$(nproc)
+          make install
+
+      - name: Build and install mito
+        run: |
+          mkdir -p build
+          cd build
+          cmake -DCMAKE_BUILD_TYPE=Release \
+                -DCMAKE_INSTALL_PREFIX=/usr/local/mito \
+                -DCMAKE_CXX_COMPILER=g++-14 \
+                -DMITO_BUILD_TESTING=OFF \
+                -DMITO_BUILD_BENCHMARKS=OFF \
+                -DWITH_MPI=OFF \
+                -DWITH_VTK=OFF \
+                -DWITH_PETSC=OFF \
+                -Dpyre_DIR=/tmp/pyre-install/share/cmake/pyre \
+                -Dpybind11_DIR=$(python3 -c "import pybind11; print(pybind11.get_cmake_dir())") \
+                ..
+          make -j$(nproc)
+          sudo make install
+
+      - name: Build and run C++ tutorials
+        run: chmod +x .github/scripts/build_and_run_tutorials.sh && .github/scripts/build_and_run_tutorials.sh
+
+      - name: Build documentation
+        run: |
+          cd docs
+          doxygen Doxyfile
+          make html
+
+      - name: Set up Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -9,3 +9,10 @@ __pycache__*/
 *.vtu
 *.pvtu
 *.msh
+html/
+latex/
+xml/
+
+# docs tutorial outputs (generated by CI)
+/docs/_tutorial_outputs/
+/build/docs_tutorials/