Repository navigation
REF: Restructure docs, separate and clarify validation studies - #22
Merged
Merged
Conversation
A bare command name read as a lesser heading than a plain-word one such as Conventions. The sections of the geometry and plot pages now read "The `naca` command", "The `plot foil` command" and so on, at the same level, with explicit ids keeping the old anchors (#naca, #repanel, #polar…) so no link changes.
The Validation pages render with their ironlab figures, so list them again; the Testing tab stays hidden. The index's links name their pages rather than their file paths.
Each tab and section of the navigation is a directory with an index.md and each page is the kebab-case of its title, so the side menu predicts the path: User guide > Commands > Analyse a single point is docs/user-guide/commands/analyse-a-single-point.md. A page's own assets go in a directory beside it named after it. The References page becomes Bibliography, the last page of the Reference section. The Validation pages become validation/index.md, series-cases.md and aerofoil-series.md, and their generators write them there. Every old URL redirects to its new page.
The site was never indexed, so no link into it needs keeping: the redirect map from the old page URLs goes, and moving a page no longer calls for one.
Move scripts/noise-floor.sh to studies/tolerances/tolerances.sh and its page to docs/validation/tolerances.md. The study now writes its tables as Markdown fragments into docs/validation/tables/, which the hand-written page includes through pymdownx.snippets; the fragments are excluded from the page build by Zensical's exclude plugin, for which the pin moves to 0.0.71.
thclark
changed the title
thclark
changed the title
… tabs (#30) * DOC: Restructure the validation and known-issues docs Make Development a docs tab holding the moved conventions/ and testing/ pages, and give Validation one section per study (aerofoil series, series cases, known issues, branch coverage, tolerances), each an index page plus chart pages. Validation pages are now written by hand. Studies no longer write under docs/: each run writes runs/<UTC>/publish/ (studies/study-support/publish.rs), and `cargo xtask publish <study>` copies a run's tables and figures in, refusing if a page uses one the run lacks. A case's page is its `topic` in cases.toml. Split the known XFOIL issues register into a category table in the user guide and, under Validation, a page per category and per numbered issue, with the known-issues runs on reproduction-run pages. Record how each point parts (`parted_by`: a branch decision or a value) and define run parting in the terminology. Add a Citing yFoil page, and scripts/docs-check.py, run by scripts/docs.sh, to enforce the sidebar icon rules and well-formed front matter. * DOC: Add a commands overview page, a use-of-AI note and the ironlab.org links Move the user guide's commands section to commands/overview.md, first under Commands; set out the licence's terms in a table; add a Use of AI section to the Development landing page; point ironlab links at ironlab.org. * DOC: Fix a typo in the use-of-AI section
thclark
added a commit
that referenced
this pull request
Oct 25, 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
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.
Promotes the
improvementstrunk tomain. It carries five PRs:namecommand" #18 Head each command section "Thenamecommand". Command sections in the geometry and plot pages are headed "Thenacacommand" and so on, at the same level, with the old anchors kept as explicit ids.git mv) todocs/user-guide/{get-started,commands,reference}/anddocs/validation/, each tab and section a directory with anindex.mdand each page the kebab-case of its title. References becomes Bibliography. The study generators (series-cases, aerofoil-series, branch-coverage) andsrc/output/figures.rs::embed_htmlwrite the new paths. Comments acrosssrc/,tests/,xtask/andCLAUDE.mdname the new paths.studies/folder. Every study leavesscripts/(which keeps only repo tooling) forstudies/, besidetests/, indexed bystudies/README.md. The noise-floor measurement becomes the tolerances study (studies/tolerances/tolerances.sh, pagedocs/validation/tolerances.md), whose tables are generated fragments indocs/validation/tables/included withpymdownx.snippetsand excluded from page building; Zensical is bumped 0.0.60 → 0.0.71 for theexcludeplugin. Two legacy geometry files committed by accident (aerofoil.json,naca63-415.json) are removed.Committed directly on
improvements:.figonly.src/output/figures.rs::embed_htmldrops its.fig.jsonbranch and always writesformat="fig": the site never embeds.fig.json, which is too slow to load.yfoil plot -o x.fig.jsonis unaffected.PRs into
improvementsdo not run theBuild and Testworkflow, so this PR is the first CI run over these changes; any fixes it needs are added as commits onimprovements.No version bump: the commits are
DOC,REFandCHO(noFEAorFIX), and the repo has nosemanticcheck or release version to bump.