Add developer guides and generate reference pages from the code

.github/workflows/docs-website.yml

@@ -0,0 +1,84 @@
+name: Docs Website
+
+on:
+  push:
+    branches: ['docs_site', 'docs/developer-guides']
+  pull_request:
+    branches: ['docs_site', 'develop']
+  workflow_dispatch:
+    inputs:
+      site_repo:
+        description: Website repository
+        default: rois1995/su2code.github.io
+      site_ref:
+        description: Website commit SHA or branch (use a SHA to reproduce a build)
+        default: docs/user-guides
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-website-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout SU2
+        uses: actions/checkout@v4
+        with:
+          path: su2
+          fetch-depth: 0
+          filter: blob:none
+          persist-credentials: false
+      - name: Get release tags for migration reference
+        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.*'
+      - name: Checkout website
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ inputs.site_repo || 'rois1995/su2code.github.io' }}
+          ref: ${{ inputs.site_ref || 'docs/user-guides' }}
+          path: site
+          fetch-depth: 0
+          filter: blob:none
+          persist-credentials: false
+      - name: Setup Ruby and locked gems
+        uses: ruby/setup-ruby@v1
+        with:
+          working-directory: site
+          ruby-version: .ruby-version
+          bundler: '2.4.22'
+          bundler-cache: true
+      - name: Install code reference tools
+        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz
+      - name: Build and check website
+        env:
+          BUNDLE_PATH: ${{ github.workspace }}/site/vendor/bundle
+        run: python3 su2/Docs/website/tools/build_docs.py --su2 su2 --site site --build-dir "$RUNNER_TEMP/docs-site" --baseurl '/${{ github.event.repository.name }}' --mark-changes
+      - name: Upload checked preview
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-preview
+          path: ${{ runner.temp }}/docs-site/site
+          retention-days: 7
+      - name: Upload Pages artifact
+        if: github.repository == 'rois1995/SU2' && github.ref == 'refs/heads/docs_site' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ${{ runner.temp }}/docs-site/site
+
+  deploy:
+    if: github.repository == 'rois1995/SU2' && github.ref == 'refs/heads/docs_site' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-24.04
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy checked website
+        id: deployment
+        uses: actions/deploy-pages@v4

Docs/website/README.md

@@ -0,0 +1,86 @@
+# SU2 documentation website
+
+The combined site uses two repositories. Developer pages and the generation/build/check tools live here; user pages, model explanations, setup guides, tutorials, V&V, navigation and search live in the website repository. Builds stage copies of both sources; the source checkouts are not overwritten.
+
+## Where an explanation belongs
+
+- **Setup guides:** how to choose settings for a class of problems, why they matter, convergence checks and troubleshooting. Link to worked cases instead of repeating their full instructions.
+- **Tutorials:** complete worked cases, with meshes, configurations, commands and post-processing.
+- **V&V:** numerical evidence, comparisons and their scope; distinguish implementation verification from physical validation.
+- **Model pages:** assumptions, exact model variant, definitions and units, governing equations or precise equation references, and differences between the literature and SU2.
+- **Developer pages:** source locations, control flow, extension steps and appropriate regression or unit checks.
+- **Generated references:** option/output/error facts extracted from the source. Explain extraction limits rather than guessing defaults or applicability.
+
+The website's **Using the Documentation** page explains this structure to readers. Keep general explanations in one place and cross-link them. In a model or developer explanation, identify the source file and checked commit; for a theoretical claim, cite the relevant paper or equation. A regression config establishes usage, not a universal numerical recommendation. Retain draft labels until the stated review is complete.
+
+## Editing
+
+Keep completed improvements, remaining gaps and their evidence in `pages/Documentation-Status.md`, listed under **Developer Docs**. Update its status and dated history when a batch is completed; use the generated reports for current build counts.
+
+Developer pages live in `pages/`, with `title` and `permalink: /docs_v7/<File-Name>/` front matter. `Adding-...` pages appear under **How to Add...**; other new pages appear under **Developer Docs**. Images in `pages/img/` are copied to `docs_files/website/`.
+
+After checking a developer page against the implementation, update its `Last checked against SU2 develop <commit>` line. The Docs Check page flags named files changed since that commit; this is a review prompt, not a proof that the page is wrong or complete.
+
+Option descriptions belong above their registration in `Common/src/CConfig.cpp`, using the existing Doxygen `DESCRIPTION:`, `OPTIONS:` and `DEFAULT:` conventions. Keep examples in `config_template.cfg` consistent with the parser. Defaults set elsewhere may not be extractable; a template example is not necessarily a default. Simple string literals and string constructors are shown as configuration values; unresolved string expressions are labelled as C++ expressions. The reference also links to relevant pages and regression configurations.
+
+The generator copies these pages and Markdown notes from code folders into a staged website. It produces the option, output, error and migration references and the Docs Check page, then updates navigation. Do not edit these generated copies in the website repository.
+
+## Local build
+
+Requirements: Python 3.8 or newer, Git, Ruby **3.3.12** (the website's `.ruby-version`), Bundler **2.4.22**, Doxygen and Graphviz. Use an existing Ruby version manager to select the required Ruby; the system Ruby need not change. The website's tracked `Gemfile.lock` fixes gem versions.
+
+With the two `docs_site` checkouts, run from the SU2 source root:
+
+```sh
+# Set these paths to your two existing checkouts/output folder.
+WEBSITE_SOURCE=/path/to/su2code.github.io
+DOCS_BUILD=/path/to/docs-build
+
+gem install bundler -v 2.4.22
+BUNDLE_GEMFILE="$WEBSITE_SOURCE/Gemfile" bundle _2.4.22_ install
+python3 Docs/website/tools/build_docs.py --site "$WEBSITE_SOURCE" --build-dir "$DOCS_BUILD" --baseurl /SU2 --mark-changes
+mkdir -p "$DOCS_BUILD/serve"
+ln -sfn ../site "$DOCS_BUILD/serve/SU2"
+python3 -m http.server 8765 --directory "$DOCS_BUILD/serve"
+```
+
+Open `http://localhost:8765/SU2/`. For a direct server without the symlink/prefix, build with `--baseurl ''`, serve `$DOCS_BUILD/site` and open `http://localhost:8765/`.
+
+`--mark-changes` preserves the red highlighting of added/modified menu items, menu sections and page titles compared with the official site. Both CI workflows pass it. This debug comparison fetches upstream website history; if unavailable, generated/developer pages remain highlighted and the build reports the limitation.
+
+The build directory must be outside both source trees. It must be empty on first use; subsequent runs replace only its managed `source`, `site` and `doxygen` subdirectories. Keep source files elsewhere. Omitted download folders link to the official site.
+
+The same command builds Doxygen, stages the site, generates references, builds Jekyll, adjusts subpath links, and checks the assembled result. It runs the Python tests first and fails on new documentation problems. There is no separate local assembly recipe.
+
+## Checks and existing debt
+
+Run the small checks directly when changing tooling:
+
+```sh
+python3 -m unittest discover -s Docs/website/tools
+```
+
+The full build checks local links and anchors in current documentation, Tutorials and V&V; configuration option names and enum keywords in configuration blocks; descriptions for newly added options; search entries and searchable output-field names. It does not request external URLs or establish that numerical examples are converged. Solver-specific option combinations still require appropriate SU2 tests.
+
+`tools/check-baseline.json` retains 24 options missing source descriptions. The 22 October follow-up resolved the 180 historical links, eight unknown template names and one obsolete enum keyword; those baseline arrays are empty. Existing link findings remain visible in the machine-readable `docs-check.json`; new findings fail the build. Remove an entry when its problem is fixed. Do not regenerate the baseline to approve new regressions. The generated Docs Check page also lists source-description and stale-page work.
+
+Each assembled site includes:
+
+- `build-info.json`: both source commit SHAs, whether either working tree was dirty, the gem lock hash, base path, build flags and tool versions.
+- `docs-check.json`: new problems, checked-reference/search counts and existing link findings.
+
+For a reproducible rebuild, check out the two recorded SHAs, select the recorded Ruby and locked gems, and use the recorded base path and flags. Dirty working trees are useful for previews but cannot be reconstructed from commit SHAs alone. Doxygen/Graphviz versions are recorded, not pinned; changes in those tools can change generated output. The date on the option reference comes from the source commits through `SOURCE_DATE_EPOCH`.
+
+## CI and publishing
+
+`.github/workflows/docs-website.yml` checks pushes to `docs_site` and `docs/developer-guides`, and pull requests targeting `develop` or `docs_site`. The PR preparation uses website branch `docs/user-guides` by default. Pull requests and pushes to the preparation branch upload checked previews without deploying. Publishing is restricted to `docs_site` runs in `rois1995/SU2`; the workflow does not publish from the official SU2 repository. Checkout references are resolved once; the manifest records the exact revisions used.
+
+The website repository's `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 a checked preview. Website-only changes therefore get checks without cross-repository write credentials. After those checks pass, publish from the SU2 **Docs Website** workflow, choosing the website commit SHA as `site_ref`:
+
+```sh
+gh workflow run docs-website.yml --repo rois1995/SU2 --ref docs_site -f site_repo=rois1995/su2code.github.io -f site_ref=<website-commit-sha>
+```
+
+To reproduce a historical deployment, select its SU2 revision as well. Normal branch builds follow the current website branch; use a commit SHA when reviewing or reproducing a particular pair of changes. Changes to workflow files require GitHub credentials allowed to update workflows; ordinary repository-only OAuth scopes may reject them.
+
+The paired sources currently use the `rois1995` forks. Publish both preparation branches to the forks before relying on their combined checks; a run started before the other branch is available may need to be repeated. Official website publishing remains a separate integration decision. Do not push these development branches directly to the official repositories.