Constraints (#1072)

Author: sbryngelson

.github/workflows/docs.yml

@@ -34,6 +34,14 @@ jobs:
         cmake -S . -B build -G Ninja --install-prefix=$(pwd)/build/install -D MFC_DOCUMENTATION=ON
         ninja -C build install
 
+    - name: Upload Built Documentation Artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: mfc-docs
+        path: build/install/docs/mfc
+        if-no-files-found: error
+        retention-days: 7
+
     # From here https://github.com/cicirello/generate-sitemap
     - name: Generate the sitemap
       id: sitemap

.gitignore

@@ -36,6 +36,7 @@ docs/*/initial*
 docs/*/result*
 docs/documentation/*-example.png
 docs/documentation/examples.md
+docs/documentation/case_constraints.md
 
 examples/*batch/*/
 examples/**/D/*

CMakeLists.txt

@@ -652,6 +652,18 @@ if (MFC_DOCUMENTATION)
         VERBATIM
     )
 
+    # Generate case_constraints.md from case_validator.py and examples/
+    add_custom_command(
+        OUTPUT  "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/case_constraints.md"
+        DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/gen_case_constraints_docs.py"
+                "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/case_validator.py"
+                "${examples_DOCs}"
+        COMMAND "bash" "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_constraints.sh"
+                       "${CMAKE_CURRENT_SOURCE_DIR}"
+        COMMENT "Generating case_constraints.md"
+        VERBATIM
+    )
+
     file(GLOB common_DOCs CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/docs/*")
 
     # GEN_DOCS: Given a target name (herein <target>), this macro sets up a
@@ -685,8 +697,10 @@ if (MFC_DOCUMENTATION)
             "${CMAKE_CURRENT_BINARY_DIR}/${target}-Doxyfile" @ONLY)
 
         set(opt_example_dependency "")
+        set(opt_constraints_dependency "")
         if (${target} STREQUAL documentation)
             set(opt_example_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/examples.md")
+            set(opt_constraints_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/case_constraints.md")
         endif()
 
         file(GLOB_RECURSE ${target}_DOCs CONFIGURE_DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/docs/${target}/*")
@@ -696,6 +710,7 @@ if (MFC_DOCUMENTATION)
             OUTPUT  "${CMAKE_CURRENT_BINARY_DIR}/${target}/html/index.html"
             DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${target}-Doxyfile"
                     "${opt_example_dependency}"
+                    "${opt_constraints_dependency}"
                     "${${target}_SRCs}" "${${target}_DOCs}"
             COMMAND "${DOXYGEN_EXECUTABLE}" "${target}-Doxyfile"
             WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"

docs/documentation/case.md

@@ -68,6 +68,15 @@ For example, to run the `scaling` case in "weak-scaling" mode:
 
 ## Parameters
 
+## Feature Compatibility
+
+Before diving into parameter details, check the **[Feature Compatibility Guide](case_constraints.md)** to understand:
+- Which features work together (MHD, bubbles, phase change, etc.)
+- Common configuration patterns with copy-paste examples
+- Requirements for each model equation and Riemann solver
+
+💡 **Tip:** If you get a validation error, the compatibility guide explains what each parameter requires.
+
 There are multiple sets of parameters that must be specified in the python input file:
 1. [Runtime Parameters](#1-runtime)
 2. [Computational Domain Parameters](#2-computational-domain)

docs/gen_constraints.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Generate case constraints documentation from case_validator.py
+
+set -e
+
+REPO_ROOT="$1"
+
+if [ -z "$REPO_ROOT" ]; then
+    echo "Usage: $0 <repo_root>"
+    exit 1
+fi
+
+echo "Generating case constraints documentation..."
+python3 "$REPO_ROOT/toolchain/mfc/gen_case_constraints_docs.py" > "$REPO_ROOT/docs/documentation/case_constraints.md"
+echo "✓ Generated docs/documentation/case_constraints.md"
+
+