Skip to content

Improve user guides, model explanations and documentation search - #222

Merged
rois1995 merged 25 commits into
su2code:developfrom
rois1995:docs/user-guides
Oct 30, 2026
Merged

rois1995 merged 25 commits into
su2code:developfrom
rois1995:docs/user-guides

Conversation

@rois1995

@rois1995 rois1995 commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

This makes the documentation easier to navigate and brings older explanations and examples into line with the code.

  • Clarify the page roles and navigation, keeping worked cases in Tutorials and numerical comparisons in V&V.
  • Add explanations of turbulence, transition, hybrid RANS/LES and wall treatment, with links to model references.
  • Add nine setup guides, troubleshooting and version-8 migration guidance.
  • Correct outdated settings, units, model descriptions and broken links in existing pages.
  • Add search across the documentation, Tutorials and V&V, and connect the user pages to the developer guides and generated references.

The setup guides remain marked as drafts where specialist review is still needed. A status page records completed work and remaining gaps, including 24 configuration options that still lack source descriptions.

The combined build passes 18 documentation tests and checks 26,164 internal references and 179 search entries with zero findings. The website GitHub check passed the same checks and regression checks for search loading, short queries and failed index downloads. Changed sections are marked in red in the preview.

Companion SU2 PR: su2code/SU2#2992. The NACA 0021 case and DES updates are proposed separately in #223.

Combined preview — this preview follows the docs_site branches and includes the proposed NACA 0021 contribution.

rois1995 and others added 23 commits October 26, 2026 11:15
Rename options that were renamed in the code (KIND_SOLVER and
PHYSICAL_PROBLEM to SOLVER, KT_CONSTANT to THERMAL_CONDUCTIVITY_CONSTANT,
RAMP_ROTATING_FRAME to RAMP_MOTION_FRAME, UNST_ADJOINT_START_ITER to
UNST_ADJOINT_ITER, CFL to CFL_NUMBER, SPECIES_USE_STRONG_BC to
MARKER_SPECIES_STRONG_BC), fix the MAKER_SPECIES_STRONG_BC typo and
remove CONV_CRITERIA, which CONV_FIELD replaces.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NSfEWrhpF27TnrkJH74sv8
Each change was checked against SU2 develop 11c177b904: solver names,
SST default version and keywords, scalar schemes, shape_optimization.py
options, turbomachinery ramp options, INCONSISTENT_DISC, flamelet and
species options and value counts, reference temperature and contact
resistance units.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NSfEWrhpF27TnrkJH74sv8
Nine draft guides (RANS external aero, incompressible, unsteady and DES,
transition, turbomachinery, heat transfer and CHT, species and
combustion, shape optimization, non-ideal flows) in a new menu section.
Settings come from the code, tutorials and test cases; each statement
names its source, and advice that needs an expert check is marked
"to be reviewed".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NSfEWrhpF27TnrkJH74sv8
The plugins were listed but not whitelisted, so GitHub Pages skipped
them: feed.xml and sitemap.xml were missing. The old v6 docs stay
online for old links but are left out of the sitemap. The search page
uses an index of the docs, tutorials and V&V pages made at build time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NSfEWrhpF27TnrkJH74sv8
Turbulence Models, Transition Models, Hybrid RANS/LES and Wall Treatment
in a new Physical Models menu section. Physical Definition keeps short
pointers. The NASA Turbulence Modeling Resource moved to
tmbwg.github.io/turbmodels; the old links redirect to a landing page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NSfEWrhpF27TnrkJH74sv8
The second list (jekyll-gist only) replaced the first one, so the feed,
SEO and sitemap plugins never ran and feed.xml and sitemap.xml were
missing on the website.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NSfEWrhpF27TnrkJH74sv8
Table of contents links now match the real section ids, and links to
.md files now point to the page addresses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NSfEWrhpF27TnrkJH74sv8
Common problems with the config, mesh, restart, divergence, convergence,
output and parallel runs: what you see, why, and what to do.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NSfEWrhpF27TnrkJH74sv8
Also fixes the multigrid note in Guide-to-v8 (the damping default is now
0.5) and two statements that did not match the test cases.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NSfEWrhpF27TnrkJH74sv8

@bigfooted bigfooted left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good, let's have a look at what needs to be kept from v7 later this year.

@rois1995
rois1995 merged commit a0bdd59 into su2code:develop Oct 30, 2026
2 checks passed
@rois1995
rois1995 deleted the docs/user-guides branch October 30, 2026 08:40
rois1995 added a commit to su2code/SU2 that referenced this pull request Nov 21, 2026
…notes (#2992)

## Proposed Changes

Correct outdated settings in `config_template.cfg` and the flamelet
boundary-condition notes. The CFD algorithms are unchanged.

## Related Work and Merge Order

Merge this PR before [website PR
#232](su2code/su2code.github.io#232). The
website's reference checks need the corrections in this PR. Once this PR
is merged, switch the website PR's CI from the temporary SU2 fork branch
to upstream `develop` and verify the checks before merging it.

The developer guides and reference generator have moved to the website
PR. The related user guides, search and navigation are in [website PR
#222](su2code/su2code.github.io#222).

## PR Checklist

- [x] I am submitting my contribution to the develop branch.
- [ ] My contribution generates no new compiler warnings (try with
--warnlevel=3 when using meson).
- [x] My contribution is commented and consistent with SU2 style
(https://su2code.github.io/docs_v7/Style-Guide/).
- [x] I used the pre-commit hook to prevent dirty commits and used
`pre-commit run --all` to format old commits.
- [x] I have added a test case that demonstrates my contribution, if
necessary.
- [x] I have updated appropriate documentation (Tutorials, Docs Page,
config_template.cpp), if necessary.

[Combined website preview](https://rois1995.github.io/SU2/)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: SU2 local assessment <local-assessment@invalid>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants