docs: OED reference site (spec-generated fields & coded values) - #286
Conversation
Build PreviewYou can find files attached to the below linked Workflow Run URL (Logs).
|
Build PreviewYou can find files attached to the below linked Workflow Run URL (Logs).
|
Build PreviewYou can find files attached to the below linked Workflow Run URL (Logs).
|
Build PreviewYou can find files attached to the below linked Workflow Run URL (Logs).
|
Build PreviewYou can find files attached to the below linked Workflow Run URL (Logs).
|
Build PreviewYou can find files attached to the below linked Workflow Run URL (Logs).
|
…alues Standalone Furo/MyST site for the Open Exposure Data standard. Field reference (by input file: Loc/Acc/ReinsInfo/ReinsScope) and coded-value lists (perils, occupancy, construction, country, coverage) are generated at build time from oed.json (_ext/gen_oed_reference.py, which regenerates oed.json from the CSVs if absent); plus the migrated spec chapters and an overview/hierarchy explanation. Cross-component links via intersphinx (orchestrator-driven). 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>
`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>
The link check (GenerateDocs#54) found two links to OpenDataStandards/tree/master/OpenExposureData/Docs, which 404s — that path went when the Open Data Standards repo was split. The equivalent lives here: ODS_OpenExposureData/tree/main/Docs (verified 200). Note two further links in import-format.rst still point at OpenDataStandards/tree/master/OpenExposureData. Those resolve today, so the check does not flag them, but they reference the superseded repository rather than this one — worth a follow-up sweep, kept out of here to stay a fix for what is actually broken. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3204275 to
09b18e7
Compare
Build PreviewYou can find files attached to the below linked Workflow Run URL (Logs).
|
SkylordA
left a comment
SkylordA
left a comment
There was a problem hiding this comment.
Docs/Cyber/ReadMe.md and Docs/Liability/ReadMe.md (background, taxonomy, contributor list) aren't migrated anywhere. "Cyber" only survives as peril-code table rows in docs/source/explanation/geography-perils.rst:113-114,140; "Liability" doesn't appear anywhere in the new docs except the caveat at docs/source/reference/fields.md:20-21.
Review feedback (SkylordA, #286), the three items inside this PR's scope. _ensure_oed_json() returned early whenever oed.json existed, so a repeat local build after editing a spec CSV served the tables from the old file. Renamed to _build_oed_json() and always rebuilt: utils/gen-json.py takes under a second, which is cheaper than a staleness check and leaves no stale path at all. Verified by planting a marker file with an empty input_fields and rebuilding — the marker is gone and 574 fields are written. generate_fields() read oed["input_fields"] as a bare subscript, unlike every other lookup in the file, so a partial oed.json failed the Sphinx build with a bare KeyError. It now raises a ValueError naming the file and the fix. The exposure hierarchy folded Docs/2_OED_Overview.rst into explanation/index.md and lost two things on the way: the account-group level (AccGroup, which no page explained) and the table of which hierarchy levels primary and reinsurance terms attach to. Both restored, with Account and Portfolio written out to match, and the note about overcounting at policy level. The other three review findings are answered on the PR: the field-status columns and the AreaCode value list are follow-ups, and the Cyber/Liability background documents are content this restructure does not cover. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Build PreviewYou can find files attached to the below linked Workflow Run URL (Logs).
|
Remaining review feedback on #286 (SkylordA), plus the duplication it exposed. Field statuses. generate_fields() rendered only "Property field status" under a column headed "Status". 1041 of the 1100 fields do not have the same status across the four lines of business, so that column was wrong for 95% of rows with nothing to say which line it described — and OpenExposureData/README.md states outright that a field's status is allowed to differ by exposure class. All four columns of OEDInputFields.csv are now rendered (Property, Cyber, Liability, Marine Cargo) and the caveat pointing readers at oed.json, an untracked generated file, is gone. This table is new in this PR, not migrated: nothing in the old Docs/ or in GenerateDocs ever rendered it. Area codes. generate_values() skipped "area", though the AreaCode field description says "See AreaCode Values sheet for details". Read from AreaCodeValues.csv rather than oed.json, whose "area" entry keeps only the codes and drops the names and resolutions. 1502 codes across 48 countries, so each country is a collapsed dropdown. Cyber and Liability. Neither had any page; "Liability" appeared in the new docs only in the caveat removed above. Added a classes-of-business page covering all four classes — including Marine Cargo, which has no background document and was silently absent — and migrated both ReadMes as pages. The taxonomy image was referenced from a personal patch branch and 404ing, so it is now carried in the repo. The contributor list is verbatim. Duplication. Docs/*.rst were byte-identical to the migrated docs/source pages (five of seven exactly; the other two differed only by the link repoint in 09b18e7), and Docs/2_OED_Overview.rst still carried an unfilled "{enter link to that .rst here}" placeholder. Removed, along with Docs/index.rst which only included them, so there is one copy to edit. Docs/ keeps its governance PDFs and the shared images pool. Two links inside these pages pointed at GitHub for content that is now in the site — the field reference and the coded values — and are internal :doc: links. Build is clean on a fresh -E with 0 warnings; 12 external links, none dead. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Build PreviewYou can find files attached to the below linked Workflow Run URL (Logs).
|
|
On the Cyber/Liability point from the review summary — done in e878af3, and the trail turned out to be worth writing down. Both are now pages: The duplication is gone. Two things were broken and are now fixed as a side effect:
Also repointed two links inside our own pages that sent readers to GitHub for content now in the site — the field reference and the coded values — to internal The contributor list in the cyber page is verbatim. It is from a 2022 working group, so it may want a check by whoever owns that content, but that felt like a separate call from migrating it. |
3 participants
Stands up a Sphinx documentation site for OED, generated from the specification, so the standard is documented where it is defined.
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.What this adds
OasisLMF and ODS_Tools link here for OED definitions rather than restating them, so this landing removes duplication elsewhere as well as adding pages here.
Review-round changes
OpenDataStandards/tree/master/OpenExposureData/Docs, a path that went when the Open Data Standards repository was split. NowODS_OpenExposureData/tree/main/Docs, verified 200.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'.Two links in
import-format.rststill point atOpenDataStandards/tree/master/OpenExposureData. Those resolve today, so nothing flags them, but they reference the superseded repository — left for a follow-up rather than widened into a fix for what is actually broken.Build is 0 warnings standalone and in the aggregated build.
Add a Sphinx documentation site for OED, with fields and coded values generated from the specification.