Fix empty bibliography in CI docs build (#1142)

* Fix empty bibliography by installing texlive-binaries in CI

Doxygen uses bib2xhtml.pl which shells out to bibtex to format the
bibliography. Without bibtex installed, citelist.html is empty and
all \cite references render as plain text. Also removes duplicate
graphviz entry.

* Add math symbols to parameter registry, cross-ref validation, and doc fixes

- Add math_symbol field to ParamDef for LaTeX symbol mapping (e.g. gamma -> γ_k)
- Define ~70 symbols inline on _r() calls in definitions.py (single source of truth)
- Show Symbol column in auto-generated parameters.md for physics parameters
- Extend lint_docs.py to validate param refs in case.md (518 refs, was unchecked)
- Add @ref cross-link validation between doc pages
- Fix doc bugs: radiue->radius, t_step_end->t_step_stop, remove stale tau_wrt row
- Add cross-page @ref links between equations.md, case.md, and parameters.md
- Update contributing guide Step 1 to document math= and desc= kwargs

* Address review: list-based table headers, robust @page/@ref checks

- Build markdown table headers from column lists instead of string concat
- Use re.search with MULTILINE for @page detection (handles leading whitespace)
- Strip code blocks before scanning for @ref targets (avoids false positives)

* Tighten param prefix check to require structural boundary

Match family prefixes only at structural boundaries to avoid
silently accepting typos like patch_ic as valid.

* Validate both family and attribute for compound params

Tighten compound-param validation to require both a known family
prefix and a known attribute. Immediately caught two doc bugs:
z_comain -> z_domain typo, model%%filepath -> model_filepath.

* Fix Doxygen warnings across docs and Fortran sources (510 → 5)

- Remove filename args from @file directives in all 52 .fpp files
- Add @param docs to 13 undocumented subroutines, remove duplicate !< inline comments
- Convert raw $...$ math to Doxygen \f$...\f$ in m_riemann_solvers.fpp
- Add @cond/@endcond around #ifdef blocks that confuse Doxygen parser
- Fix getting-started.md HTML (<h3> in <summary>), contributing.md (@: escaping)
- Fix stale @param names in m_data_input.f90
- Remove obsolete Doxyfile tags (HTML_TIMESTAMP, LATEX_TIMESTAMP), fix PROJECT_NAME quoting
- Add stable {#id} anchors to generated case_constraints.md and cli-reference.md
- Add _escape_doxygen() helper for CLI help text, add missing precheck command
- Extend lint_docs.py with math syntax and section anchor checks

* Remove duplicate References page, link directly to Bibliography

The manual references.md page just redirected to the auto-generated
Bibliography (citelist). Remove it and point the sidebar link directly
to \ref citelist to avoid two near-identical sidebar entries.


* Redo Fortran source doc fixes without comment mangling

Previous commit used an overly broad regex that stripped @param,
@brief, and first words from comments across all .fpp files.
Restore all source files from master and re-apply only:
- Remove filename args from @file directives (58 files)
- Convert raw $...$ math to \f$...\f$ in m_riemann_solvers.fpp
- Add @cond/@endcond for #ifdef blocks with vendor attributes
- Fix stale @param name in m_data_input.f90

Author: sbryngelson

.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

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
@@ -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/documentation/case.md

@@ -148,7 +148,7 @@ Both human reviewers and AI code reviewers reference this section.
 ### Memory and Allocation
 
 - **ALLOCATE/DEALLOCATE pairing:** Every `@:ALLOCATE()` must have a matching `@:DEALLOCATE()`. Missing deallocations leak GPU memory.
-- **@:ACC_SETUP_VFs / @:ACC_SETUP_SFs:** Vector/scalar fields must have GPU pointer setup before use in kernels.
+- **`@:ACC_SETUP_VFs` / `@:ACC_SETUP_SFs`:** Vector/scalar fields must have GPU pointer setup before use in kernels.
 - **Conditional allocation:** If an array is allocated inside an `if` block, its deallocation must follow the same condition.
 - **Out-of-bounds access:** Fortran is permissive with assumed-shape arrays. Check that index arithmetic stays within declared bounds.
 
@@ -212,10 +212,27 @@ Adding a parameter touches both the Python toolchain and Fortran source. Follow
 Add a call to `_r()` inside the `_load()` function:
 
 ```python
-_r("my_param", REAL, {"my_feature_tag"})
+_r("my_param", REAL, {"my_feature_tag"},
+   desc="Description of the parameter",
+   math=r"\f$\xi\f$")
 ```
 
-The arguments are: name, type (`INT`, `REAL`, `LOG`, `STR`), and a set of feature tags. You can add an explicit description with `desc="..."`, otherwise one is auto-generated from `_SIMPLE_DESCS` or `_ATTR_DESCS`.
+The arguments are:
+- **name**: parameter name (must match the Fortran namelist variable)
+- **type**: `INT`, `REAL`, `LOG`, `STR`, or `A_REAL` (analytic expression)
+- **tags**: set of feature tags for grouping (e.g. `{"bubbles"}`, `{"mhd"}`)
+- **desc**: human-readable description (optional; auto-generated from `_SIMPLE_DESCS` or `_ATTR_DESCS` if omitted)
+- **math**: LaTeX math symbol in Doxygen format (optional; shown in the Symbol column of @ref parameters)
+
+For indexed families like `fluid_pp`, put the symbol next to its attribute name using tuples:
+
+```python
+for f in range(1, NF + 1):
+    px = f"fluid_pp({f})%"
+    for a, sym in [("gamma", r"\f$\gamma_k\f$"),
+                   ("my_attr", r"\f$\xi_k\f$")]:  # <-- add here
+        _r(f"{px}{a}", REAL, math=sym)
+```
 
 **Step 2: Add constraints** (same file, `CONSTRAINTS` dict)
 

docs/documentation/contributing.md

@@ -7,6 +7,8 @@ Each section notes the input parameter(s) that activate the corresponding physic
 
 The models and algorithms described here are detailed in \cite Wilfong26 (MFC 5.0) and \cite Bryngelson21. Foundational references for each model are cited inline; see the \ref citelist "Bibliography" for full details.
 
+For parameter details and allowed values, see @ref case "Case Files" and the @ref parameters "Case Parameters" reference.
+
 ---
 
 ## 1. Overview

docs/documentation/equations.md

@@ -70,7 +70,7 @@ for a Linux experience.
 
  <details>
 
-   <summary><h3>Windows + WSL (Recommended)</h3></summary>
+   <summary><b>Windows + WSL (Recommended)</b></summary>
 
 Install [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/) on Windows 11:
 Either
@@ -92,7 +92,7 @@ Once you have WSL installed, you can follow the instructions for *nix systems ab
 
   <details>
 
-   <summary><h3>Native Windows (Intel)</h3></summary>
+   <summary><b>Native Windows (Intel)</b></summary>
 
 Install the latest version of:
 - [Microsoft Visual Studio Community](https://visualstudio.microsoft.com/)
@@ -118,7 +118,9 @@ You will also have access to the `.sln` Microsoft Visual Studio solution files f
 
   </details>
 
-  <summary><h3>MacOS</h3></summary>
+  <details>
+
+  <summary><b>MacOS</b></summary>
 
 Using [Homebrew](https://brew.sh/) you can install the necessary dependencies
 before configuring your environment:

docs/documentation/getting-started.md

@@ -35,5 +35,5 @@ Welcome to the Multi-component Flow Code (MFC) documentation.
 ## About
 
 - @ref papers "Papers" - Publications using MFC
-- @ref references "References" - Bibliography
+- \ref citelist "Bibliography" - Cited references
 - @ref authors "Authors" - Contributors

docs/documentation/readme.md

@@ -54,30 +54,30 @@ For analysis and processing of the database using VisIt's capability, the user i
 ## Serial data output
 
 If ``parallel_io = 'F'``, MFC will output the conservative variables to a directory `D/`. 
-If multiple cores are used ($\mathtt{ppn > 1}$), then a separate file is created for each core.
+If multiple cores are used (\f$\mathtt{ppn > 1}\f$), then a separate file is created for each core.
 If only one coordinate dimension (`n = 0` and `p = 0`) exists, the primitive variables will also be written to `D/`.
 The file names correspond to the variables associated with each equation solved by MFC.
 They are written at every `t_step_save` time step.
 The conservative variables are
 
-$$ {(\rho \alpha)}\_{1}, \dots, (\rho\alpha)\_{N\_c}, \rho u\_{1}, \dots, \rho u\_{N\_d}, E, \alpha\_1, \dots, \alpha\_{N\_c} $$
+\f[ (\rho \alpha)_{1}, \dots, (\rho\alpha)_{N_c}, \rho u_{1}, \dots, \rho u_{N_d}, E, \alpha_1, \dots, \alpha_{N_c} \f]
 
 and the primitive variables are
 
-$$ {(\rho \alpha)}\_1, \dots, (\rho\alpha)\_{N\_c}, u\_1, \dots, u\_{N\_d}, p, \alpha\_1, \dots, \alpha\_{N\_c} $$
+\f[ (\rho \alpha)_1, \dots, (\rho\alpha)_{N_c}, u_1, \dots, u_{N_d}, p, \alpha_1, \dots, \alpha_{N_c} \f]
 
 where $N_c$ are the number of components `num_fluids` and $N_d$ is the number of spatial dimensions. 
 There are exceptions: if `model_eqns = 3`, then the six-equation model appends these variables with the internal energies of each component.
 If there are sub-grid bubbles `bubbles = T`, then the bubble variables are also written. 
 These depend on the bubble dynamics model used.
 If ``polytropic = 'T'``, then the conservative variables are appended by 
 
-$$ n\_b R\_1, n\_b {\\dot R}\_1, \dots, n\_b R\_{N\_b}, n\_b {\\dot R}\_{N\_b} $$
+\f[ n_b R_1, n_b \dot{R}_1, \dots, n_b R_{N_b}, n_b \dot{R}_{N_b} \f]
 
 where $n_B$ is the bubble number density, and $N_b$ is the number of bubble sizes (see the matching variable in the input file, `Nb`).
 The primitive bubble variables do not include $n_B$:
 
-$$ R\_1, {\\dot R}\_1, \dots, R\_{N\_b}, {\\dot R}\_{N\_b} $$
+\f[ R_1, \dot{R}_1, \dots, R_{N_b}, \dot{R}_{N_b} \f]
 
 ## Remote Visualization on PACE Phoenix
 

docs/documentation/references.md

@@ -1,5 +1,5 @@
 !>
-!! @file m_boundary_conditions_common.fpp
+!! @file
 !! @brief Contains module m_boundary_conditions_common
 
 !> @brief The purpose of the module is to apply noncharacteristic and processor