Fix 37 broken Fortran % accessors in docs and add lint check

Doxygen silently consumes %<word> (even inside backtick code spans),
so `bc_y%beg` renders as `bc_ybeg`. Fixed all 37 instances in
hand-written docs to use %% escape. Added check_doxygen_percent()
lint check to catch this in CI going forward.

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

Author: sbryngelson

docs/documentation/case.md

@@ -297,7 +297,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.
+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.
 
 ### 4. Immersed Boundary Patches {#sec-immersed-boundary-patches}
@@ -620,8 +620,8 @@ To restart the simulation from $k$-th time step, see @ref running "Restarting Ca
 | `num_probes`            | Integer | Number of probes	|
 | `probe(i)%[x,y,z]`      | Real	  | Coordinates of probe $i$	|
 | `output_partial_domain` | Logical | Output part of the domain |
-| `[x,y,z]_output%beg`    | Real    | Beginning of the output domain in the [x,y,z]-direction |
-| `[x,y,z]_output%end`    | Real    | End of the output domain in the [x,y,z]-direction |
+| `[x,y,z]_output%%beg`    | Real    | Beginning of the output domain in the [x,y,z]-direction |
+| `[x,y,z]_output%%end`    | Real    | End of the output domain in the [x,y,z]-direction |
 | `lag_txt_wrt`           | Logical | Write Lagrangian bubble data to `.dat` files |
 | `lag_header`            | Logical | Write header to Lagrangian bubble `.dat` files |
 | `lag_db_wrt`            | Logical | Write Lagrangian bubble data to silo/hdf5 database files |
@@ -667,7 +667,7 @@ If `file_per_process` is true, then pre_process, simulation, and post_process mu
 
 - `probe_wrt` activates the output of state variables at coordinates specified by `probe(i)%[x;y,z]`.
 
-- `output_partial_domain` activates the output of part of the domain specified by `[x,y,z]_output%beg` and `[x,y,z]_output%end`.
+- `output_partial_domain` activates the output of part of the domain specified by `[x,y,z]_output%%beg` and `[x,y,z]_output%%end`.
 This is useful for large domains where only a portion of the domain is of interest.
 It is not supported when `precision = 1` and `format = 1`.
 It also cannot be enabled with `flux_wrt`, `heat_ratio_wrt`, `pres_inf_wrt`, `c_wrt`, `omega_wrt`, `ib`, `schlieren_wrt`, `qm_wrt`, or 'liutex_wrt'.
@@ -991,30 +991,30 @@ Note: For relativistic flow, the conservative and primitive densities are differ
 
 When ``cyl_coord = 'T'`` is set in 3D the following constraints must be met:
 
-- `bc_y%beg = -14`  enables the axis boundary condition
+- `bc_y%%beg = -14`  enables the axis boundary condition
 
-- `bc_z%beg = bc_z%end = -1`  enables periodic boundary conditions in the azimuthal direction
+- `bc_z%%beg = bc_z%%end = -1`  enables periodic boundary conditions in the azimuthal direction
 
-- `z_domain%beg = 0`  sets the azimuthal starting point to 0
+- `z_domain%%beg = 0`  sets the azimuthal starting point to 0
 
-- `z_domain%end = 2*math.pi` to set the azimuthal ending point to \f$2\pi\f$ (note, requires `import math` in the case file)
+- `z_domain%%end = 2*math.pi` to set the azimuthal ending point to \f$2\pi\f$ (note, requires `import math` in the case file)
 
 When ``cyl_coord = 'T'`` is set in 2D the following constraints must be met:
 
-- `bc_y%beg = -2` to enable reflective boundary conditions
+- `bc_y%%beg = -2` to enable reflective boundary conditions
 
 ### 17. Chemistry
 
 | Parameter                     | Type    | Description                                              |
 | ---:                          | :---:   | :---                                                     |
 | `chemistry`                   | Logical | Enable chemistry simulation                              |
-| `chem_params%diffusion`       | Logical | Enable multispecies diffusion                            |
-| `chem_params%reactions`       | Logical | Enable chemical reactions                                |
-| `chem_params%gamma_method`    | Integer | Methodology for calculating the heat capacity ratio      |
-| `chem_params%transport_model` | Integer | Methodology for calculating the diffusion coefficients   |
+| `chem_params%%diffusion`       | Logical | Enable multispecies diffusion                            |
+| `chem_params%%reactions`       | Logical | Enable chemical reactions                                |
+| `chem_params%%gamma_method`    | Integer | Methodology for calculating the heat capacity ratio      |
+| `chem_params%%transport_model` | Integer | Methodology for calculating the diffusion coefficients   |
 | `cantera_file`                | String  | Cantera-format mechanism file (e.g., .yaml)              |
 
-- `chem_params%transport_model` specifies the methodology for calculating diffusion coefficients and other transport properties, `1` for mixture-average, `2` for Unity-Lewis
+- `chem_params%%transport_model` specifies the methodology for calculating diffusion coefficients and other transport properties, `1` for mixture-average, `2` for Unity-Lewis
 
 - `cantera_file` specifies the chemical mechanism file. If the file is part of the standard Cantera library, only the filename is required. Otherwise, the file must be located in the same directory as your `case.py` file
 
@@ -1051,15 +1051,15 @@ The entries labeled "Characteristic." are characteristic boundary conditions bas
 
 | Parameter                     | Type    | Description |
 | ---:                          | :----:  | :--- |
-| `bc_[x,y,z]%grcbc_in`         | Logical | Enable grcbc for subsonic inflow |
-| `bc_[x,y,z]%grcbc_out`        | Logical | Enable grcbc for subsonic outflow (pressure)|
-| `bc_[x,y,z]%grcbc_vel_out`    | Logical | Enable grcbc for subsonic outflow (pressure + normal velocity) |
-| `bc_[x,y,z]%vel_in`           | Real Array | Inflow velocities in x, y and z directions |
-| `bc_[x,y,z]%vel_out`          | Real Array | Outflow velocities in x, y and z directions |
-| `bc_[x,y,z]%pres_in`          | Real    | Inflow pressure |
-| `bc_[x,y,z]%pres_out`         | Real    | Outflow pressure |
-| `bc_[x,y,z]%alpha_rho_in`     | Real Array | Inflow density |
-| `bc_[x,y,z]%alpha_in`         | Real Array | Inflow void fraction |
+| `bc_[x,y,z]%%grcbc_in`         | Logical | Enable grcbc for subsonic inflow |
+| `bc_[x,y,z]%%grcbc_out`        | Logical | Enable grcbc for subsonic outflow (pressure)|
+| `bc_[x,y,z]%%grcbc_vel_out`    | Logical | Enable grcbc for subsonic outflow (pressure + normal velocity) |
+| `bc_[x,y,z]%%vel_in`           | Real Array | Inflow velocities in x, y and z directions |
+| `bc_[x,y,z]%%vel_out`          | Real Array | Outflow velocities in x, y and z directions |
+| `bc_[x,y,z]%%pres_in`          | Real    | Inflow pressure |
+| `bc_[x,y,z]%%pres_out`         | Real    | Outflow pressure |
+| `bc_[x,y,z]%%alpha_rho_in`     | Real Array | Inflow density |
+| `bc_[x,y,z]%%alpha_in`         | Real Array | Inflow void fraction |
 
 This boundary condition can be used for subsonic inflow (`bc_[x,y,z]%[beg,end]` = -7) and subsonic outflow (`bc_[x,y,z]%[beg,end]` = -8) characteristic boundary conditions. These are based on \cite Pirozzoli13. This enables to provide inflow and outflow conditions outside the computational domain.
 

docs/documentation/contributing.md

@@ -64,8 +64,8 @@ q_cons_vf (conservative variables: density, momentum, energy, volume fractions)
 ```
 
 Key data structures (defined in `src/common/m_derived_types.fpp`):
-- `scalar_field` — wraps a 3D `real(stp)` array (`%sf(i,j,k)`)
-- `vector_field` — array of `scalar_field` (`%vf(1:sys_size)`)
+- `scalar_field` — wraps a 3D `real(stp)` array (`%%sf(i,j,k)`)
+- `vector_field` — array of `scalar_field` (`%%vf(1:sys_size)`)
 - `q_cons_vf` / `q_prim_vf` — conservative and primitive state vectors
 
 ### Build Toolchain
@@ -136,7 +136,7 @@ Both human reviewers and AI code reviewers reference this section.
 
 ### Array Bounds and Indexing
 
-- MFC uses **non-unity lower bounds** (e.g., `idwbuff(1)%beg:idwbuff(1)%end` with negative ghost-cell indices). Always verify loop bounds match array declarations.
+- MFC uses **non-unity lower bounds** (e.g., `idwbuff(1)%%beg:idwbuff(1)%%end` with negative ghost-cell indices). Always verify loop bounds match array declarations.
 - **Riemann solver indexing:** Left states at `j`, right states at `j+1`. Off-by-one here corrupts fluxes.
 
 ### Precision and Type Safety
@@ -164,7 +164,7 @@ Both human reviewers and AI code reviewers reference this section.
 - **Pressure formula** must match `model_eqns` value. Model 2/3 (multi-fluid), model 4 (bubbles), MHD, and hypoelastic each use different EOS formulations. Wrong formula = wrong physics.
 - **Conservative-primitive conversion:** Density recovery, kinetic energy, and pressure each have model-specific paths. Verify the correct branch is taken.
 - **Volume fractions** must sum to 1. `alpha_rho_K` must be non-negative. Species mass fractions should be clipped to [0,1].
-- **Boundary conditions:** Periodic BCs must match at both ends (`bc_x%beg` and `bc_x%end`). Cylindrical coordinates have special requirements (`bc_y%beg = -14` for axis in 3D).
+- **Boundary conditions:** Periodic BCs must match at both ends (`bc_x%%beg` and `bc_x%%end`). Cylindrical coordinates have special requirements (`bc_y%%beg = -14` for axis in 3D).
 - **Parameter constraints:** New parameters or physics features must be validated in `toolchain/mfc/case_validator.py`. New features should add corresponding validation.
 
 ### Python Toolchain

docs/documentation/equations.md

@@ -777,7 +777,7 @@ Used for viscous fluxes and velocity gradients.
 | `-15` | Slip wall |
 | `-16` | No-slip wall |
 
-### 16.2 Characteristic BCs (\cite Thompson87, \cite Thompson90; `bc_x%beg = -5` to `-12`)
+### 16.2 Characteristic BCs (\cite Thompson87, \cite Thompson90; `bc_x%%beg = -5` to `-12`)
 
 **Characteristic decomposition:**
 

docs/documentation/running.md

@@ -309,8 +309,8 @@ If you want to restart a simulation,
 1. For the Computational Domain Parameters
     - Have the following removed __except__ `m`, `n`, and `p`:
 		- All domain/mesh information
-			- `(xyz)_domain%beg`
-			- `(xyz)_domain%end`
+			- `(xyz)_domain%%beg`
+			- `(xyz)_domain%%end`
 			- `stretch_(xyz)`
 			- `a_(xyz)`
 			- `(xyz)_a`
@@ -334,11 +334,11 @@ If you want to restart a simulation,
 
 3. For Patches
 	- Have all information about old patches (used in the `case.py` file) removed.
-		- `patch_icpp(1)%all variables`
-		- `patch_icpp(2)%all variables`
-		- `patch_icpp(num_patches)%all variables`
+		- `patch_icpp(1)%%all variables`
+		- `patch_icpp(2)%%all variables`
+		- `patch_icpp(num_patches)%%all variables`
 	- Add information about new patches that will be introduced, if any. The parameter num_patches should reflect this addition.
-		- e.g. `patch_icpp(1)%some variables of interest`
+		- e.g. `patch_icpp(1)%%some variables of interest`
 
 4. For Fluid properties
 	- Keep information about the fluid properties

toolchain/mfc/lint_docs.py

@@ -315,6 +315,47 @@ def check_section_anchors(repo_root: Path) -> list[str]:
     return errors
 
 
+def check_doxygen_percent(repo_root: Path) -> list[str]:
+    """Check that Fortran % accessors inside backtick code spans use %% (Doxygen escape).
+
+    Doxygen treats %<word> as "suppress auto-link" and silently eats the %
+    character, even inside backtick code spans.  Writing %% produces a
+    literal %.  Only flag % followed by [a-zA-Z_] (the pattern Doxygen
+    consumes); %[, %(, etc. are safe.
+    """
+    doc_dir = repo_root / "docs" / "documentation"
+    if not doc_dir.exists():
+        return []
+
+    ignored = _gitignored_docs(repo_root)
+    code_span_re = re.compile(r"`([^`\n]+)`")
+    bad_pct_re = re.compile(r"(?<!%)%(?=[a-zA-Z_])")
+
+    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)
+                if bad_pct_re.search(span):
+                    fixed = bad_pct_re.sub("%%", span)
+                    errors.append(
+                        f"  {rel}:{i} Doxygen will eat the % in `{span}`."
+                        f" Fix: `{fixed}`"
+                    )
+
+    return errors
+
+
 def check_page_refs(repo_root: Path) -> list[str]:
     """Check that @ref targets in docs reference existing page identifiers."""
     doc_dir = repo_root / "docs" / "documentation"
@@ -354,6 +395,7 @@ 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_doxygen_percent(repo_root))
     all_errors.extend(check_section_anchors(repo_root))
 
     if all_errors: