docs: the settings file has no reference page — mesh: and airfoil: are reachable only through docstrings

[1-Bort-1]

TL;DR

MeshSettings and AirfoilSettings were rendered on the API pages, but no .md page anywhere showed a reader the file those blocks live in — so mesh:, airfoil: and solver: xfoil were reachable only by opening a docstring and guessing the YAML around it. This adds docs/src/settings.md, an annotated vsm_settings.yaml the docs build renders and the test suite loads.

The red check is #300, not this diff

Test end-user and developer setup is red here, and it is not this change: this branch is +139 / −0 across README.md, docs/make.jl, docs/src/index.md, docs/src/settings.md and test/settings/test_settings.jl, with no Julia source in it at all, and that job neither builds the docs nor runs test/settings/.

What fails is examples/ram_air_kite.jl:79 — plot_slices_3d → fit_kulfan_parameters → normalize_airfoil at src/airfoil_aero/kulfan.jl:71, ArgumentError: reducing over an empty collection is not allowed, the empty argmin you get when read_dat_coordinates finds a deflected .dat that is all NaN NaN rows. That is issue #300, whose fix is open as #301.

I checked it against a branch that shares no code with this one rather than inferring it: #305 changes bin/release and nothing else, and its run fails the same job on the same example with the same error and the same 15 passed, 1 failed. The same job is red right now on #302, #306, #301 and #273 too. Every other check on this PR that has finished is green, including Documentation, which is the one that actually exercises the page this PR adds.

I am not fixing it here. It is a src/ bug with its own issue and its own open PR, and pulling it into a docs diff would put two ideas in one PR and take the fix away from the reviewer who has the context for it.

What the page is

One annotated file, all three top-level blocks, with a wing carrying both mesh: and airfoil: annotated field by field. Every field of both blocks appears, because that is the gap the issue names: showing the block and deferring to the docstring for its contents would have moved the problem, not closed it. The split I kept instead is the one CLEAN_CODE.md §3 prescribes for data files — the YAML comment gives a field's meaning, unit and allowed values, and the linked docstring keeps the defaults and the prose. solver_settings: is the exception: the file needs the block to be real, so the sample shows the two keys that are genuinely required plus a representative few, and points at SolverSettings for the rest rather than opening a second field reference.

Three things the page says that a reader could not have worked out from the docstrings: geometry_file resolves against the working directory while the settings path itself resolves under data/; mesh: obj_file: is the mesh sections are generated from and is not the wing's own top-level obj_file, which cannot sit beside geometry_file; and n_panels written under solver_settings: is discarded and recomputed as the sum over the wings.

The sample is executed, not typed

A YAML sample in a markdown file rots silently, so the suite loads this one. test/settings/test_settings.jl extracts the page's own ```yaml fence, parses it, and — the part that actually bites — asserts the key sets of mesh: and `airfoil:` equal `fieldnames(MeshSettings)` and `fieldnames(AirfoilSettings)`. A field added to either struct now fails the suite instead of quietly leaving the page a field short. I checked that it bites rather than assuming it: deleting `n_bins: 60` from the page turns the testset red at 4 passed, 1 failed.

The existing mesh and airfoil blocks testset already covers the parsing itself, so the new one asserts only what is specific to the page and does not restate it.

Where I would push back

No CHANGELOG.md entry. This is documentation with no behaviour change, and #302 is holding that file for the v5.1.0 release; adding a line there would conflict for no gain. Say the word if you would rather see it under a Documentation heading and I will add it after #302 merges.

I also added the pointer line to docs/src/index.md as well as README.md, though the issue asked only for the README. The two files carry that input section identically, and updating one would have left the docs home — the page next door to the new one — as the only place still not mentioning it.

Found, not fixed

• ConditionSettings is unexported and has no docstring, so condition: is the one block the page cannot @ref. Its four fields are annotated in the sample instead. Giving it a docstring is a src/ change and a second idea.
• The shipped data/*/vsm_settings.yaml files carry 20–35-line explanatory headers that this page now duplicates, against CLEAN_CODE.md §3's two-line limit, and the two ram_air_kite files additionally carry decorative top-level Model: / PanelDistribution: / InitialGammaDistribution: blocks the parser never reads. That is a cleanup: PR; say if you want it queued.
• Wing(::VSMSettings) reads settings.wings[1] only, though wings: is a list and vsm_settings_dual.yaml ships two. I left this out of the page: it is Wing's behaviour rather than the file's, but it will surprise someone who writes a second wing.
• obj_to_yaml's own table_format default is :csv while AirfoilSettings.table_format defaults to :arrow, so the same dataset gets a different table format depending on which route configured it.

Verification

• Reproduced first, at fb1eea7: git grep '```yaml' -- docs README.md and git grep -l 'mesh:' -- 'docs/src/*.md' README.md both returned nothing, and git grep 'solver: xfoil' -- '*.md' matched only CHANGELOG.md:38
• test/settings/test_settings.jl 33/33 pass on the current head 99b1815 (juliaserver, 9 + 17 + 5 + 2); new testset 5/5, and red at "4 passed, 1 failed" with n_bins: 60 deleted from the page
• Docs build clean · 20 cross-references on the new page resolve, 0 unresolved @ref in docs/build/settings.html · pre-existing size warnings on private_functions.md and functions.md only
• Sample loads to the expected values: solver: xfoil → XFoilSolver, rotation rows → [0 0 -1; -1 0 0; 0 1 0], sweeps → -180.0:1.0:180.0 and -40.0:10.0:40.0, reynolds → 1.6919889502762433e6, table_format → Symbol arrow, solver_settings.n_panels → 50
• Merged origin/main into the branch at 99b1815; 0 commits behind, and the merge touched no file this PR adds · REUSE lint n/a, this repo has no bin/reuse_lint
• Local full suite: PASS (6 min, Julia 1.12.7, one matrix cell) — run on ca29dc5, before the merge of main
• GitHub CI on 99b1815: Documentation PASS · Julia 1.12 pull_request PASS on ubuntu, macOS and windows · Julia 1.11 coverage PASS · codecov/patch PASS · Test end-user and developer setup FAIL for write_section_aero writes an all-NaN deflected .dat, and read_section_ #300, evidence above · the two remaining coverage jobs were still running when this was written
• Benchmark: n/a
• Risk: the guard reads docs/src/settings.md by path, so the suite needs the repo checkout rather than a stripped install to run that testset.

Scope

+139 / −0 across 5 files, of which docs/src/settings.md is 114. No src/ change, no CHANGELOG entry (see above). Not stacked — of the open PRs only #301 touches docs/src/ at all, and that is private_functions.md, no file this branch opens.

Closes #278 · task VortexStepMethod.jl-278

[1-Bort-1]

Local full suite: PASS (7 min, Julia 1.12.7, one cell of the matrix)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!