Skip to content

index.md

Latest commit

 

History

History
52 lines (42 loc) · 2.89 KB

index.md

File metadata and controls

52 lines (42 loc) · 2.89 KB

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.

!!! tip "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.

!!! note "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/.