Skip to content

Commit c612b6a

Browse files
sbryngelsonclaude
sbryngelson
and
claude
authored
Improve API documentation discoverability (#1167)
* Improve API documentation discoverability and source browsing Add API nav link to landing page, cross-links in user guide sidebar, auto-generated module listings for all three Doxygen targets, and enable SOURCE_BROWSER for click-through to annotated source code. The gen_api_landing.py script scans src/{target}/*.fpp at build time to produce docs/{target}/readme.md with explicit @ref links that handle Fortran case-insensitive namespaces correctly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add missing @file documentation blocks to 16 source files Add Doxygen @file/@brief blocks to 13 modules that were missing them (m_body_forces, m_igr, m_muscl, m_sim_helpers, m_surface_tension, m_finite_differences, m_mpi_common, m_nvtx, m_delay_file_access, m_phase_change, m_check_ib_patches, m_check_patches, m_simplex_noise) and fix 3 files with malformed comment openers (m_chemistry used !!> instead of !>, m_data_output and m_helper_basic started with !! continuation markers instead of !> openers). All file list pages now show descriptions for every entry. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Exclude strawberryperl.com from lychee (frequently times out) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix unlinked module names in Doxygen file list descriptions Use explicit @ref for mixed-case Fortran modules (m_bubbles_EE/EL/ EL_kernels) so Doxygen resolves the lowercase namespace. Correct wrong module names in @file briefs: m_boundary_conditions_common -> m_boundary_common, m_patches -> m_ib_patches / m_icpp_patches. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Auto-fix @file briefs at build time to match module declarations Add docs/fix_file_briefs.py that reads the actual module/program name from each Fortran source file and ensures the @file @brief matches, using @ref for mixed-case identifiers. Runs before Doxygen via CMake so new files, renames, and case issues are caught automatically. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix 472 of 477 Doxygen @param warnings and add WARN_LOGFILE - Add DOXYGEN_WARN_LOGFILE to CMakeLists.txt and Doxyfile.in to capture per-target warning logs during documentation builds - Fix stale, missing, duplicate, and misspelled @param entries across 28 source files (common, pre_process, post_process, simulation modules) - Common module fixes (m_helper, m_model, m_mpi_common, m_phase_change, m_finite_differences) eliminate 3x warnings since each is shared across all three Doxygen targets - Remaining 5 warnings are structural unbalanced grouping from fypp macro expansion, not @param issues Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix remaining 5 Doxygen grouping warnings (now 0 warnings total) - m_surface_tension.fpp: typo @) -> @} (close group) - m_global_parameters.fpp (sim): copy-paste @{ -> @} (close group) - m_global_parameters.fpp (post): typo #} -> @} (close group) - m_rhs.fpp: add missing @} closer for index bounds group - m_compute_levelset.fpp: remove orphaned @} with no matching opener Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * 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> * Fix @param qv description: Fluid reference energy, not Vapor quality Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add module-level @brief descriptions for all 16 undocumented modules Doxygen uses the comment block directly before the module declaration (not the @file header) to populate the Modules List page. These 16 modules only had file-level @Briefs, so they appeared with empty descriptions on the namespace list pages. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add subroutine @brief descriptions and sidebar cross-navigation - Add ~170 !> @brief one-line descriptions to previously undocumented subroutines/functions across all 45 source files - Add cross-navigation links (User Guide, Pre-Process/Simulation/Post- Process API) injected at the top of the Doxygen sidebar via JavaScript - Fix stale @param ib in s_ib_3D_airfoil Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Rewrite module briefs, add description tables to landing pages, and lint for missing briefs - Rewrite ~51 module-level !> @brief descriptions to be concise and descriptive (one sentence, no boilerplate) - Update gen_api_landing.py to extract briefs from source files and render module tables with descriptions on API landing pages - Add check_module_briefs() linter to lint_docs.py ensuring every m_*.fpp/.f90 has a module-level !> @brief before the module declaration Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 05b26f7 commit c612b6a

94 files changed

Lines changed: 1123 additions & 393 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.lychee.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,5 @@ exclude = [
2424
"https://mflowcode\\.github\\.io/sitemap\\.xml", # Only exists after deployment
2525
"https://cpe\\.ext\\.hpe\\.com", # HPE Cray docs have broken SSL cert
2626
"https://sc22\\.supercomputing\\.org", # Returns 415 to automated requests
27+
"https://strawberryperl\\.com", # Frequently times out
2728
]

‎CMakeLists.txt‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -727,6 +727,8 @@ if (MFC_DOCUMENTATION)
727727
set(DOXYGEN_IMAGE_PATH "\"${CMAKE_CURRENT_SOURCE_DIR}/docs/res\"\
728728
\"${CMAKE_CURRENT_SOURCE_DIR}/docs/${target}\"")
729729

730+
set(DOXYGEN_WARN_LOGFILE "\"${CMAKE_CURRENT_BINARY_DIR}/${target}-doxygen-warnings.log\"")
731+
730732
file(MAKE_DIRECTORY "${DOXYGEN_OUTPUT_DIRECTORY}")
731733

732734
configure_file(
@@ -806,6 +808,44 @@ if (MFC_DOCUMENTATION)
806808
GEN_DOCS(post_process "MFC: Post-Process")
807809
GEN_DOCS(documentation "MFC")
808810

811+
# Generate API landing pages for pre_process, simulation, post_process.
812+
# Scans src/{target}/*.fpp to produce module lists in docs/{target}/readme.md.
813+
add_custom_command(
814+
OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/gen-api-landing.stamp"
815+
DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_api_landing.py"
816+
${pre_process_FPPs} ${pre_process_F90s}
817+
${simulation_FPPs} ${simulation_F90s}
818+
${post_process_FPPs} ${post_process_F90s}
819+
COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/gen_api_landing.py"
820+
"${CMAKE_CURRENT_SOURCE_DIR}"
821+
COMMAND "${CMAKE_COMMAND}" -E touch "${CMAKE_CURRENT_BINARY_DIR}/gen-api-landing.stamp"
822+
COMMENT "Generating API landing pages"
823+
VERBATIM
824+
)
825+
add_custom_target(gen_api_landing DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/gen-api-landing.stamp")
826+
add_dependencies(pre_process_doxygen gen_api_landing)
827+
add_dependencies(simulation_doxygen gen_api_landing)
828+
add_dependencies(post_process_doxygen gen_api_landing)
829+
830+
# Fix @file/@brief headers to match actual module/program declarations.
831+
# Handles mixed-case Fortran names and catches stale module renames.
832+
add_custom_command(
833+
OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/fix-file-briefs.stamp"
834+
DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/docs/fix_file_briefs.py"
835+
${pre_process_FPPs} ${pre_process_F90s}
836+
${simulation_FPPs} ${simulation_F90s}
837+
${post_process_FPPs} ${post_process_F90s}
838+
COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/docs/fix_file_briefs.py"
839+
"${CMAKE_CURRENT_SOURCE_DIR}"
840+
COMMAND "${CMAKE_COMMAND}" -E touch "${CMAKE_CURRENT_BINARY_DIR}/fix-file-briefs.stamp"
841+
COMMENT "Fixing @file brief headers"
842+
VERBATIM
843+
)
844+
add_custom_target(fix_file_briefs DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/fix-file-briefs.stamp")
845+
add_dependencies(pre_process_doxygen fix_file_briefs)
846+
add_dependencies(simulation_doxygen fix_file_briefs)
847+
add_dependencies(post_process_doxygen fix_file_briefs)
848+
809849
# Inject per-page last-updated dates into documentation markdown files.
810850
# Runs after auto-generated .md files exist, before Doxygen processes them.
811851
# Uses a stamp file so it only runs once per build.

‎docs/Doxyfile.in‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -806,7 +806,7 @@ WARN_FORMAT = "$file:$line: $text"
806806
# messages should be written. If left blank the output is written to standard
807807
# error (stderr).
808808

809-
WARN_LOGFILE =
809+
WARN_LOGFILE = @DOXYGEN_WARN_LOGFILE@
810810

811811
#---------------------------------------------------------------------------
812812
# Configuration options related to the input files
@@ -983,7 +983,7 @@ USE_MDFILE_AS_MAINPAGE =
983983
# also VERBATIM_HEADERS is set to NO.
984984
# The default value is: NO.
985985

986-
SOURCE_BROWSER = NO
986+
SOURCE_BROWSER = YES
987987

988988
# Setting the INLINE_SOURCES tag to YES will include the body of functions,
989989
# classes and enums directly into the documentation.

‎docs/custom.css‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,38 @@
33
* Overrides for doxygen-awesome theme
44
*/
55

6+
/* Cross-navigation panel at top of sidebar */
7+
#mfc-nav {
8+
display: flex;
9+
flex-direction: column;
10+
padding: 10px 12px 8px;
11+
border-bottom: 1px solid var(--separator-color);
12+
background: var(--side-nav-background);
13+
font-size: 0.8rem;
14+
}
15+
16+
#mfc-nav a {
17+
display: block;
18+
padding: 4px 8px;
19+
border-radius: 4px;
20+
color: var(--page-foreground-color);
21+
text-decoration: none;
22+
opacity: 0.75;
23+
transition: background 0.12s, opacity 0.12s;
24+
}
25+
26+
#mfc-nav a:hover {
27+
opacity: 1;
28+
background: var(--side-nav-background-highlight, rgba(0,0,0,0.05));
29+
}
30+
31+
#mfc-nav a.active {
32+
font-weight: 600;
33+
opacity: 1;
34+
color: var(--primary-color);
35+
background: var(--side-nav-background-highlight, rgba(0,0,0,0.05));
36+
}
37+
638
/* Narrower left navigation panel */
739
html {
840
--side-nav-fixed-width: 210px;

‎docs/documentation/authors.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,6 @@
33
## Authors
44

55
Contributors to MFC since 2019 can be [viewed here](https://github.com/MFlowCode/MFC/graphs/contributors).
6+
7+
8+
<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‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1202,3 +1202,6 @@ The above variables are used for all simulations.
12021202
| hypoelastic variables | N/A |
12031203

12041204
The above variables correspond to optional physics.
1205+
1206+
1207+
<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‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -767,3 +767,6 @@ If your change touches GPU code (`src/simulation/`), see the GPU checklist in th
767767
- A maintainer will merge your PR once all reviews are approved and CI is green
768768

769769
If your PR is large or architectural, consider opening an issue first to discuss the approach.
770+
771+
772+
<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‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,3 +188,6 @@ linux/loong64
188188
linux/arm/v7
189189
linux/arm/v6
190190
```
191+
192+
193+
<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‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1049,3 +1049,6 @@ Additionally, the **artificial Mach number** technique (`pi_fac`) modifies \f$\p
10491049

10501050
**Advective flux limiting** based on local volume fraction gradient \f$\chi\f$ to prevent spurious oscillations near material interfaces.
10511051

1052+
1053+
1054+
<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‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,3 +208,6 @@ The "base case" uses 2M and 8M grid points per process.
208208
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.
209209

210210
<img src="../res/strongScaling/cpuStrongScaling.svg" style="width: 50%; border-radius: 10pt"/>
211+
212+
213+
<div style='text-align:center; font-size:0.75rem; color:#888; padding:16px 0 0;'>Page last updated: 2026-02-16</div>

0 commit comments

Comments
 (0)