docs: Diátaxis foundation, OpenAPI/redoc, validated Platform-API how-to

[sstruzik]

Gives OasisPlatform its own Diátaxis documentation set, co-located with the code, replacing the platform prose that lived in GenerateDocs.

Part of the cross-repo Oasis documentation restructure (Option B): each repository owns the docs for what it owns, and GenerateDocs aggregates them into the published site.

What this adds

• A Furo + MyST Diátaxis project in docs/source/, with the platform pages migrated out of GenerateDocs: explanation (overview, architecture, Oasis UI), how-to (first steps, deployment, container configuration, distributed execution and configuration), reference (REST API).
• The OpenAPI schemas persisted in-repo (_static/schemas/). They were CI-only with 3-day retention, so the API reference could not be rebuilt from history. Now they are versioned with the code.
• The REST API rendered with Redoc, vendored in _static/redoc/ (redoc.standalone.js v2.1.5). This replaced sphinxcontrib-redoc, which is abandoned, capped Sphinx below 8 and needed pkg_resources/setuptools<81; dropping it took the whole toolchain to Sphinx 9.1. A build hook inlines each spec into a themed page, so it renders offline and under file://.
• A Platform-API how-to (run-analysis-via-api) — the full APIClient workflow: connect, register a model, upload OED, create an analysis, generate inputs, run, download ORD. Validated end-to-end against a live v2 platform, not written from the source: build images → register → upload → generate → run → download → EP-curve plot.
• The old flat alabaster docs removed, including committed build output (53 files, ~18k lines).
• Shared Oasis branding and cross-component intersphinx links, matching the other five component sites.

Review-round changes

Three broken in-site links, found by the new link check (GenerateDocs#55) and both from RST auto-linking text that was never meant to be a link:

• first-steps.rst had `httpie <www.httpie.org>`_ with no scheme, so Sphinx resolved it as a relative path. Doubly broken: www.httpie.org no longer resolves at all, and httpie.org now redirects to httpie.io.
• container_configuration.rst had https://<site-domain>/api/ as a placeholder; the parser auto-linked it only as far as the <, giving href="https:/" twice and rendering the text as https:/ /<site-domain>/api/. So the table read wrongly as well as linking nowhere. Both are now inline literals.

Eleven links off a deleted branch. reference/API.rst pointed at OasisPlatform/blob/platform-2.0/kubernetes/…, and that branch is gone. All three target files exist on main (verified 200). One of the eleven was wrapped across two source lines, so it needed a second pass — worth knowing for anyone doing a similar sweep.

The SaaS providers list migrated in. This page already ended its SaaS discussion with "More information about SaaS and the companies can be found in the SaaS providers section" — a promise to a section that never existed here. That content was in GenerateDocs and was being dropped, with the landing-page link repointed to platform/index.html, which names none of the providers. The six named companies now live in how-to/deployment.rst as a real section, and the dangling sentence references it. All six links verified 200.

conf.py hardened — it no longer aborts when OASIS_INTERSPHINX_MAP is exported empty (environ.get(NAME, "{}") only defaults when the variable is unset, so an empty value reached json.loads("")), plus the E401 import split so the cross-component block is lint-clean and identical across components.

Build is 0 warnings standalone and in the aggregated build.

Two things worth a look

• https://www.rms.com/ in the new SaaS list now redirects to moodys.com (RMS was acquired), so the label "RMS IRP" is behind the branding. Kept verbatim, since that commit moves content rather than rewriting it.
• Scan Repo fails on this branch. It was already failing before these commits, and the build_images failures seen mid-review were a GitHub rate limit while building the ods-tools wheel (403 rate limit exceeded fetching OED spec releases) — not caused by anything here.

Add the OasisPlatform documentation set: Diátaxis structure, persisted OpenAPI schemas rendered with a vendored Redoc, and a live-validated Platform-API how-to.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@a982331). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1418   +/-   ##
=======================================
  Coverage        ?   74.10%           
=======================================
  Files           ?      214           
  Lines           ?    14140           
  Branches        ?        0           
=======================================
  Hits            ?    10478           
  Misses          ?     3662           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sambles]

Looks good, New build structure for the documentation works well.

The docs themselves could do with an overhaul and trimming down in places. But i feels its better to do that in another PR after this is merged