Skip to content

Commit a0bdd59

Browse files
rois1995rois1995
authored
Merge pull request #222 from rois1995/docs/user-guides
Improve user guides, model explanations and documentation search
2 parents ac2ce4e + b87e19c commit a0bdd59

79 files changed

Lines changed: 5209 additions & 361 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/docs-check.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
name: Documentation Checks
2+
3+
on:
4+
push:
5+
branches: ['docs_site', 'docs/user-guides', 'docs/naca0021']
6+
pull_request:
7+
branches: ['docs_site', 'develop', 'docs/user-guides']
8+
workflow_dispatch:
9+
inputs:
10+
su2_ref:
11+
description: SU2 commit SHA or branch
12+
default: docs/developer-guides
13+
14+
permissions:
15+
contents: read
16+
17+
concurrency:
18+
group: docs-check-${{ github.event_name }}-${{ github.ref }}
19+
cancel-in-progress: true
20+
21+
jobs:
22+
check:
23+
runs-on: ubuntu-24.04
24+
steps:
25+
- name: Checkout website under review
26+
uses: actions/checkout@v4
27+
with:
28+
path: site
29+
fetch-depth: 0
30+
filter: blob:none
31+
persist-credentials: false
32+
- name: Checkout SU2 documentation tools
33+
uses: actions/checkout@v4
34+
with:
35+
repository: rois1995/SU2
36+
ref: ${{ inputs.su2_ref || 'docs/developer-guides' }}
37+
path: su2
38+
fetch-depth: 0
39+
filter: blob:none
40+
persist-credentials: false
41+
- name: Get release tags for migration reference
42+
run: git -C su2 fetch --quiet --filter=blob:none https://github.com/su2code/SU2.git 'refs/tags/v7.*:refs/tags/v7.*' 'refs/tags/v8.*:refs/tags/v8.*'
43+
- name: Setup Node for search checks
44+
uses: actions/setup-node@v4
45+
with:
46+
node-version: '22'
47+
- name: Check search behavior
48+
run: node site/tools/test_search.js
49+
- name: Setup Ruby and locked gems
50+
uses: ruby/setup-ruby@v1
51+
with:
52+
working-directory: site
53+
ruby-version: .ruby-version
54+
bundler: '2.4.22'
55+
bundler-cache: true
56+
- name: Install code reference tools
57+
run: sudo apt-get update && sudo apt-get install -y doxygen graphviz
58+
- name: Build and check website
59+
env:
60+
GITHUB_REPOSITORY: rois1995/SU2
61+
BUNDLE_PATH: ${{ github.workspace }}/site/vendor/bundle
62+
run: python3 su2/Docs/website/tools/build_docs.py --su2 su2 --site site --build-dir "$RUNNER_TEMP/docs-site" --baseurl /SU2 --mark-changes
63+
- name: Upload checked preview
64+
uses: actions/upload-artifact@v4
65+
with:
66+
name: docs-preview
67+
path: ${{ runner.temp }}/docs-site/site
68+
retention-days: 7

‎.gitignore‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,11 @@
22
# https://jekyllrb.com/docs/structure/
33
/_site
44

5-
# bundler snapshot of all gems and versions that it installed
6-
# https://bundler.io/rationale.html
7-
Gemfile.lock
5+
# Keep Gemfile.lock tracked so local and CI builds use the same gems.
86

97
.jekyll-metadata
8+
9+
# Local/CI dependency and Jekyll caches
10+
.bundle/
11+
vendor/bundle/
12+
.jekyll-cache/

‎.ruby-version‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
3.3.12

‎Gemfile.lock‎

Lines changed: 282 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,282 @@
1+
GEM
2+
remote: https://rubygems.org/
3+
specs:
4+
activesupport (7.1.6)
5+
base64
6+
benchmark (>= 0.3)
7+
bigdecimal
8+
concurrent-ruby (~> 1.0, >= 1.0.2)
9+
connection_pool (>= 2.2.5)
10+
drb
11+
i18n (>= 1.6, < 2)
12+
logger (>= 1.4.2)
13+
minitest (>= 5.1)
14+
mutex_m
15+
securerandom (>= 0.3)
16+
tzinfo (~> 2.0)
17+
addressable (2.9.0)
18+
public_suffix (>= 2.0.2, < 8.0)
19+
base64 (0.2.0)
20+
benchmark (0.5.0)
21+
bigdecimal (4.1.3)
22+
coffee-script (2.4.1)
23+
coffee-script-source
24+
execjs
25+
coffee-script-source (1.12.2)
26+
colorator (1.1.0)
27+
commonmarker (0.23.12)
28+
concurrent-ruby (1.3.8)
29+
connection_pool (2.5.5)
30+
dnsruby (1.72.3)
31+
base64 (~> 0.2.0)
32+
simpleidn (~> 0.2.1)
33+
drb (2.2.3)
34+
em-websocket (0.5.3)
35+
eventmachine (>= 0.12.9)
36+
http_parser.rb (~> 0)
37+
ethon (0.18.0)
38+
ffi (>= 1.15.0)
39+
logger
40+
eventmachine (1.2.7)
41+
execjs (2.10.2)
42+
json (>= 2)
43+
faraday (2.8.1)
44+
base64
45+
faraday-net_http (>= 2.0, < 3.1)
46+
ruby2_keywords (>= 0.0.4)
47+
faraday-net_http (3.0.2)
48+
ffi (1.17.4)
49+
forwardable-extended (2.6.0)
50+
gemoji (4.1.0)
51+
github-pages (231)
52+
github-pages-health-check (= 1.18.2)
53+
jekyll (= 3.9.5)
54+
jekyll-avatar (= 0.8.0)
55+
jekyll-coffeescript (= 1.2.2)
56+
jekyll-commonmark-ghpages (= 0.4.0)
57+
jekyll-default-layout (= 0.1.5)
58+
jekyll-feed (= 0.17.0)
59+
jekyll-gist (= 1.5.0)
60+
jekyll-github-metadata (= 2.16.1)
61+
jekyll-include-cache (= 0.2.1)
62+
jekyll-mentions (= 1.6.0)
63+
jekyll-optional-front-matter (= 0.3.2)
64+
jekyll-paginate (= 1.1.0)
65+
jekyll-readme-index (= 0.3.0)
66+
jekyll-redirect-from (= 0.16.0)
67+
jekyll-relative-links (= 0.6.1)
68+
jekyll-remote-theme (= 0.4.3)
69+
jekyll-sass-converter (= 1.5.2)
70+
jekyll-seo-tag (= 2.8.0)
71+
jekyll-sitemap (= 1.4.0)
72+
jekyll-swiss (= 1.0.0)
73+
jekyll-theme-architect (= 0.2.0)
74+
jekyll-theme-cayman (= 0.2.0)
75+
jekyll-theme-dinky (= 0.2.0)
76+
jekyll-theme-hacker (= 0.2.0)
77+
jekyll-theme-leap-day (= 0.2.0)
78+
jekyll-theme-merlot (= 0.2.0)
79+
jekyll-theme-midnight (= 0.2.0)
80+
jekyll-theme-minimal (= 0.2.0)
81+
jekyll-theme-modernist (= 0.2.0)
82+
jekyll-theme-primer (= 0.6.0)
83+
jekyll-theme-slate (= 0.2.0)
84+
jekyll-theme-tactile (= 0.2.0)
85+
jekyll-theme-time-machine (= 0.2.0)
86+
jekyll-titles-from-headings (= 0.5.3)
87+
jemoji (= 0.13.0)
88+
kramdown (= 2.4.0)
89+
kramdown-parser-gfm (= 1.1.0)
90+
liquid (= 4.0.4)
91+
mercenary (~> 0.3)
92+
minima (= 2.5.1)
93+
nokogiri (>= 1.13.6, < 2.0)
94+
rouge (= 3.30.0)
95+
terminal-table (~> 1.4)
96+
github-pages-health-check (1.18.2)
97+
addressable (~> 2.3)
98+
dnsruby (~> 1.60)
99+
octokit (>= 4, < 8)
100+
public_suffix (>= 3.0, < 6.0)
101+
typhoeus (~> 1.3)
102+
html-pipeline (2.14.3)
103+
activesupport (>= 2)
104+
nokogiri (>= 1.4)
105+
http_parser.rb (0.8.1)
106+
i18n (1.14.8)
107+
concurrent-ruby (~> 1.0)
108+
jekyll (3.9.5)
109+
addressable (~> 2.4)
110+
colorator (~> 1.0)
111+
em-websocket (~> 0.5)
112+
i18n (>= 0.7, < 2)
113+
jekyll-sass-converter (~> 1.0)
114+
jekyll-watch (~> 2.0)
115+
kramdown (>= 1.17, < 3)
116+
liquid (~> 4.0)
117+
mercenary (~> 0.3.3)
118+
pathutil (~> 0.9)
119+
rouge (>= 1.7, < 4)
120+
safe_yaml (~> 1.0)
121+
jekyll-avatar (0.8.0)
122+
jekyll (>= 3.0, < 5.0)
123+
jekyll-coffeescript (1.2.2)
124+
coffee-script (~> 2.2)
125+
coffee-script-source (~> 1.12)
126+
jekyll-commonmark (1.4.0)
127+
commonmarker (~> 0.22)
128+
jekyll-commonmark-ghpages (0.4.0)
129+
commonmarker (~> 0.23.7)
130+
jekyll (~> 3.9.0)
131+
jekyll-commonmark (~> 1.4.0)
132+
rouge (>= 2.0, < 5.0)
133+
jekyll-default-layout (0.1.5)
134+
jekyll (>= 3.0, < 5.0)
135+
jekyll-feed (0.17.0)
136+
jekyll (>= 3.7, < 5.0)
137+
jekyll-gist (1.5.0)
138+
octokit (~> 4.2)
139+
jekyll-github-metadata (2.16.1)
140+
jekyll (>= 3.4, < 5.0)
141+
octokit (>= 4, < 7, != 4.4.0)
142+
jekyll-include-cache (0.2.1)
143+
jekyll (>= 3.7, < 5.0)
144+
jekyll-mentions (1.6.0)
145+
html-pipeline (~> 2.3)
146+
jekyll (>= 3.7, < 5.0)
147+
jekyll-optional-front-matter (0.3.2)
148+
jekyll (>= 3.0, < 5.0)
149+
jekyll-paginate (1.1.0)
150+
jekyll-readme-index (0.3.0)
151+
jekyll (>= 3.0, < 5.0)
152+
jekyll-redirect-from (0.16.0)
153+
jekyll (>= 3.3, < 5.0)
154+
jekyll-relative-links (0.6.1)
155+
jekyll (>= 3.3, < 5.0)
156+
jekyll-remote-theme (0.4.3)
157+
addressable (~> 2.0)
158+
jekyll (>= 3.5, < 5.0)
159+
jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
160+
rubyzip (>= 1.3.0, < 3.0)
161+
jekyll-sass-converter (1.5.2)
162+
sass (~> 3.4)
163+
jekyll-seo-tag (2.8.0)
164+
jekyll (>= 3.8, < 5.0)
165+
jekyll-sitemap (1.4.0)
166+
jekyll (>= 3.7, < 5.0)
167+
jekyll-swiss (1.0.0)
168+
jekyll-theme-architect (0.2.0)
169+
jekyll (> 3.5, < 5.0)
170+
jekyll-seo-tag (~> 2.0)
171+
jekyll-theme-cayman (0.2.0)
172+
jekyll (> 3.5, < 5.0)
173+
jekyll-seo-tag (~> 2.0)
174+
jekyll-theme-dinky (0.2.0)
175+
jekyll (> 3.5, < 5.0)
176+
jekyll-seo-tag (~> 2.0)
177+
jekyll-theme-hacker (0.2.0)
178+
jekyll (> 3.5, < 5.0)
179+
jekyll-seo-tag (~> 2.0)
180+
jekyll-theme-leap-day (0.2.0)
181+
jekyll (> 3.5, < 5.0)
182+
jekyll-seo-tag (~> 2.0)
183+
jekyll-theme-merlot (0.2.0)
184+
jekyll (> 3.5, < 5.0)
185+
jekyll-seo-tag (~> 2.0)
186+
jekyll-theme-midnight (0.2.0)
187+
jekyll (> 3.5, < 5.0)
188+
jekyll-seo-tag (~> 2.0)
189+
jekyll-theme-minimal (0.2.0)
190+
jekyll (> 3.5, < 5.0)
191+
jekyll-seo-tag (~> 2.0)
192+
jekyll-theme-modernist (0.2.0)
193+
jekyll (> 3.5, < 5.0)
194+
jekyll-seo-tag (~> 2.0)
195+
jekyll-theme-primer (0.6.0)
196+
jekyll (> 3.5, < 5.0)
197+
jekyll-github-metadata (~> 2.9)
198+
jekyll-seo-tag (~> 2.0)
199+
jekyll-theme-slate (0.2.0)
200+
jekyll (> 3.5, < 5.0)
201+
jekyll-seo-tag (~> 2.0)
202+
jekyll-theme-tactile (0.2.0)
203+
jekyll (> 3.5, < 5.0)
204+
jekyll-seo-tag (~> 2.0)
205+
jekyll-theme-time-machine (0.2.0)
206+
jekyll (> 3.5, < 5.0)
207+
jekyll-seo-tag (~> 2.0)
208+
jekyll-titles-from-headings (0.5.3)
209+
jekyll (>= 3.3, < 5.0)
210+
jekyll-twitter-plugin (2.1.0)
211+
jekyll-watch (2.2.1)
212+
listen (~> 3.0)
213+
jemoji (0.13.0)
214+
gemoji (>= 3, < 5)
215+
html-pipeline (~> 2.2)
216+
jekyll (>= 3.0, < 5.0)
217+
json (3.1.0)
218+
kramdown (2.4.0)
219+
rexml
220+
kramdown-parser-gfm (1.1.0)
221+
kramdown (~> 2.0)
222+
liquid (4.0.4)
223+
listen (3.10.1)
224+
logger
225+
rb-fsevent (~> 0.10, >= 0.10.3)
226+
rb-inotify (~> 0.9, >= 0.9.10)
227+
logger (1.7.0)
228+
mercenary (0.3.6)
229+
mini_portile2 (2.8.9)
230+
minima (2.5.1)
231+
jekyll (>= 3.5, < 5.0)
232+
jekyll-feed (~> 0.9)
233+
jekyll-seo-tag (~> 2.1)
234+
minitest (5.26.1)
235+
mutex_m (0.3.0)
236+
nokogiri (1.15.7)
237+
mini_portile2 (~> 2.8.2)
238+
racc (~> 1.4)
239+
octokit (4.25.1)
240+
faraday (>= 1, < 3)
241+
sawyer (~> 0.9)
242+
pathutil (0.16.2)
243+
forwardable-extended (~> 2.6)
244+
public_suffix (5.1.1)
245+
racc (1.8.1)
246+
rb-fsevent (0.11.2)
247+
rb-inotify (0.11.1)
248+
ffi (~> 1.0)
249+
rexml (3.4.4)
250+
rouge (3.30.0)
251+
ruby2_keywords (0.0.5)
252+
rubyzip (2.4.1)
253+
safe_yaml (1.0.5)
254+
sass (3.7.4)
255+
sass-listen (~> 4.0.0)
256+
sass-listen (4.0.0)
257+
rb-fsevent (~> 0.9, >= 0.9.4)
258+
rb-inotify (~> 0.9, >= 0.9.7)
259+
sawyer (0.9.3)
260+
addressable (>= 2.3.5)
261+
faraday (>= 0.17.3, < 3)
262+
securerandom (0.3.2)
263+
simpleidn (0.2.3)
264+
terminal-table (1.8.0)
265+
unicode-display_width (~> 1.1, >= 1.1.1)
266+
typhoeus (1.6.0)
267+
ethon (>= 0.18.0)
268+
tzinfo (2.0.6)
269+
concurrent-ruby (~> 1.0)
270+
unicode-display_width (1.8.0)
271+
webrick (1.9.2)
272+
273+
PLATFORMS
274+
ruby
275+
276+
DEPENDENCIES
277+
github-pages
278+
jekyll-twitter-plugin
279+
webrick
280+
281+
BUNDLED WITH
282+
2.4.22

‎README.md‎

Lines changed: 21 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,23 @@
1-
# su2code.github.io
2-
[Link to Website](https://su2code.github.io/)
1+
# SU2 website
32

4-
## For Developers
3+
[Official website](https://su2code.github.io/) · [Documentation preview](https://rois1995.github.io/SU2/)
54

6-
In order to make any changes in the documentation of SU2, the files in [_docs_v7/](_docs_v7) should be touched. This is the documentation which is currently online.
5+
## Editing documentation
6+
7+
User guide, setup and model pages live in `_docs_v7/`; worked examples live in `_tutorials/`; verification and validation comparisons live in `_vandv/`. Navigation is in `_data/`, and `search.json` indexes those three collections. The `docs_v7` URL is retained for compatibility; check the version stated on each page.
8+
9+
Keep each explanation in the appropriate section and link to related pages. See `_docs_v7/Using-the-Documentation.md` for their roles and evidence conventions. The nine setup guides share `_includes/setup-guide-intro.md`; retain draft labels and review marks until the stated review is complete.
10+
11+
Developer pages and generated references are overlaid from the SU2 repository. Edit developer pages in `Docs/website/pages/` there and option descriptions in the source; do not create competing copies here.
12+
13+
## Building and checking
14+
15+
Use Ruby **3.3.12** from `.ruby-version` and Bundler **2.4.22** with the tracked `Gemfile.lock`. The combined build entry point is `Docs/website/tools/build_docs.py` in the SU2 checkout. Its README, `Docs/website/README.md`, gives the local commands and output-directory rules. It builds and checks the same staged site locally and in CI, including red preview highlighting when `--mark-changes` is passed.
16+
17+
`.github/workflows/docs-check.yml` checks pushes to `docs_site`, `docs/user-guides` and `docs/naca0021`, and pull requests targeting `develop`, `docs_site` or `docs/user-guides`. It uses SU2 branch `docs/developer-guides` by default and uploads `docs-preview`. A manual run accepts an exact SU2 SHA through `su2_ref`. It checks internal references, search coverage, documented option names and source descriptions for new options. Historical findings are tracked explicitly in SU2's `check-baseline.json`; new findings fail.
18+
19+
Search behavior is checked separately with Node.js 22: run `node tools/test_search.js` from this repository. CI runs the same check before building the site. No npm packages are needed.
20+
21+
Website-only changes do not publish directly to SU2's Pages site. Publishing is currently restricted to `docs_site` in `rois1995/SU2`. First ensure that branch contains the reviewed SU2 tools, then start **Docs Website** there with the reviewed website commit SHA as `site_ref`. Check both recorded source revisions against the reviewed build before accepting the deployment. The result records both commit SHAs and tool versions in `build-info.json` and check results in `docs-check.json`. This avoids requiring a token with cross-repository write access for website pull requests.
22+
23+
The current preview uses the `rois1995` forks. Website PR branches are `docs/user-guides` and `docs/naca0021`; `docs_site` is the existing published preview branch. Submit upstream changes through pull requests to `develop`. Do not push development branches directly to the official repositories.

0 commit comments

Comments
 (0)