Documentation overhaul: modernise site, fix stale content, add missing pages - #341
Merged
Conversation
…e nav (#339) Content fixes: - Fix dead links (udales-getting-started, /docs/tutorial_mlx, write_inputs.sh) - Fix NETCDF_DIR option name; document DOUBLE_PRECISION, SINGLE_PRECISION_OUTPUT, FFT_Choice - Fix citation volume (GMD 17), example 949/950 mixups, Tfacinit/&INPS errors, typos - De-personalise cluster workflows page (generic venv path, current Python module) - Remove stale namelist rows (luflowr, lvflowr, lslicedump, nblocks, lsdriver) - Fix wrong defaults (dtdriver, fraction, courant, driverstore) - Mention link_driver_files.sh in driver simulations page Structure: - New Python package overview page (under-testing caveat, notebook pointers) - MATLAB path deprecation notices: retired from v3.0 onwards - Write real workflow overview page (was a stub) - Homepage redesign with capability overview and card grid - Nav restructure into journey-based tabs; include orphan pages Site modernisation: - Material light/dark palette toggle, navigation tabs, search suggest/highlight, code copy - MathJax 2.7 -> MathJax 3; codehilite -> pymdownx.highlight; dedupe extensions - Mermaid diagram support; remove obsolete bibtex cite_style option Publications: - Add Wilson2026, Fellini2026, Wilson2025, Reeuwijk2025; complete Owens2025 entry Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ingularity (#339) New pages: - Model overview: physics and capabilities with citations - Output files reference: every NetCDF dump with enabling switch and frequency, incl. fac.nc (lwritefac) and restart files; verified against source - Troubleshooting: 16 entries grounded in actual error messages in code/scripts - Scalar boundary conditions section (was "TBC"), verified against modboundary Fixes: - Replace docs/DEVELOP.md and docs/CONTRIBUTING.md symlinks (rendered as literal path text on Windows checkouts) with pymdownx.snippets build-time includes - Refresh DEVELOP.md: drop obsolete ../.venv instructions, point to setup_venv.sh and tests/run_tests.py - De-emphasise Singularity: outdated-image warning (still uDALES 1.0), removed from homepage/workflow, section marked not recommended Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- New Development overview page orienting the section (notes, contributing, parallelisation, agents, FORD docs, repo layout) - DEVELOP.md: replace duplicated installation/running sections with a pointer to the installation guide plus developer-specific Debug build instructions - Rename included notes page to udales-development-notes.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…h instructions (#339) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs/udales-docs-software.md was the FORD config file, which MkDocs rendered as a garbled page whenever FORD had not overwritten it (any local preview). Move it to ford.md at the repo root (paths adjusted, TODO summary filled in), update the CI and DEVELOP.md build commands, and replace the raw nav link with a small explainer page for the Fortran API reference. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Code architecture: repository layout, module responsibilities, and the verified RK3 timestep call sequence from program.f90; field array and halo conventions - Extending uDALES: recipes traced through working examples — namelist option, fielddump variable, xytdump statistic, example case, test suite - Testing and CI: actual suites from test_suites.yml, local invocation, CI jobs, and pre-review expectations - Development overview updated; release-vs-master guidance added to installation and development pages Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
madDipanjan
approved these changes
Jul 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses #339 (full audit findings and UX analysis recorded there).
Content fixes
udales-getting-startedlinks,/docs/tutorial_mlx→tutorial_udbase(5 tutorials),write_input.shtypo,NETCDF4_DIR→NETCDF_DIR, GMD citation volume 16 → 17, example 949/950 mixups and phantom case501,Tfacinit.f90→Tfacinit.inp.<expnr>,&INP→&INPS, assorted typosluflowr,lvflowr,lslicedump,nblocks,lsdriver); fixed 4 wrong defaults (dtdriver,fraction,courant,driverstore) — all verified against sourcemodboundary.f90New pages
fac.ncand restart files), verified against sourcetools/python/examples/program.f90), Extending uDALES (recipes traced through working examples), Testing and CIScope decisions
Site modernisation
codehilite→pymdownx.highlight; de-duplicated extensions; removed obsolete bibtexcite_styleoption (latent CI break)docs/DEVELOP.md/docs/CONTRIBUTING.mdsymlinks (rendered as literal path text on Windows checkouts) replaced with build-time snippet includesdocs/toford.md(it rendered as a garbled page locally); nav now has a proper Fortran API reference explainer; note: the CI docs job'sfordinvocation changed accordinglySite builds cleanly with
mkdocs build(only pre-existing benign warnings remain). Follow-ups tracked in #339;run_examples.shdrift filed as #340.🤖 Generated with Claude Code