How the documentation is organised

This page is for people writing OasisLMF documentation. It records how the docs are structured, built and published, and the rules to follow when adding a page, so that decisions already taken don’t have to be rediscovered.

Ownership: each repository documents its own code

Every code repository owns the documentation for its own code, in-repo, next to that code. One thin orchestrator aggregates them into the published site.

OasisLMF/docs/          MDK, pytools, CLI, the financial module, modelling
                        methodology, correlation, disaggregation, the kernel
                        component reference
OasisPlatform/docs/     platform, deployment, distributed execution, REST API
ODS_Tools/docs/         OED loading and validation, the settings schemas
ODS_OpenExposureData/   the OED standard          } spec-generated reference
ODS_OpenResultsData/    the ORD standard          }
OasisModels/docs/       worked, end-to-end model examples

GenerateDocs            orchestrator: pins each repository to a ref, builds each
                        one, resolves cross-references between them, and publishes
                        the combined site to oasislmf.github.io

Why this shape:

• It kills drift. Conceptual pages sit beside the code, so a behaviour change and its documentation travel in the same pull request and the same review.

• One source of truth per topic. The orchestrator holds no prose; it only assembles.

• Versioned. The orchestrator pins refs, so each published build maps to real releases and the site can offer a version selector.

• Lower barrier. Documentation lives where contributors already are.

The trade-off, accepted deliberately: contributors must know which repository owns a page. If you are unsure, the owner is whichever repository contains the code the page describes.

ktools is being decommissioned and does not own documentation. Its component docs were drained into this repository and rewritten against the oasislmf/pytools implementations; ktools is a content source, not a documentation home.

Content model: Diátaxis

Four modes, and never two on the same page:

Mode	Purpose	Examples here	Maintained as
Tutorials	Learning by doing	“Run your first analysis”	Hand-written, ideally executable
How-to	Task recipes	“Generate Oasis files”, “Configure distributed execution”	Hand-written
Reference	Dry facts	Python API, CLI options, settings schemas, stream formats	Generated where possible (autoapi, argparse, schema)
Explanation	Understanding	Financial module, sampling, correlation, disaggregation	Hand-written, co-located with the algorithms

The reference layer is largely automatable, which frees effort for the explanation layer — where both the value and the drift risk concentrate.

Each audience gets a landing page: analysts and end users, model developers, platform operators, and contributors.

Tooling

In place:

Concern	Choice	Why
Engine	Sphinx	Already in use; the right tool
Theme	Furo	Branded (Oasis colours, Raleway)
Authoring	MyST Markdown alongside reStructuredText	Lower barrier; both compile, so migration is incremental
API reference	sphinx-autoapi, scoped per subsystem	AST-based, so no heavy imports; avoids a whole-package dump
Landing pages	sphinx-design cards and grids	Per-audience entry points
Executable docs	myst-nb	Tutorials run at build time, so they cannot silently rot
Copy buttons	sphinx-copybutton	Contributor experience
Cross-repo links	sphinx.ext.intersphinx, driven by the orchestrator	See the note below

Agreed but not yet implemented — worth knowing before you assume a safety net exists:

• linkcheck in CI. Dead external links build perfectly cleanly. There is no job running it today.

• Docstring-coverage gate (e.g. interrogate), to keep the generated reference honest as the autoapi scope widens.

• Mermaid diagrams. Diagrams-as-text would diff cleanly and avoid stale binary assets, but the extension is not configured.

• A render check. See the first gotcha below: “builds clean” is not “renders clean”.

Authoring rules and traps

These are concrete, recurring problems found while building these docs. Where a rule exists it is because something broke.

1. Do not use .. contents::. Furo renders its own “On this page” sidebar, and a docutils .. contents:: directive becomes a red error box visible to readers.

2. “Builds clean” is not “renders clean”. That .. contents:: failure produced exit 0 and no Sphinx warning — the theme injects the error into the HTML, not the build log. When you change something structural, look at the built page.

3. Cross-repository references need the orchestrator. An {external+...} role only resolves when the orchestrator supplies the inventories, and an unresolved one does not degrade to plain text — Sphinx drops the link text and silently mangles the sentence. For prose a reader must follow, either route the target through a per-build-mode substitution in conf.py or write an ordinary link; the orchestrator rewrites in-site URLs to page-relative either way.

4. Google-style docstrings: mind the colon. In a Returns: block napoleon treats everything before the first colon on the first line as the return type. A named return (intervals (np.ndarray): …) therefore turns the name into a type and emits a cross-reference; write the description first instead.

5. Docstrings are RST. Bare indented code or algorithm sketches need a :: literal block; lists need a blank line before them; *args-style text and identifiers ending in an underscore (numpy.str_) must be inline literals or they are read as markup.

6. Never paste code. Use literalinclude or an executable notebook cell, so samples come from sources that are actually run.

7. Keep the build at zero warnings. Every component currently builds clean, standalone and aggregated. That is only useful as a gate if it stays true.