Fix empty bibliography in CI docs build

.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/contributing.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/equations.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/getting-started.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/readme.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/visualization.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
 

src/common/m_boundary_common.fpp

@@ -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

src/common/m_checker_common.fpp

@@ -1,5 +1,5 @@
 !>
-!!@file m_checker_common.f90
+!!@file
 !!@brief Contains module m_checker_common
 
 #:include 'case.fpp'

src/common/m_chemistry.fpp

@@ -1,5 +1,5 @@
 !!>
-!! @file   m_chemistry.f90
+!! @file
 !! @brief  Contains module m_chemistry
 !! @author Henry Le Berre <hberre3@gatech.edu>
 

src/common/m_compile_specific.f90

@@ -1,5 +1,5 @@
 !>
-!! @file m_compile_specific.f90
+!! @file
 !! @brief Contains module m_compile_specific
 
 !> @brief This module contains subroutines that are compiler specific

src/common/m_compute_levelset.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_compute_levelset.fpp
+!! @file
 !! @brief Contains module m_compute_levelset
 
 #:include 'macros.fpp'

src/common/m_constants.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_constants.f90
+!! @file
 !! @brief Contains constant values used throughout the code(s).
 
 module m_constants

src/common/m_derived_types.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_derived_types.f90
+!! @file
 !! @brief Contains module m_derived_types
 
 #:include "macros.fpp"

src/common/m_helper.fpp

@@ -2,7 +2,7 @@
 #:include 'macros.fpp'
 
 !>
-!! @file m_helper.f90
+!! @file
 !! @brief Contains module m_helper
 
 module m_helper

src/common/m_helper_basic.fpp

@@ -1,5 +1,5 @@
 
-!! @file m_helper_basic.f90
+!! @file
 !! @brief Contains module m_helper_basic
 
 #:include 'macros.fpp'

src/common/m_ib_patches.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_patches.fpp
+!! @file
 !! @brief Contains module m_patches
 
 #:include 'case.fpp'

src/common/m_model.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file   m_model.fpp
+!! @file
 !! @author Henry Le Berre <hberre3@gatech.edu>
 !! @brief  Contains module m_model
 

src/common/m_variables_conversion.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_variables_conversion.f90
+!! @file
 !! @brief Contains module m_variables_conversion
 
 #:include 'macros.fpp'

src/post_process/m_checker.fpp

@@ -1,5 +1,5 @@
 !>
-!!@file m_checker.f90
+!!@file
 !!@brief Contains module m_checker
 
 #:include 'macros.fpp'

src/post_process/m_data_input.f90

@@ -1,5 +1,5 @@
 !>
-!! @file m_data_input.f90
+!! @file
 !> @brief Contains module m_data_input
 
 !> @brief This module features procedures, which for a specific time-step,
@@ -211,8 +211,10 @@ impure subroutine s_read_ib_data_files(file_loc_base, t_step)
     end subroutine s_read_ib_data_files
 
     !> Helper subroutine to allocate field arrays for given dimensionality
-    !!  @param start_idx Starting index for allocation
-    !!  @param end_x, end_y, end_z End indices for each dimension
+    !!  @param local_start_idx Starting index for allocation
+    !!  @param end_x End index for x dimension
+    !!  @param end_y End index for y dimension
+    !!  @param end_z End index for z dimension
     impure subroutine s_allocate_field_arrays(local_start_idx, end_x, end_y, end_z)
 
         integer, intent(in) :: local_start_idx, end_x, end_y, end_z

src/post_process/m_data_output.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_data_output.f90
+!! @file
 !! @brief Contains module m_data_output
 
 !> @brief This module enables the restructuring of the raw simulation data

src/post_process/m_derived_variables.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_derived_variables.f90
+!! @file
 !! @brief Contains module m_derived_variables
 
 !> @brief This module features subroutines that allow for the derivation of

src/post_process/m_global_parameters.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_global_parameters.f90
+!! @file
 !! @brief Contains module m_global_parameters
 
 #:include 'case.fpp'

src/post_process/m_mpi_proxy.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_mpi_proxy.f90
+!! @file
 !! @brief Contains module m_mpi_proxy
 
 !> @brief  This module serves as a proxy to the parameters and subroutines

src/post_process/m_start_up.fpp

@@ -1,7 +1,7 @@
 #:include 'macros.fpp'
 
 !>
-!! @file m_start_up.f90
+!! @file
 !! @brief  Contains module m_start_up
 
 !> @brief This module contains the subroutines that read in and check the

src/post_process/p_main.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file p_main.f90
+!! @file
 !! @brief Contains program p_main
 
 !> @brief The post-process restructures raw unformatted data, outputted by

src/pre_process/m_assign_variables.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_assign_variables.f90
+!! @file
 !! @brief Contains module m_assign_variables
 
 #:include 'case.fpp'

src/pre_process/m_boundary_conditions.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_boundary_conditions.fpp
+!! @file
 !! @brief Contains module m_boundary_conditions
 
 !> @brief This module contains

src/pre_process/m_checker.fpp

@@ -1,5 +1,5 @@
 !>
-!!@file m_checker.f90
+!!@file
 !!@brief Contains module m_checker
 
 #:include 'macros.fpp'

src/pre_process/m_data_output.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_data_output.f90
+!! @file
 !! @brief Contains module m_data_output
 
 !> @brief This module takes care of writing the grid and initial condition

src/pre_process/m_global_parameters.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_global_parameters.f90
+!! @file
 !! @brief Contains module m_global_parameters
 
 #:include 'case.fpp'

src/pre_process/m_grid.f90

@@ -1,5 +1,5 @@
 !>
-!! @file m_grid.f90
+!! @file
 !! @brief Contains module m_grid
 
 !> @brief  This module takes care of creating the rectilinear grid on which

src/pre_process/m_icpp_patches.fpp

@@ -1,5 +1,5 @@
 !>
-!! @file m_patches.fpp
+!! @file
 !! @brief Contains module m_patches
 
 #:include 'case.fpp'