Documentation overhaul: modernise site layout, fix stale content, restructure navigation

[mvreeuwijk]

A full audit of the documentation against the current master codebase (2026-07-18) shows the docs have drifted substantially and the site layout is dated. This issue tracks a documentation overhaul.

Scope decisions

• Python tooling: pages that already reference the Python path keep it. A new Python package overview page will be added (marked as under active testing), pointing to the tutorial notebooks in tools/python/examples/.
• MATLAB path: all tutorials remain MATLAB-based for now. Docs will state that the MATLAB path is deprecated and will be retired from uDALES v3.0 onwards, with the Python package as its successor.
• Namelist reference: current level of per-variable description is sufficient (several namelist variables are unused and pending cleanup). Only stale entries and incorrect defaults are fixed — no coverage expansion.
• Publication list: to be fed by an automated push of recent uDALES papers from vanreeuwijk.net (integration designed separately; the page will be structured to consume it).

Audit findings

Broken/incorrect references

• DEVELOP.md:5,51 — links to renamed page udales-getting-started (now udales-installation); both anchors 404
• docs/udales-simulation-setup.md:8 — write_input.sh / write_input.m → write_inputs.sh / write_inputs.m
• All five tutorials reference non-existent /docs/tutorial_mlx → actual docs/tutorial_udbase/
• docs/udales-installation.md:184 — NETCDF4_DIR → NETCDF_DIR; options table omits DOUBLE_PRECISION, SINGLE_PRECISION_OUTPUT, FFT_Choice
• docs/udales-how-to-cite.md — GMD volume says 16, should be 17
• docs/udales-example-simulations.md — references non-existent case 501; 949/950 precursor mixups; Tfacinit.f90 → Tfacinit.inp.<expnr>; &INP → &INPS; image captions blocks.501/502 for cases 949/950
• docs/cluster_workflows.md — hardcoded personal path /rds/general/user/mvr/home/udales/.venv; stale Python/3.9.6 module (scripts load Python/3.13.1-GCCcore-14.2.0)
• Typos: "uvuntu" (installation), "depricate"/"recomended" (pre-processing), &OUPUT (post-processing)
• Venv location inconsistent across pages: tools/python/.venv (setup_venv.sh, write_inputs.sh) vs top-level .venv (Windows page, DEVELOP.md)

Namelist reference (scoped fixes only)

• Remove stale documented options no longer read from namoptions: luflowr, lvflowr, lslicedump (now lk/li/ljslicedump), nblocks, lsdriver (set programmatically)
• Fix wrong defaults: dtdriver (0 → 0.1), fraction (0 → 1), courant (1.1 → effective 1.5), driverstore (documented 0, actually uninitialised — must be set when driving)

Structure / navigation

• Orphan pages not in nav: udales-2decomp.md, cluster_workflows.md, udales-agents.md (linked from homepage but not navigable), udales-workflow.md (stub)
• udales-workflow.md is a 3-line stub — write a real end-to-end workflow overview (build → pre-process → run → post-process) and put it in nav
• New page: Python package overview (udbase, udprep, udgeom, udvis, udstats; testing caveat; pointer to tools/python/examples/ notebooks)
• Add MATLAB-path deprecation notice (retired from v3.0) to MATLAB-routed pages/tutorials
• Nav regrouping: user path (install → inputs → run → post-process), tutorials, Python package, developer section (DEVELOP, CONTRIBUTING, 2decomp, agents, cluster workflows), about (cite, publications)
• Mention tools/link_driver_files.sh in driver-simulations page (currently instructs manual copy)

Site layout modernisation (mkdocs)

• Modern Material palette with automatic light/dark scheme toggle
• Enable navigation/search features: navigation.tabs, navigation.top, search.suggest, search.highlight, content.code.copy, toc.follow
• MathJax 2.7 (2017) → MathJax 3 with current arithmatex generic config
• Replace legacy codehilite with pymdownx.highlight; de-duplicate extension list (mark, details, superfences, tasklist all listed twice)
• Homepage redesign: capability overview + quick-start cards (keep the animation GIFs)
• Branding: logo/favicon (Material icon)

Deferred (follow-up issues, out of scope here)

• Scalar boundary conditions section ("TBC")
• Output-variables reference (what each dump file contains)
• Restart/warmstart documentation
• Troubleshooting/FAQ page
• CONTRIBUTING.md refresh (last touched 2020)
• vanreeuwijk.net → publication list feed implementation

🤖 Generated with Claude Code

[mvreeuwijk]

UX analysis: the documentation as user journeys

Looking at the site as a whole, five distinct audiences arrive with different questions. This is how the docs serve each of them, what the docs-overhaul branch changes, and what still needs its own page.

1. The evaluator — "is uDALES right for my work?"

Before: a 12-line homepage with three GIFs and no statement of what the model does; capabilities were only discoverable implicitly through the namoptions reference and example cases.
Branch: homepage rewritten as a router — capability paragraph, card grid to the main journeys, citing/contributing pointers.
Still missing: a model overview page — one page describing the physics (LES core + IBM, surface energy balance with radiation, vegetation, dispersion/chemistry, precursor-driven inflow) with pointers to the GMD description papers. This is the largest remaining gap for this audience and deserves its own follow-up issue.

2. The new user — "get me to a first successful run"

Before: no end-to-end overview existed (udales-workflow.md was a 3-line stub, not even in the nav); the install page was referred to by three different names across the site.
Branch: a Getting started tab now carries this journey: Installation → Workflow overview (new page, with diagram, each step linking to its detailed guide) → Example simulations.

3. The case builder — "set up my own experiment"

*Simulation inputs tab: namoptions reference → boundary conditions → geometry generation → copying setups → precursor simulations. The structure is sound; the gaps are content, not organisation: scalar boundary conditions ("TBC"), restart/warmstart, and trees/vegetation setup have no documentation. Follow-up issues.

4. The runner — desktop and HPC

Branch: Running simulations tab now includes the previously orphaned cluster-workflows page (de-personalised: generic venv path, current Python module). The Windows preprocessing page stays as the experimental Python route it documents.

5. The analyst — "what's in my output and how do I read it?"

Branch: Tutorials tab (MATLAB, now carrying the v3.0 retirement notice) plus the new Python package page pointing at the notebooks in tools/python/examples/.
Still missing: an output reference — what each dump file (tdump, xytdump, fielddump, slices, fac*, treedump) contains and which switch produces it. Today this knowledge is scattered across the post-processing page and tutorial prose. Second-largest gap; follow-up issue.

6. The contributor

Branch: Development tab gathers DEVELOP, CONTRIBUTING, parallelisation (2DECOMP, previously orphaned), agents guide, and the FORD software docs.
Still missing: CONTRIBUTING dates from 2020 and predates the current test/agents workflow — needs a refresh (follow-up).

Proposed follow-up pages (each a separate issue)

1. Model overview / capabilities (evaluators)
2. Output-variables reference (analysts)
3. Troubleshooting / FAQ (new users; only the Windows page has any today)
4. Restart & warmstart guide (case builders)
5. Scalar boundary conditions + trees/vegetation setup (case builders)
6. CONTRIBUTING refresh (contributors)

🤖 Generated with Claude Code