Address reviewer feedback on API docs scripts

- gen_api_landing.py: scan .f90 files (not just .fpp), add encoding
  and mkdir, add future annotations
- fix_file_briefs.py: exclude module procedure from regex, add
  encoding, add future annotations
- CMakeLists.txt: add source file DEPENDS to stamp commands so they
  re-run when Fortran sources change

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

Author: sbryngelson

CMakeLists.txt

@@ -813,6 +813,9 @@ if (MFC_DOCUMENTATION)
     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"
@@ -829,6 +832,9 @@ if (MFC_DOCUMENTATION)
     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"

docs/fix_file_briefs.py

@@ -12,6 +12,8 @@
      (Doxygen lowercases Fortran namespaces).
 """
 
+from __future__ import annotations
+
 import re
 import sys
 from pathlib import Path
@@ -27,7 +29,8 @@
 
 # First `module X` or `program X` that isn't `end module/program`.
 DECL_RE = re.compile(
-    r"^\s*(module|program)\s+(\w+)\s*$", re.MULTILINE | re.IGNORECASE
+    r"^\s*(module(?!\s+procedure)\b|program)\s+(\w+)\s*$",
+    re.MULTILINE | re.IGNORECASE,
 )
 
 # Any "Contains module/program <name>" in a Doxygen comment line.
@@ -66,7 +69,7 @@ def has_file_directive(text: str) -> bool:
     if not d.exists():
         continue
     for f in sorted(list(d.glob("*.fpp")) + list(d.glob("*.f90"))):
-        text = f.read_text()
+        text = f.read_text(encoding="utf-8")
         entity = find_entity(text)
         if entity is None:
             continue
@@ -77,7 +80,7 @@ def has_file_directive(text: str) -> bool:
             # 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)
+            f.write_text(text, encoding="utf-8")
             fixed += 1
             print(f"Added  {f.relative_to(src_dir)}")
             continue
@@ -96,7 +99,7 @@ def has_file_directive(text: str) -> bool:
         new_text = text[: m.start()] + new_line + text[m.end() :]
 
         if new_text != text:
-            f.write_text(new_text)
+            f.write_text(new_text, encoding="utf-8")
             fixed += 1
             print(f"Fixed  {f.relative_to(src_dir)}: {current_name} -> {ref}")
 

docs/gen_api_landing.py

@@ -4,10 +4,12 @@
 Usage: python3 gen_api_landing.py [source_dir]
   source_dir defaults to current directory.
 
-Scans src/{target}/*.fpp and src/common/*.fpp to produce module tables
-in docs/{target}/readme.md. Intro text is defined below per target.
+Scans src/{target}/*.fpp,*.f90 and src/common/*.fpp,*.f90 to produce module
+tables in docs/{target}/readme.md. Intro text is defined below per target.
 """
 
+from __future__ import annotations
+
 import sys
 from pathlib import Path
 
@@ -46,10 +48,12 @@
 
 
 def get_modules(directory: Path) -> list[str]:
-    """Return sorted list of module names (m_*) from .fpp files."""
-    return sorted(
-        f.stem for f in directory.glob("m_*.fpp")
-    )
+    """Return sorted list of module names (m_*) from .fpp and .f90 files."""
+    modules: set[str] = set()
+    for pattern in ("m_*.fpp", "m_*.f90"):
+        for f in directory.glob(pattern):
+            modules.add(f.stem)
+    return sorted(modules)
 
 
 for target, info in TARGETS.items():
@@ -88,5 +92,6 @@ def get_modules(directory: Path) -> list[str]:
         lines.append(f"- [{label} API](../{sib}/index.html)")
     lines.append("")
 
-    out.write_text("\n".join(lines))
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text("\n".join(lines), encoding="utf-8")
     print(f"Generated {out}")

docs/post_process/readme.md

@@ -7,6 +7,7 @@ The post-process component reads raw simulation output and computes derived quan
 ### Post-Process
 
 - @ref m_checker "m_checker"
+- @ref m_data_input "m_data_input"
 - @ref m_data_output "m_data_output"
 - @ref m_derived_variables "m_derived_variables"
 - @ref m_global_parameters "m_global_parameters"
@@ -18,14 +19,18 @@ The post-process component reads raw simulation output and computes derived quan
 - @ref m_boundary_common "m_boundary_common"
 - @ref m_checker_common "m_checker_common"
 - @ref m_chemistry "m_chemistry"
+- @ref m_compile_specific "m_compile_specific"
 - @ref m_constants "m_constants"
+- @ref m_delay_file_access "m_delay_file_access"
 - @ref m_derived_types "m_derived_types"
 - @ref m_finite_differences "m_finite_differences"
 - @ref m_helper "m_helper"
 - @ref m_helper_basic "m_helper_basic"
 - @ref m_model "m_model"
 - @ref m_mpi_common "m_mpi_common"
+- @ref m_nvtx "m_nvtx"
 - @ref m_phase_change "m_phase_change"
+- @ref m_precision_select "m_precision_select"
 - @ref m_variables_conversion "m_variables_conversion"
 
 ## See Also

docs/pre_process/readme.md

@@ -13,6 +13,7 @@ The pre-process component generates initial conditions and computational meshes
 - @ref m_checker "m_checker"
 - @ref m_data_output "m_data_output"
 - @ref m_global_parameters "m_global_parameters"
+- @ref m_grid "m_grid"
 - @ref m_icpp_patches "m_icpp_patches"
 - @ref m_initial_condition "m_initial_condition"
 - @ref m_mpi_proxy "m_mpi_proxy"
@@ -25,14 +26,18 @@ The pre-process component generates initial conditions and computational meshes
 - @ref m_boundary_common "m_boundary_common"
 - @ref m_checker_common "m_checker_common"
 - @ref m_chemistry "m_chemistry"
+- @ref m_compile_specific "m_compile_specific"
 - @ref m_constants "m_constants"
+- @ref m_delay_file_access "m_delay_file_access"
 - @ref m_derived_types "m_derived_types"
 - @ref m_finite_differences "m_finite_differences"
 - @ref m_helper "m_helper"
 - @ref m_helper_basic "m_helper_basic"
 - @ref m_model "m_model"
 - @ref m_mpi_common "m_mpi_common"
+- @ref m_nvtx "m_nvtx"
 - @ref m_phase_change "m_phase_change"
+- @ref m_precision_select "m_precision_select"
 - @ref m_variables_conversion "m_variables_conversion"
 
 ## See Also

docs/simulation/readme.md

@@ -43,14 +43,18 @@ The simulation component is the core flow solver. It advances the governing equa
 - @ref m_boundary_common "m_boundary_common"
 - @ref m_checker_common "m_checker_common"
 - @ref m_chemistry "m_chemistry"
+- @ref m_compile_specific "m_compile_specific"
 - @ref m_constants "m_constants"
+- @ref m_delay_file_access "m_delay_file_access"
 - @ref m_derived_types "m_derived_types"
 - @ref m_finite_differences "m_finite_differences"
 - @ref m_helper "m_helper"
 - @ref m_helper_basic "m_helper_basic"
 - @ref m_model "m_model"
 - @ref m_mpi_common "m_mpi_common"
+- @ref m_nvtx "m_nvtx"
 - @ref m_phase_change "m_phase_change"
+- @ref m_precision_select "m_precision_select"
 - @ref m_variables_conversion "m_variables_conversion"
 
 ## See Also