docs: OED load/validate notebook + settings-schema reference

[sstruzik]

Stands up documentation for ODS_Tools: an executable OED load-and-validate tutorial, and a settings-schema reference generated from the schemas this repository owns.

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

• tutorials/load-validate-oed — a myst-nb notebook that executes at build time: loads an OED location file with OedExposure, runs DEFAULT_VALIDATION_CONFIG in return mode, catches a missing LocPeril, fixes it and re-validates. Because it runs, its output cannot drift from the library.
• A settings-schema reference generated from ods_tools/data/*_settings_schema.json (_ext/gen_settings_reference.py), covering model, analysis and combine settings. The schemas stay the single source of truth — edit the JSON, not Markdown.
• Diátaxis structure, shared Oasis branding, and cross-component intersphinx links, matching the other five component sites.

Review-round changes (@Ha-Ree)

The generated reference was dropping most of the constraints in the schemas. _constraints() understood only enum/default/minimum/maximum, so 95 keyword occurrences were silently omitted (minLength ×69, uniqueItems ×16, minItems ×6, minProperties, maxLength, pattern, multipleOf). Worse, 29 array properties keep their constraints on items{}, which was never inspected — including 7 items.enum allowed-value lists, so group_event_set_fields, group_format_priority, valid_output_perspectives/metrics and the event_set valid_* fields all rendered an empty Constraints cell. A generated reference that silently omits which values are legal defeats the point of generating it. Arrays are now summarised in two parts — keywords on the array describe the list, item keywords are reported as "each item …" — and arrays of objects are left alone, since they already expand into their own subsection. Coverage: 89 → 212 of 335 properties now document a constraint.

The ord cross-reference took two attempts, and the first was wrong. The page's one {external+ord:doc} reference warned on every standalone build, because the ORD inventory only exists when the orchestrator supplies OASIS_INTERSPHINX_MAP. I first suppressed the warning — which hid a visible defect: an unresolved {external+...} role does not degrade to plain text, Sphinx drops the link text, so the sentence rendered as "…a table in the (e.g. …)". It is now routed through a per-build-mode substitution in conf.py: the role under the orchestrator (verified, and it warns if ORD renames the page — confirmed by simulating exactly that), a plain link standalone. Verified all three ways: standalone 0 warnings; ord mapped resolves; mapped without ord still warns.

conf.py tidied — the guards this file makes unreachable are gone (os was already imported, sphinx.ext.intersphinx is provably absent from the extensions literal, intersphinx_mapping/html_theme_options/html_static_path/html_css_files are provably undefined, html_theme is set 20 lines above). One correction to the premise: json was not imported at the top, so it moved up rather than being deleted. Also hardened against OASIS_INTERSPHINX_MAP being exported empty, which reached json.loads("") and aborted the build.

Duplicate sample data removed — the tutorial's OED file was byte-identical to validation/SourceLocOEDPiWind10Currency.csv; the notebook now walks up from the build directory to the repository's own copy, and still executes with identical output (10 locations, 25 columns, 1 finding → 0 after the fix).

Build is 0 warnings standalone and in the aggregated build.

One open question for the reviewer

Dropping the role in favour of a substitution means Sphinx no longer verifies the ORD target on a standalone build (the orchestrated build still does). GenerateDocs#55 adds a weekly link check over the assembled site, which covers this and every other link — worth confirming that is where you would want that check to live.

Add ODS_Tools documentation: an executable OED load/validate tutorial and a settings-schema reference generated from the bundled schemas.

[codecov]

Codecov Report

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

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #289   +/-   ##
=======================================
  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.

[Ha-Ree]

Can be expanded to include < and > so events_<id>.bin etc load (currently says events_.bin