Auto-generate physics_constraints.md from PHYSICS_DOCS metadata

Replace the hand-written physics constraints page with an auto-generated
one that merges PHYSICS_DOCS entries (math, explanations, references) with
AST-extracted validation rules (stages, severity, messages). This prevents
the documentation from going stale when check methods are added or modified.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sbryngelson

.gitignore

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

CMakeLists.txt

@@ -673,6 +673,17 @@ if (MFC_DOCUMENTATION)
         VERBATIM
     )
 
+    # Generate physics_constraints.md from PHYSICS_DOCS + AST-extracted rules
+    add_custom_command(
+        OUTPUT  "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/physics_constraints.md"
+        DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/gen_physics_docs.py"
+                "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/case_validator.py"
+        COMMAND "bash" "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_constraints.sh"
+                       "${CMAKE_CURRENT_SOURCE_DIR}"
+        COMMENT "Generating physics_constraints.md"
+        VERBATIM
+    )
+
     # Generate cli-reference.md from cli/commands.py
     add_custom_command(
         OUTPUT  "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/cli-reference.md"
@@ -732,11 +743,13 @@ if (MFC_DOCUMENTATION)
 
         set(opt_example_dependency "")
         set(opt_constraints_dependency "")
+        set(opt_physics_dependency "")
         set(opt_cli_reference_dependency "")
         set(opt_parameters_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")
+            set(opt_physics_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/physics_constraints.md")
             set(opt_cli_reference_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/cli-reference.md")
             set(opt_parameters_dependency "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/parameters.md")
         endif()
@@ -749,6 +762,7 @@ if (MFC_DOCUMENTATION)
             DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${target}-Doxyfile"
                     "${opt_example_dependency}"
                     "${opt_constraints_dependency}"
+                    "${opt_physics_dependency}"
                     "${opt_cli_reference_dependency}"
                     "${opt_parameters_dependency}"
                     "${${target}_SRCs}" "${${target}_DOCs}"

docs/documentation/contributing.md

@@ -274,6 +274,8 @@ def check_my_feature(self):
         self.errors.append("my_param requires other_param to be set")
 ```
 
+If your check enforces a physics constraint, also add a `PHYSICS_DOCS` entry (see [How to Document Physics Constraints](#how-to-document-physics-constraints) below).
+
 **Step 5: Declare in Fortran** (`src/<target>/m_global_parameters.fpp`)
 
 Add the variable declaration in the appropriate target's global parameters module. Choose the target(s) where the parameter is used:
@@ -659,6 +661,41 @@ Checklist:
 
 See @ref troubleshooting for debugging workflows, profiling tools, GPU diagnostic environment variables, common build/runtime errors, and fixes.
 
+### How to Document Physics Constraints {#how-to-document-physics-constraints}
+
+When adding a new `check_` method to `case_validator.py`, document its physics by adding an entry to the `PHYSICS_DOCS` dict at the top of the file:
+
+```python
+PHYSICS_DOCS = {
+    ...
+    "check_my_feature": {
+        "title": "My Feature Constraint",          # Required: human-readable title
+        "category": "Thermodynamic Constraints",    # Required: groups the constraint in docs
+        "explanation": "Why this constraint exists.", # Required: plain English
+        "math": r"\alpha > 0",                      # Optional: LaTeX formula
+        "references": ["Wilfong26"],                # Optional: BibTeX keys from references.bib
+        "exceptions": ["IBM cases"],                # Optional: when constraint doesn't apply
+    },
+}
+```
+
+The @ref physics_constraints "Physics Constraints" page is **auto-generated** — run `./mfc.sh generate` to rebuild it.
+The generator merges your `PHYSICS_DOCS` entry with the AST-extracted `prohibit()`/`warn()` calls,
+so stage, severity, and parameter information appear automatically.
+
+**Fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Section heading in generated docs |
+| `category` | Yes | Grouping category (e.g., "Mixture Constraints") |
+| `explanation` | Yes | Plain English description of the physics |
+| `math` | No | LaTeX formula (rendered by Doxygen's MathJax) |
+| `references` | No | List of BibTeX cite keys from `docs/references.bib` |
+| `exceptions` | No | List of cases where the constraint doesn't apply |
+
+**Categories:** Thermodynamic Constraints, Mixture Constraints, Domain and Geometry, Velocity and Dimensional Consistency, Model Equations, Boundary Conditions, Bubble Physics, Feature Compatibility, Numerical Schemes, Acoustic Sources, Post-Processing.
+
 ## Testing
 
 MFC has 500+ regression tests. See @ref testing for the full guide.