Improve API documentation discoverability

.lychee.toml

@@ -24,4 +24,5 @@ exclude = [
     "https://mflowcode\\.github\\.io/sitemap\\.xml",  # Only exists after deployment
     "https://cpe\\.ext\\.hpe\\.com",                   # HPE Cray docs have broken SSL cert
     "https://sc22\\.supercomputing\\.org",              # Returns 415 to automated requests
+    "https://strawberryperl\\.com",                    # Frequently times out
 ]

CMakeLists.txt

@@ -727,6 +727,8 @@ if (MFC_DOCUMENTATION)
         set(DOXYGEN_IMAGE_PATH       "\"${CMAKE_CURRENT_SOURCE_DIR}/docs/res\"\
                                       \"${CMAKE_CURRENT_SOURCE_DIR}/docs/${target}\"")
 
+        set(DOXYGEN_WARN_LOGFILE "\"${CMAKE_CURRENT_BINARY_DIR}/${target}-doxygen-warnings.log\"")
+
         file(MAKE_DIRECTORY "${DOXYGEN_OUTPUT_DIRECTORY}")
 
         configure_file(
@@ -806,6 +808,44 @@ if (MFC_DOCUMENTATION)
     GEN_DOCS(post_process  "MFC: Post-Process")
     GEN_DOCS(documentation "MFC")
 
+    # Generate API landing pages for pre_process, simulation, post_process.
+    # Scans src/{target}/*.fpp to produce module lists in docs/{target}/readme.md.
+    add_custom_command(
+        OUTPUT  "${CMAKE_CURRENT_BINARY_DIR}/gen-api-landing.stamp"
+        DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_api_landing.py"
+                ${pre_process_FPPs} ${pre_process_F90s}
+                ${simulation_FPPs} ${simulation_F90s}
+                ${post_process_FPPs} ${post_process_F90s}
+        COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_api_landing.py"
+                "${CMAKE_CURRENT_SOURCE_DIR}"
+        COMMAND "${CMAKE_COMMAND}" -E touch "${CMAKE_CURRENT_BINARY_DIR}/gen-api-landing.stamp"
+        COMMENT "Generating API landing pages"
+        VERBATIM
+    )
+    add_custom_target(gen_api_landing DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/gen-api-landing.stamp")
+    add_dependencies(pre_process_doxygen gen_api_landing)
+    add_dependencies(simulation_doxygen gen_api_landing)
+    add_dependencies(post_process_doxygen gen_api_landing)
+
+    # Fix @file/@brief headers to match actual module/program declarations.
+    # Handles mixed-case Fortran names and catches stale module renames.
+    add_custom_command(
+        OUTPUT  "${CMAKE_CURRENT_BINARY_DIR}/fix-file-briefs.stamp"
+        DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/docs/fix_file_briefs.py"
+                ${pre_process_FPPs} ${pre_process_F90s}
+                ${simulation_FPPs} ${simulation_F90s}
+                ${post_process_FPPs} ${post_process_F90s}
+        COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/fix_file_briefs.py"
+                "${CMAKE_CURRENT_SOURCE_DIR}"
+        COMMAND "${CMAKE_COMMAND}" -E touch "${CMAKE_CURRENT_BINARY_DIR}/fix-file-briefs.stamp"
+        COMMENT "Fixing @file brief headers"
+        VERBATIM
+    )
+    add_custom_target(fix_file_briefs DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/fix-file-briefs.stamp")
+    add_dependencies(pre_process_doxygen fix_file_briefs)
+    add_dependencies(simulation_doxygen fix_file_briefs)
+    add_dependencies(post_process_doxygen fix_file_briefs)
+
     # Inject per-page last-updated dates into documentation markdown files.
     # Runs after auto-generated .md files exist, before Doxygen processes them.
     # Uses a stamp file so it only runs once per build.

docs/Doxyfile.in

@@ -806,7 +806,7 @@ WARN_FORMAT            = "$file:$line: $text"
 # messages should be written. If left blank the output is written to standard
 # error (stderr).
 
-WARN_LOGFILE           =
+WARN_LOGFILE           = @DOXYGEN_WARN_LOGFILE@
 
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
@@ -983,7 +983,7 @@ USE_MDFILE_AS_MAINPAGE =
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.

docs/custom.css

@@ -3,6 +3,38 @@
  * Overrides for doxygen-awesome theme
  */
 
+/* Cross-navigation panel at top of sidebar */
+#mfc-nav {
+    display: flex;
+    flex-direction: column;
+    padding: 10px 12px 8px;
+    border-bottom: 1px solid var(--separator-color);
+    background: var(--side-nav-background);
+    font-size: 0.8rem;
+}
+
+#mfc-nav a {
+    display: block;
+    padding: 4px 8px;
+    border-radius: 4px;
+    color: var(--page-foreground-color);
+    text-decoration: none;
+    opacity: 0.75;
+    transition: background 0.12s, opacity 0.12s;
+}
+
+#mfc-nav a:hover {
+    opacity: 1;
+    background: var(--side-nav-background-highlight, rgba(0,0,0,0.05));
+}
+
+#mfc-nav a.active {
+    font-weight: 600;
+    opacity: 1;
+    color: var(--primary-color);
+    background: var(--side-nav-background-highlight, rgba(0,0,0,0.05));
+}
+
 /* Narrower left navigation panel */
 html {
     --side-nav-fixed-width: 210px;

docs/documentation/authors.md

@@ -3,3 +3,6 @@
 ## Authors
 
 Contributors to MFC since 2019 can be [viewed here](https://github.com/MFlowCode/MFC/graphs/contributors).
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-04</div>

docs/documentation/case.md

@@ -1202,3 +1202,6 @@ The above variables are used for all simulations.
 | hypoelastic variables     | N/A |
 
 The above variables correspond to optional physics.
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-15</div>

docs/documentation/contributing.md

@@ -767,3 +767,6 @@ If your change touches GPU code (`src/simulation/`), see the GPU checklist in th
 - A maintainer will merge your PR once all reviews are approved and CI is green
 
 If your PR is large or architectural, consider opening an issue first to discuss the approach.
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-15</div>

docs/documentation/docker.md

@@ -188,3 +188,6 @@ linux/loong64
 linux/arm/v7
 linux/arm/v6
 ```
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-04</div>

docs/documentation/equations.md

@@ -1049,3 +1049,6 @@ Additionally, the **artificial Mach number** technique (`pi_fac`) modifies \f$\p
 
 **Advective flux limiting** based on local volume fraction gradient \f$\chi\f$ to prevent spurious oscillations near material interfaces.
 
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-15</div>

docs/documentation/expectedPerformance.md

@@ -208,3 +208,6 @@ The "base case" uses 2M and 8M grid points per process.
 CPU strong scaling tests are done with problem sizes of 16, 32, and 64M grid points, with the base case using 2, 4, and 8M cells per process.
 
 <img src="../res/strongScaling/cpuStrongScaling.svg" style="width: 50%; border-radius: 10pt"/>
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-16</div>

docs/documentation/getting-started.md

@@ -241,3 +241,6 @@ autoload -Uz compinit && compinit
 ```
 
 After reloading your shell, press Tab to complete commands and options.
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-15</div>

docs/documentation/gpuParallelization.md

@@ -779,3 +779,6 @@ LIBOMPTARGET_JIT_SKIP_OPT=1
   - NVHPC is built on top of LLVM
 - [OpenMP Docs](https://www.openmp.org/spec-html/5.1/openmp.html)
 - [OpenACC Docs](https://www.openacc.org/sites/default/files/inline-files/OpenACC.2.7.pdf)
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-04</div>

docs/documentation/papers.md

@@ -60,3 +60,6 @@ Supercomputing 22 (SC'22): Scalable GPU Accelerated Simulation of Multiphase Com
     pages        = {1--3}
 }
 ```
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-09</div>

docs/documentation/readme.md

@@ -32,9 +32,15 @@ Welcome to the Multi-component Flow Code (MFC) documentation.
 ## Development
 
 - @ref contributing "Contributing" - Developer guide and coding standards
+- [Pre-Process API](../pre_process/index.html) - Source code reference for mesh generation and initial conditions
+- [Simulation API](../simulation/index.html) - Source code reference for the flow solver
+- [Post-Process API](../post_process/index.html) - Source code reference for data extraction and visualization
 
 ## About
 
 - @ref papers "Papers" - Publications using MFC
 - \ref citelist "Bibliography" - Cited references
 - @ref authors "Authors" - Contributors
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-19</div>

docs/documentation/running.md

@@ -374,3 +374,6 @@ We have provided an example, `case.py` and `restart_case.py` in `/examples/1D_va
 ./mfc.sh run examples/2D_shockbubble/case.py -e batch \
                -N 2 -n 4 -t simulation -a <redacted> -c summit
 ```
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-14</div>

docs/documentation/testing.md

@@ -104,3 +104,6 @@ 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.
 
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-15</div>

docs/documentation/troubleshooting.md

@@ -478,3 +478,6 @@ If you can't resolve an issue:
    ./mfc.sh help gpu
    ./mfc.sh <command> -h
    ```
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-04</div>

docs/documentation/visualization.md

@@ -140,3 +140,6 @@ Below is a slightly altered version of that dialogue:
 * Click `Add Server` If you have not set up the PACE connection.
 This will create a new dialogue box where you can specify a configuration name and set the `Port` to `8722`.
 Once this is done, click `configure` and then `save` on the next dialogue box.
+
+
+<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-13</div>

docs/fix_file_briefs.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Ensure @file/@brief headers match actual module/program declarations.
+
+Usage: python3 fix_file_briefs.py [source_dir]
+  source_dir defaults to current directory.
+
+For each .fpp/.f90 in src/{pre_process,simulation,post_process,common}:
+  1. Parses the first `module <name>` or `program <name>` declaration.
+  2. If no @file directive exists in the first 15 lines, prepends a header.
+  3. If a "Contains module/program ..." @brief exists, rewrites the name
+     to match the source, using @ref for mixed-case Fortran identifiers
+     (Doxygen lowercases Fortran namespaces).
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+src_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(".")
+
+DIRS = [
+    src_dir / "src" / "pre_process",
+    src_dir / "src" / "simulation",
+    src_dir / "src" / "post_process",
+    src_dir / "src" / "common",
+]
+
+# First `module X` or `program X` that isn't `end module/program`.
+DECL_RE = re.compile(
+    r"^\s*(module(?!\s+procedure)\b|program)\s+(\w+)\s*$",
+    re.MULTILINE | re.IGNORECASE,
+)
+
+# Any "Contains module/program <name>" in a Doxygen comment line.
+# Matches both `!! @brief Contains ...` and `!> @brief Contains ...`.
+BRIEF_CONTAINS_RE = re.compile(
+    r"^(!!|!>)\s*@brief\s+(Contains (?:module|program) )(.*)",
+    re.MULTILINE,
+)
+
+
+def find_entity(text: str) -> tuple[str, str] | None:
+    """Return (kind, name) of the first module/program declaration."""
+    for m in DECL_RE.finditer(text):
+        line_start = text.rfind("\n", 0, m.start()) + 1
+        line = text[line_start : m.end()].strip()
+        if line.lower().startswith("end"):
+            continue
+        return m.group(1).lower(), m.group(2)
+    return None
+
+
+def make_ref(name: str) -> str:
+    """Return @ref for mixed-case names, plain name for lowercase."""
+    lower = name.lower()
+    return f'@ref {lower} "{name}"' if lower != name else name
+
+
+def has_file_directive(text: str) -> bool:
+    """Check if @file appears in the first 15 lines."""
+    head = "\n".join(text.splitlines()[:15])
+    return bool(re.search(r"@file", head))
+
+
+fixed = 0
+for d in DIRS:
+    if not d.exists():
+        continue
+    for f in sorted(list(d.glob("*.fpp")) + list(d.glob("*.f90"))):
+        text = f.read_text(encoding="utf-8")
+        entity = find_entity(text)
+        if entity is None:
+            continue
+        kind, name = entity
+        ref = make_ref(name)
+
+        if not has_file_directive(text):
+            # No @file at all — prepend a complete header.
+            header = f"!>\n!! @file\n!! @brief Contains {kind} {ref}\n\n"
+            text = header + text
+            f.write_text(text, encoding="utf-8")
+            fixed += 1
+            print(f"Added  {f.relative_to(src_dir)}")
+            continue
+
+        # Has @file — check if there's a "Contains module/program" brief to fix.
+        m = BRIEF_CONTAINS_RE.search(text)
+        if m is None:
+            continue  # Has @file but no "Contains ..." brief — leave it alone
+
+        current_name = m.group(3).strip()
+        if current_name == ref:
+            continue  # Already correct
+
+        # Replace the name portion of the brief line.
+        new_line = f"{m.group(1)} @brief {m.group(2)}{ref}"
+        new_text = text[: m.start()] + new_line + text[m.end() :]
+
+        if new_text != text:
+            f.write_text(new_text, encoding="utf-8")
+            fixed += 1
+            print(f"Fixed  {f.relative_to(src_dir)}: {current_name} -> {ref}")
+
+print(f"Done — {fixed} file(s) updated.")