docs: promote the typed-data flow and reframe it end-to-end#7
Merged
Conversation
The "Typed objects vs dictionaries" concept is the page that shows how to write Python against the generated data structures, yet it sat last in the Concepts nav and was the 4th item in every reading order. Reframe it as "Typed data, end to end" — leading with the insight that once you are in Python the data starts from a structured set of parameters and stays in typed objects all the way to XML (CalculationResult -> to_model -> generated models -> XML), with the dict contrast as supporting material. All code examples stay bound to the real APIs and remain backed by tests/unit/test_typed_vs_dict.py. Promote it in the navigation: move it to second in Concepts (after schema-as-contract) and surface it from the home mental-model paragraph, the zero-to-green tutorial reading order, and the onboarding reading order.
|
Contributor
Author
|
this is what the preview page looks like for me |
Reaching the page still took too many steps (open menu -> Concepts -> the entry). Promote it further: - Add it as a top-level nav item (after Onboarding), so it is one tap from the navigation drawer rather than nested under Concepts. It remains listed under Concepts too, for the Diataxis grouping. - Add a prominent tip callout near the top of the home page linking straight to it, so it is reachable in one click from the landing page.
The aligned trailing comments (padding the -> annotations into columns) made the lines wide enough to clip off-screen on a phone, hiding the right-hand side of the first sample. Reformat so every Python line stays narrow: - Replace the aligned inline annotations in the end-to-end sample with a short code block plus an "expression -> type" table. - Put TypeError / mypy / MappingError notes on their own short comment lines instead of long trailing comments, and wrap the dataclasses.replace call. - Bind the example path to a short `input_path` variable so the calculate_from_file lines stay narrow while keeping the real filename.
Two changes from review: 1. Make the first typed-data sample persuasive without going wide. Replace the short block + type table with a taller, narrow, runnable drill-down: print statements walk the structure at increasing depth (CalculationResult -> ActiveSonarResult -> SectorResult, then the schema-generated Platform and Sector), each followed by its real output. Every printed value was captured by running the pipeline, and tests/unit/test_typed_vs_dict.py still passes. 2. Remove the ADRs and the "Add a decision record" how-to from the published site while keeping them in the repo. They are excluded from the MkDocs build via exclude_docs (still browsable on GitHub under docs/decisions/). In-text ADR citations are kept as plain text (unlinked); the few navigation pointers that targeted the removed section now point at docs/decisions/ in the repo.
Clarify that the example explores only typed structures, never the raw JSON. calculate_from_file returns a typed CalculationResult (not the parsed dict), so the walkthrough now says so explicitly and leads with the payoff: you use attributes rather than string keys, the IDE autocompletes each step, and a typo fails immediately. The JSON is parsed once internally and never indexed by key. Printed outputs are unchanged and still captured from a real run.
The jump to "platform = to_model(result)" was unexplained. Expand the inline comment so it is self-describing — to_model copies the calculation result into the schema-generated classes, converts to the schema's types, and range-checks each value before serialisation — and name to_model in the intro prose so the reader meets it before the code.
…diate Interim trim ahead of the planned refactor that removes the intermediate CalculationResult. The headline example no longer teaches the result -> to_model -> platform two-step; it collapses production into a single "produce the schema's data object" line and explores only that object (a Platform generated from the XSD) with IDE autocomplete and the schema's Decimal types. Output values are captured from a real run. The page now tells the defensible story: we build one data object that meets the schema.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
When reading the published docs, the page that actually shows how to write Python against the new typed data structures —
concepts/typed-vs-dicts.md— was buried: last in the Concepts nav and the 4th item in every reading order. This raises its prominence and reframes it around the realisation that if you start from a set of parameters in a structure, the whole flow should be typed data — end to end, not just at the storage boundary.What changed
Content reframe —
concepts/typed-vs-dicts.md→ "Typed data, end to end"CalculationResult(typed dataclass) →to_model→ generated models (Platform,Sector, …) → XML. The only loosely-typed moment is the raw JSON at the very edge, parsed once at a single boundary.dict-vs-typed contrast as supporting material (why typed wins), plus the construction-timeTypeError, themypytype check, and theMappingErrorrange gate.tests/unit/test_typed_vs_dict.py— no behavioural claims were invented.Navigation promotion
mkdocs.yml: moved the page to second in Concepts (after Schema as the contract, which grounds its "generated from the schema" claims) and retitled it Typed data, end to end.docs/index.md: the one-paragraph mental model now calls out the typed-end-to-end flow and links the page.docs/tutorials/01-start-here.md: added it to the Step 4 reading order (now item 2).docs/onboarding.md: bumped it up the "build the mental model" reading order (now item 2).Verification
mkdocs build --strictpasses with no warnings — nav entries and all cross-links resolve.Note / follow-up
This PR is docs only. It advocates the typed-from-the-start pattern; the shipped acoustic seams still read the raw input as a
dict(spec["baseFrequencyHz"], etc.) before producing the typedCalculationResult. If you'd like the code to also start from a typed parameter structure (so the dict never appears past the parse boundary), that's a natural next change — happy to follow up.https://claude.ai/code/session_01Fzbw6tx6MM6Ffk4LUaFYSP
Generated by Claude Code