merge from upstream master

Author: conraddelgado

.github/workflows/docs.yml

@@ -21,7 +21,7 @@ jobs:
     - name: Build Doxygen
       run:  |
         sudo apt update -y
-        sudo apt install -y cmake ninja-build graphviz graphviz
+        sudo apt install -y cmake ninja-build graphviz texlive-binaries
         git clone https://github.com/doxygen/doxygen.git ../doxygen
         cd ../doxygen
         git checkout Release_1_16_1

.github/workflows/lint-toolchain.yml

@@ -42,5 +42,21 @@ jobs:
 
     - name: Validate example cases
       run: |
-        ./mfc.sh validate examples/1D_sodshocktube/case.py
-        ./mfc.sh validate examples/2D_shockbubble/case.py
+        failed=0
+        passed=0
+        for case in examples/*/case.py; do
+          [ -f "$case" ] || continue
+          output=$(./mfc.sh validate "$case" 2>&1)
+          if [ $? -eq 0 ]; then
+            passed=$((passed + 1))
+          else
+            echo "FAIL: $case"
+            echo "$output"
+            failed=$((failed + 1))
+          fi
+        done
+        echo ""
+        echo "Results: $passed passed, $failed failed"
+        if [ "$failed" -ne 0 ]; then
+          exit 1
+        fi

.github/workflows/test.yml

@@ -49,6 +49,9 @@ jobs:
         run: |
           ! grep -iR -e '\.\.\.' -e '\-\-\-' -e '===' ./src/*
 
+      - name: Lint Docs
+        run: python3 toolchain/mfc/lint_docs.py
+
   file-changes:
     name: Detect File Changes
     runs-on: 'ubuntu-latest'

.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/*

.pr_agent.toml

@@ -1,7 +1,12 @@
 # .pr_agent.toml
 [github_app]
-# Run these tools automatically on every new PR:
-pr_commands = ["/describe", "/review", "/improve"]
+pr_commands = [
+  "/review",
+  "/improve",
+]
+
+handle_push_trigger = true
+push_commands = ["/improve"]
 
 [pr_reviewer]                # (all fields optional)
 num_max_findings        = 10  # how many items to surface

.typos.toml

@@ -30,4 +30,4 @@ unknwn = "unknwn"     # typo for "unknown" - tests unknown param detection
 tru = "tru"           # typo for "true" in "when_tru" - tests dependency keys
 
 [files]
-extend-exclude = ["docs/documentation/references*", "tests/", "toolchain/cce_simulation_workgroup_256.sh", "build-docs/"]
+extend-exclude = ["docs/documentation/references*", "docs/references.bib", "tests/", "toolchain/cce_simulation_workgroup_256.sh", "build-docs/"]

CMakeLists.txt

@@ -660,16 +660,19 @@ if (MFC_DOCUMENTATION)
         VERBATIM
     )
 
-    # Generate case_constraints.md from case_validator.py and examples/
+    # Generate case_constraints.md and physics_constraints.md together.
+    # Both are produced by gen_constraints.sh, so a single command avoids races.
     add_custom_command(
         OUTPUT  "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/case_constraints.md"
+                "${CMAKE_CURRENT_SOURCE_DIR}/docs/documentation/physics_constraints.md"
         DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/gen_case_constraints_docs.py"
+                "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/gen_physics_docs.py"
                 "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/case_validator.py"
                 "${CMAKE_CURRENT_SOURCE_DIR}/toolchain/mfc/params/definitions.py"
                 "${examples_DOCs}"
         COMMAND "bash" "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_constraints.sh"
                        "${CMAKE_CURRENT_SOURCE_DIR}"
-        COMMENT "Generating case_constraints.md"
+        COMMENT "Generating case_constraints.md and physics_constraints.md"
         VERBATIM
     )
 
@@ -720,6 +723,7 @@ if (MFC_DOCUMENTATION)
         set(DOXYGEN_HTML_OUTPUT      "\"${CMAKE_CURRENT_BINARY_DIR}/${target}\"")
         set(DOXYGEN_MATHJAX_CODEFILE "\"${CMAKE_CURRENT_SOURCE_DIR}/docs/config.js\"")
         set(DOXYGEN_PROJECT_LOGO     "\"${CMAKE_CURRENT_SOURCE_DIR}/docs/res/icon.ico\"")
+        set(DOXYGEN_CITE_BIB_FILES   "\"${CMAKE_CURRENT_SOURCE_DIR}/docs/references.bib\"")
         set(DOXYGEN_IMAGE_PATH       "\"${CMAKE_CURRENT_SOURCE_DIR}/docs/res\"\
                                       \"${CMAKE_CURRENT_SOURCE_DIR}/docs/${target}\"")
 
@@ -731,11 +735,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()
@@ -748,10 +754,13 @@ 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}"
             COMMAND "${DOXYGEN_EXECUTABLE}" "${target}-Doxyfile"
+            COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/postprocess_citations.py"
+                    "${CMAKE_CURRENT_BINARY_DIR}/${target}"
             WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}"
             COMMENT "${target}: Generating documentation"
         )
@@ -771,6 +780,7 @@ if (MFC_DOCUMENTATION)
     add_custom_target(documentation)
 
     find_package(Doxygen REQUIRED dot REQUIRED)
+    find_package(Python3 REQUIRED COMPONENTS Interpreter)
 
     # > Fetch CSS Theme
     ExternalProject_Add(doxygen-awesome-css

docs/Doxyfile.in

@@ -35,7 +35,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "@DOXYGEN_PROJECT_NAME@"
+PROJECT_NAME           = @DOXYGEN_PROJECT_NAME@
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -740,7 +740,7 @@ LAYOUT_FILE            =
 # LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the
 # search path. See also \cite for info how to create references.
 
-CITE_BIB_FILES         =
+CITE_BIB_FILES         = @DOXYGEN_CITE_BIB_FILES@
 
 #---------------------------------------------------------------------------
 # Configuration options related to warning and progress messages
@@ -970,7 +970,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE = readme.md
+USE_MDFILE_AS_MAINPAGE =
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -1205,14 +1205,6 @@ HTML_COLORSTYLE_SAT    = 255
 
 HTML_COLORSTYLE_GAMMA  = 113
 
-# If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML
-# page will contain the date and time when the page was generated. Setting this
-# to YES can help to show when doxygen was last run and thus if the
-# documentation is up to date.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_HTML is set to YES.
-
-HTML_TIMESTAMP         = NO
 
 # If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML
 # documentation will contain a main index with vertical navigation menus that
@@ -1801,13 +1793,6 @@ LATEX_HIDE_INDICES     = NO
 
 LATEX_BIB_STYLE        = plain
 
-# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated
-# page will contain the date and time when the page was generated. Setting this
-# to NO can help when comparing the output of multiple runs.
-# The default value is: NO.
-# This tag requires that the tag GENERATE_LATEX is set to YES.
-
-LATEX_TIMESTAMP        = NO
 
 # The LATEX_EMOJI_DIRECTORY tag is used to specify the (relative or absolute)
 # path from which the emoji images will be read. If a relative path is entered,

docs/custom.css

@@ -3,6 +3,22 @@
  * Overrides for doxygen-awesome theme
  */
 
+/* Seamless split <code> tags for Fortran % struct accessors.
+ * Doxygen consumes %<word> even inside code spans, so we split around %
+ * into adjacent <code> elements and remove internal borders/padding. */
+code.f90l {
+    border-right: 0;
+    border-top-right-radius: 0;
+    border-bottom-right-radius: 0;
+    padding-right: 0;
+}
+code.f90r {
+    border-left: 0;
+    border-top-left-radius: 0;
+    border-bottom-left-radius: 0;
+    padding-left: 0;
+}
+
 /* Fix inline code visibility in colored admonition blocks (warning, attention, important, note, etc.) */
 
 /* Warning/Attention/Important blocks (red/pink background) */