Strengthen doc linter with new Doxygen rendering checks

Add three new checks to lint_docs.py:
- check_unpaired_math: catches unpaired \f$ delimiters and unbalanced
  \f[/\f] display math blocks that break all subsequent rendering
- check_doxygen_commands_in_backticks: catches Doxygen @ and \ block
  commands inside backtick code spans (known Doxygen bug #6054)
- check_single_quote_in_backtick: catches single quotes in single-
  backtick spans which Doxygen treats as ending the span

Fix 7 pre-existing single-quote issues found by the new check in
case.md, contributing.md, and testing.md (use double backticks).

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

Author: sbryngelson

docs/documentation/case.md

@@ -298,7 +298,7 @@ These physical parameters must be consistent with fluid material's parameters de
 #### Elliptic Smoothing
 
 Initial conditions in which not all patches support the `patch_icpp(j)%%smoothen` parameter can still be smoothed by applying iterations of the heat equation to the initial condition.
-This is enabled by adding `'elliptic_smoothing': "T",` and `'elliptic_smoothing_iters': N,` to the case dictionary, where `N` is the number of smoothing iterations to apply.
+This is enabled by adding ``'elliptic_smoothing': "T",`` and ``'elliptic_smoothing_iters': N,`` to the case dictionary, where `N` is the number of smoothing iterations to apply.
 
 ### 4. Immersed Boundary Patches {#sec-immersed-boundary-patches}
 
@@ -658,7 +658,7 @@ If `file_per_process` is true, then pre_process, simulation, and post_process mu
 
 - `cons_vars_wrt` and `prim_vars_wrt` activate the output of conservative and primitive state variables into the database.
 
-- `[variable's name]_wrt` activates the output of each specified variable into the database.
+- ``[variable's name]_wrt`` activates the output of each specified variable into the database.
 
 - `schlieren_alpha(i)` specifies the intensity of the numerical Schlieren of $i$-th component.
 
@@ -898,11 +898,11 @@ The parameters are optionally used to define initial velocity profiles and pertu
 
 - `mixlayer_vel_profile` activates setting the mean streamwise velocity to a hyperbolic tangent profile. This option works only for `n > 0`.
 
-- `mixlayer_vel_coef` is a parameter for the hyperbolic tangent profile of a mixing layer when `mixlayer_vel_profile = 'T'`. The mean streamwise velocity profile is given as:
+- `mixlayer_vel_coef` is a parameter for the hyperbolic tangent profile of a mixing layer when ``mixlayer_vel_profile = 'T'``. The mean streamwise velocity profile is given as:
 
 \f[ u = \text{patch\_icpp(1)\%vel(1)} \cdot \tanh( y_{cc} \cdot \text{mixlayer\_vel\_coef}) \f]
 
-- `mixlayer_perturb` activates the velocity perturbation for a temporal mixing layer with hyperbolic tangent mean streamwise velocity profile, using an inverter version of the spectrum-based synthetic turbulence generation method proposed by \cite Guo23. This option only works for `p > 0` and `mixlayer_vel_profile = 'T'`.
+- `mixlayer_perturb` activates the velocity perturbation for a temporal mixing layer with hyperbolic tangent mean streamwise velocity profile, using an inverter version of the spectrum-based synthetic turbulence generation method proposed by \cite Guo23. This option only works for `p > 0` and ``mixlayer_vel_profile = 'T'``.
 
 ### 11. Phase Change Model {#sec-phase-change}
 | Parameter              | Type    | Description                                    |

docs/documentation/contributing.md

@@ -380,7 +380,7 @@ $:END_GPU_PARALLEL_LOOP()
 Key rules:
 - Always pair `$:GPU_PARALLEL_LOOP(...)` with `$:END_GPU_PARALLEL_LOOP()`
 - Use `collapse(n)` to fuse nested loops when the loop bounds are independent
-- Declare all loop-local temporaries in `private='[...]'`
+- Declare all loop-local temporaries in ``private='[...]'``
 - Never use `stop` or `error stop` inside a GPU loop
 
 ### How to Allocate and Manage GPU Arrays

docs/documentation/testing.md

@@ -99,7 +99,7 @@ To test the post-processing code, append the `-a` or `--test-all` option:
 ./mfc.sh test -a -j 8
 ```
 
-This argument will re-run the test stack with `parallel_io='T'`, which generates silo_hdf5 files.
+This argument will re-run the test stack with ``parallel_io='T'``, which generates silo_hdf5 files.
 It will also turn most write parameters (`*_wrt`) on.
 Then, it searches through the silo files using `h5dump` to ensure that there are no `NaN`s or `Infinity`s.
 Although adding this option does not guarantee that accurate `.silo` files are generated, it does ensure that the post-process code does not fail or produce malformed data.

toolchain/mfc/lint_docs.py

@@ -549,6 +549,165 @@ def check_cli_refs(repo_root: Path) -> list[str]:
     return errors
 
 
+def check_unpaired_math(repo_root: Path) -> list[str]:
+    """Check for unpaired \\f$ inline math and unbalanced \\f[/\\f] display math."""
+    doc_dir = repo_root / "docs" / "documentation"
+    if not doc_dir.exists():
+        return []
+
+    ignored = _gitignored_docs(repo_root)
+    errors = []
+
+    for md_file in sorted(doc_dir.glob("*.md")):
+        if md_file.name in ignored:
+            continue
+        text = md_file.read_text(encoding="utf-8")
+        rel = md_file.relative_to(repo_root)
+        in_code = False
+        display_math_open = 0  # line number where \f[ was opened, 0 = closed
+
+        for i, line in enumerate(text.split("\n"), 1):
+            if line.strip().startswith("```"):
+                in_code = not in_code
+                continue
+            if in_code:
+                continue
+
+            # Count \f$ occurrences (should be even per line for inline math)
+            inline_count = len(re.findall(r"\\f\$", line))
+            if inline_count % 2 != 0:
+                errors.append(
+                    f"  {rel}:{i} has {inline_count} \\f$ delimiter(s) (odd)."
+                    " Fix: ensure every \\f$ has a matching closing \\f$"
+                )
+
+            # Track \f[ / \f] balance
+            opens = len(re.findall(r"\\f\[", line))
+            closes = len(re.findall(r"\\f\]", line))
+            for _ in range(opens):
+                if display_math_open:
+                    errors.append(
+                        f"  {rel}:{i} opens \\f[ but previous \\f["
+                        f" from line {display_math_open} is still open."
+                        " Fix: add missing \\f]"
+                    )
+                display_math_open = i
+            for _ in range(closes):
+                if not display_math_open:
+                    errors.append(
+                        f"  {rel}:{i} has \\f] without a preceding \\f[."
+                        " Fix: add missing \\f[ or remove extra \\f]"
+                    )
+                else:
+                    display_math_open = 0
+
+        if display_math_open:
+            errors.append(
+                f"  {rel}:{display_math_open} opens \\f[ that is never closed."
+                " Fix: add \\f] to close the display math block"
+            )
+
+    return errors
+
+
+# Doxygen block commands that are incorrectly processed inside backtick
+# code spans (known Doxygen bug, see github.com/doxygen/doxygen/issues/6054).
+_DOXYGEN_BLOCK_CMDS = {
+    "code", "endcode", "verbatim", "endverbatim",
+    "dot", "enddot", "msc", "endmsc",
+    "startuml", "enduml",
+    "latexonly", "endlatexonly", "htmlonly", "endhtmlonly",
+    "xmlonly", "endxmlonly", "rtfonly", "endrtfonly",
+    "manonly", "endmanonly", "docbookonly", "enddocbookonly",
+    "todo", "deprecated", "bug", "test",
+    "note", "warning", "attention", "remark",
+    "brief", "details", "param", "return", "returns",
+}
+
+
+def check_doxygen_commands_in_backticks(repo_root: Path) -> list[str]:
+    """Check for Doxygen @/\\ commands inside backtick code spans.
+
+    Doxygen processes certain block commands even inside backtick code
+    spans, which can break rendering.  Flag these so authors can
+    restructure or use fenced code blocks instead.
+    """
+    doc_dir = repo_root / "docs" / "documentation"
+    if not doc_dir.exists():
+        return []
+
+    ignored = _gitignored_docs(repo_root)
+    code_span_re = re.compile(r"``([^`\n]+)``|`([^`\n]+)`")
+    # Match @cmd or \cmd where cmd is a known Doxygen block command
+    cmd_pattern = "|".join(re.escape(c) for c in sorted(_DOXYGEN_BLOCK_CMDS))
+    doxy_cmd_re = re.compile(rf"(?:@|\\)({cmd_pattern})\b")
+
+    errors = []
+    for md_file in sorted(doc_dir.glob("*.md")):
+        if md_file.name in ignored:
+            continue
+        text = md_file.read_text(encoding="utf-8")
+        rel = md_file.relative_to(repo_root)
+        in_code = False
+        for i, line in enumerate(text.split("\n"), 1):
+            if line.strip().startswith("```"):
+                in_code = not in_code
+                continue
+            if in_code:
+                continue
+            for m in code_span_re.finditer(line):
+                span = m.group(1) or m.group(2)
+                cmd_match = doxy_cmd_re.search(span)
+                if cmd_match:
+                    cmd = cmd_match.group(0)
+                    errors.append(
+                        f"  {rel}:{i} backtick span contains Doxygen"
+                        f" command '{cmd}' which may be processed."
+                        " Fix: use a fenced code block or rephrase"
+                    )
+
+    return errors
+
+
+def check_single_quote_in_backtick(repo_root: Path) -> list[str]:
+    """Check for single quotes inside single-backtick code spans.
+
+    Doxygen treats a single quote inside a single-backtick code span as
+    ending the span (backward-compat quirk).  Use double backticks instead.
+    """
+    doc_dir = repo_root / "docs" / "documentation"
+    if not doc_dir.exists():
+        return []
+
+    ignored = _gitignored_docs(repo_root)
+    # Match single-backtick spans (not double-backtick)
+    single_bt_re = re.compile(r"(?<!`)`([^`\n]+)`(?!`)")
+
+    errors = []
+    for md_file in sorted(doc_dir.glob("*.md")):
+        if md_file.name in ignored:
+            continue
+        text = md_file.read_text(encoding="utf-8")
+        rel = md_file.relative_to(repo_root)
+        in_code = False
+        for i, line in enumerate(text.split("\n"), 1):
+            if line.strip().startswith("```"):
+                in_code = not in_code
+                continue
+            if in_code:
+                continue
+            for m in single_bt_re.finditer(line):
+                span = m.group(1)
+                if "'" in span:
+                    errors.append(
+                        f"  {rel}:{i} single-backtick span `{span}` contains"
+                        " a single quote, which Doxygen treats as ending the"
+                        f" span. Fix: use double backticks ``{span}``"
+                    )
+
+    return errors
+
+
 def main():
     repo_root = Path(__file__).resolve().parents[2]
 
@@ -558,7 +717,10 @@ def main():
     all_errors.extend(check_param_refs(repo_root))
     all_errors.extend(check_page_refs(repo_root))
     all_errors.extend(check_math_syntax(repo_root))
+    all_errors.extend(check_unpaired_math(repo_root))
     all_errors.extend(check_doxygen_percent(repo_root))
+    all_errors.extend(check_doxygen_commands_in_backticks(repo_root))
+    all_errors.extend(check_single_quote_in_backtick(repo_root))
     all_errors.extend(check_section_anchors(repo_root))
     all_errors.extend(check_physics_docs_coverage(repo_root))
     all_errors.extend(check_identifier_refs(repo_root))