Acoustic Reference Book — Phase 1 Pipeline¶
A schema-driven pipeline that turns acoustic calculation output into validated XML Acoustic Dataset, plus the documentation that lets you learn it and defend the decisions behind it.
Writing Python here? Start with the data
The pipeline keeps everything in typed objects from a structured parameter set all the way to XML. The one page to read first is Typed data, end to end — how to write code against the generated structures.
This site is organised so it can grow with your understanding. It follows the Diátaxis model — four kinds of documentation, each answering a different question — plus a set of Architecture Decision Records (ADRs) that record why each choice was made (and what was rejected).
Where to go¶
| If you want to… | Go to | It answers |
|---|---|---|
| Get the environment running and see it work | Tutorials | "Show me, step by step." |
| Do a specific task | How-to guides | "How do I X?" |
| Understand why it works this way | Concepts | "Help me understand." |
| Look up a command or the schema shape | Reference | "What exactly is X?" |
| Decode a term | Glossary | "What does that word mean?" |
The one-paragraph mental model¶
The schema (XSD) is the contract. Everything derives from it: typed data classes
(generated by xsdata), the validation gate (xmlschema), the HTML reference docs and
Mermaid ERD, and the language bindings shipped to consumers. We never hand-write the
things the schema can generate — configure, don't create. When you write Python here you
start from a structured set of parameters and the data stays in typed objects end to end,
from that structure through to the XML — see
Typed data, end to end. Output is trusted only after
passing two gates: a mechanical structural gate (schema-valid + round-trips) and a
human semantic gate (is the science right?). See
Schema as the contract and
The two verification gates.
How this set grows¶
- Every significant choice is recorded as a numbered ADR, kept in the
repository under
docs/decisions/(not published to this site). - New understanding lands as a concept page; new recipes as how-to guides.
- The schema reference and ERD are generated from the enriched XSD — see the generated schema reference — so the docs can never drift from the contract.
Status
The environment (Codespace, tests, docs site) and the full schema-driven pipeline are real
and green. See the feature spec and plan under specs/001-codespace-xml-scaffold/.