struphy-hub.github.io

The Struphy documentation site: an Astro site in docs/, backed by data generated from the Struphy Python package (checked out here as a git submodule).

Building the site locally

1. Get the code, including the Struphy submodule

git clone --recurse-submodules git@github.com:struphy-hub/struphy-hub.github.io.git
cd struphy-hub.github.io

If you already cloned without --recurse-submodules:

git submodule update --init

2. Install Struphy from the submodule

Requires Python 3.12. From the repo root:

python -m venv .venv
source .venv/bin/activate
pip install ./submodules/struphy

3. Generate the site's data

These scripts (repo root) import Struphy classes and export the JSON/VTK/image data the site pages are built from:

python generate_all.py

which just runs, in order:

python generate_models.py
python generate_domains.py docs/public/domains
python generate_equilibrium_slices.py
python generate_perturbations.py
python generate_model_graph.py

Each one prints what it generated (and skips) as it runs. Their output lives under docs/src/data/ and docs/public/domains/.

4. Build the Astro site

Requires Node.js >= 22.12. From docs/:

cd docs
npm ci
npm run build

The built site is written to docs/dist/. Use npm run dev instead for a local dev server (both dev and build automatically regenerate docs/src/data/catalogue-index.json / catalogue-details.json and docs/src/data/examples-index.json from the data produced in step 3, via their pre* npm hooks).

The full pipeline (including the CI-specific steps) is defined in .github/workflows/deploy.yml, which is the source of truth if these instructions drift.

Example gallery scripts (optional)

docs/src/examples/*.py are full, runnable Struphy simulations shown on the /examples/ pages, separate from the data pipeline above. They need struphy compile and a heavier install (pip install './submodules/struphy[mpi]', or whatever extras the example needs) and aren't required to build the site. generate_examples.py (repo root) generates their page metadata (name, description, equations, config summary) by importing each script without running its simulation — see docs/src/examples/README.md for the full step-by-step guide to adding a new example.

Each example's page lives at docs/src/pages/examples/<script-stem>/, matching its <script-stem>.metadata.json. docs/scripts/generate-examples-index.mjs (run automatically by the pre* npm hooks above) collects every example's metadata — including the model field generate_examples.py fills in — into docs/src/data/examples-index.json, which both /examples/ and each model's /models/<slug>/ page read to link examples to their model automatically. No manual list to keep in sync.