docs: PiWind end-to-end + step-by-step notebooks + intersphinx - #42
Open
sstruzik wants to merge 7 commits into
Open
docs: PiWind end-to-end + step-by-step notebooks + intersphinx#42sstruzik wants to merge 7 commits into
sstruzik wants to merge 7 commits into
Conversation
Stand up an executable docs project in OasisModels (Furo + myst-nb) and add the high-level worked example tutorials/run-piwind-analysis.md: shows the single 'oasislmf model run -C config' command (full pytools pipeline modelpy->gulmc->fmpy-> summarypy->eltpy/pltpy/lecpy/aalpy) and analyses the ORD outputs it produces (SELT, OEP/AEP EP curves for GUL & IL, losses at return periods) from a committed sample of a real PiWind run. Engine shown as a command, not executed at build; analysis cells execute (verified). ORD EPType/EPCalc semantics per ODS_OpenResultsData. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add tutorials/pipeline-step-by-step.md decomposing the generated run_kernel.sh pipeline stage by stage: evepy -> gulmc -> fmpy -> summarypy -> eltpy/pltpy/lecpy/ aalpy. Each stage shows the real command (extracted from the script) and the intermediary stream data (events, GUL item-level losses with the sidx statistics, FM insured losses), produced by running each pytools tool once on a single event and converted with bintocsv. Engine shown as commands, not executed at build; sample-loading cells execute (verified by render). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the orchestrator-driven intersphinx block so the models docs can cross-reference the other Oasis component sites in the aggregated build. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add the Oasis logo (light/dark, always visible in the Furo sidebar), the maroon/red Raleway palette matching oasislmf.github.io, and a persistent 'Oasis documentation home' link (rewritten to page-relative by the aggregator) so you can return to the top of the aggregated site from anywhere. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The sidebar logo now returns to the aggregated landing, so the redundant 'Oasis documentation home' announcement bar is removed. Add the GitHub link in Furo's conventional spot — the footer icons (bottom of every page). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
sstruzik
marked this pull request as ready for review
August 11, 2026 08:58
`environ.get(NAME, "{}")` only substitutes the default when the variable is UNSET, so
exporting it empty reached json.loads("") and aborted the build with a traceback instead
of falling back to no cross-component inventories. Now `environ.get(NAME) or "{}"`.
Latent rather than live: the GenerateDocs orchestrator always writes valid JSON via
json.dumps, so it triggers only when the variable is exported empty by hand or by a CI
step. Found while reworking the same block in ODS_Tools (#289, 10e38ba) and applied
across the remaining components for consistency.
Verified by executing conf.py with the variable unset, set-but-empty and mapped: all
three succeed, and any pre-existing intersphinx_mapping entries are preserved.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
autopep8 --diff --exit-code, which OasisLMF runs recursively over the repo, flagged `import json as _ix_json, os as _ix_os` as E401. Pre-existing, and dormant only because the code-quality workflow is not among the checks triggered on the docs PRs. Same change ODS_Tools already took in eb349ea, so all six components now have an identical, lint-clean cross-component block. Verified: 0 autopep8 findings for this file (was 3), the CI flake8 selection is clean, and conf.py still executes with OASIS_INTERSPHINX_MAP unset, set-but-empty and mapped. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
2 participants
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.
Adds executable, end-to-end model documentation to the repository that has the models and the CI to keep it honest.
Part of the cross-repo Oasis documentation restructure (Option B): each repository owns the docs for what it owns, and
GenerateDocsaggregates them into the published site.Why here
Worked examples that actually run a model belong in the model repository, not in the orchestrator (which has no engine) and not in OasisLMF (which has no model data). This repository has both, plus
model-testsCI, so the examples are exercised rather than assumed.What this adds
tutorials/run-piwind-analysis— the high-level path:oasislmf model run -C config, then analysis of the ORD outputs (SELT, OEP/AEP EP curves).tutorials/pipeline-step-by-step— the same run decomposed into the kernel pipeline (evepy→gulmc→fmpy→summarypy→eltpy/…), with the real commands and the intermediate stream data at each stage..ipynb.The engine invocation itself is shown as a command rather than executed at build time, since running a model needs the model data and the loss engine; the analysis of its output is what executes.
Review-round changes
conf.pyno longer aborts whenOASIS_INTERSPHINX_MAPis exported empty:environ.get(NAME, "{}")only substitutes its default when the variable is unset, so an empty value reachedjson.loads("")and killed the build with a traceback. Nowenviron.get(NAME) or "{}", verified with the variable unset, set-but-empty and mapped.style:split the one-line import inconf.pythatautopep8flagged as E401, so the cross-component block is lint-clean and identical to the other components'.Build is 0 warnings standalone and in the aggregated build, with both notebooks executing and publishing their
.ipynb.Add executable PiWind tutorials — a high-level end-to-end analysis and a step-by-step kernel pipeline walkthrough — published as documentation.