Models and fields page with a generated field type table #708

Parent

#698

What to build

The field type table is wrong in about 9 cells (str is varchar, not TEXT; datetime is timestamptz on Postgres; enums are varchar(n) on SQLite; UUID width; int is never BIGINT without db_type) and the page's own DDL contradicts it.

The table is generated from the storage resolution the emitters share (_core._resolve_storage_type, I-1 item 3) for every supported annotation on both dialects, written to docs/includes/field-types.md and embedded by the page; a test regenerates it and fails on any difference. The page gets one running example, DDL shown beside each schema feature (PassReport statements or the create pass rendering), and one explanation of what happens when a Model base class declares fields (the base gets a table of its own; verify before writing), which the timestamps and soft-delete how-tos will link to.

Pages: guide/models-and-fields.md

Acceptance criteria

• Every fact on the page matches the code at the time of the PR; each High finding in the audit rows below is fixed, and each Medium/Low finding is fixed or answered in the PR body with the reason it was left.
• Each page is one kind (tutorial, how-to, reference or explanation) and opens with one sentence saying what it covers, then an example on the first screen (writing-for-humans rules 1–2).
• Each page uses one running example, declared once near the top and reused; each section shows only what changed (rule 3).
• Every code block has a lead-in sentence ending in a colon and a result sentence after it, and shows its result: printed output, or the asserted value inside the embedded snippet range (rules 7–8). Snippet end: markers sit below the assert or print that holds the result.
• Every copyable block either shows the async with engines.session(): wrapper or sits under a sentence that says it runs inside one and links to Connections › Sessions; the page's first block shows the wrapper.
• Every inline Python block that does real work runs under the harness ({test=run prelude=<name>}) or moves into an example script; a block left compile-only says why in its fence marker.
• Every lambda passed to a query method names its parameter after the model in lowercase singular (AGENTS.md I-8); python -m tests._docs_checks reports no violation for the owned files.
• Every error check in an owned example fails when the expected error is not raised (try/except/else: raise AssertionError, or the harness helper).
• Field-declaring examples show both declaration styles as tabs, each backed by a runnable script (AGENTS.md I-7), and the twins use the one Annotated idiom recorded in the docs conventions.
• Headings are short sentence-case noun phrases naming the feature (rule 5); how-to titles name the goal (rule 24); no minimising words (rule 17); admonitions follow rule 20.
• No ADR numbers, issue numbers, codenames, dated or release-bound notes, or contributor-only references in page text; version markers are self-contained blocks at the end of a section.
• Reference material that has a home in Reference is linked, not repeated; each topic ends with a pointer to its reference entry (rule 4).

Files owned

• Create: docs/includes/field-types.md, tests/test_docs_field_type_table.py, docs/examples/models_and_fields.py, docs/examples/models_and_fields_annotated.py
• Modify: docs/pages/guide/models-and-fields.md, docs/examples/table_checks.py, docs/examples/table_checks_annotated.py

Interfaces

• Consumes: I-7, I-14, docs conventions (AGENTS.md ticket (AGENTS.md: rewrite I-8 for the lambda-only query API, add a docstring invariant, record the docs conventions #703))
• Consumes: harness (harness ticket (Docs harness: run inline blocks with a prelude, run docstring examples, and check lambda names and error checks #704))
• Consumes: quickstart example as rewritten by the get-started ticket (Get started pages: home page and README, Why Ferro, installation and quickstart #705)
• Produces: Section anchor #fields-on-a-model-base-class on the models-and-fields page: the one explanation of base-class fields, linked by the short how-tos ticket (How-tos: testing, pagination, timestamps and soft deletes #716).
• Produces: python -m tests.test_docs_field_type_table regenerates docs/includes/field-types.md.

Test scenarios

• Happy path: the strict site build succeeds and every snippet range on the owned pages renders without leading indentation.
• Happy path: every owned example script runs to completion under tests/test_docs_examples.py, and every inline block marked {test=run ...} runs.
• Error path: deleting the raise an owned example's error check expects makes that example's test fail.
• Edge case: python -m tests._docs_checks over the owned files exits 0; renaming one lambda parameter to t makes it exit 1 naming the file and line.
• Integration: the type table test fails when one cell of docs/includes/field-types.md is edited by hand.

Verify

uv run --no-sync zensical build --clean --strict
uv run --no-sync pytest tests/test_docs_examples.py -q --no-cov -p no:cacheprovider -n 8
uv run --no-sync pytest tests/test_docs_field_type_table.py -q --no-cov -p no:cacheprovider
uv run --no-sync python -m tests._docs_checks docs/pages/guide/models-and-fields.md docs/examples/models_and_fields.py docs/examples/table_checks.py

Blocked by

• Docs site config: Zensical features, Markdown extensions, API reference options and a strict build #701, AGENTS.md: rewrite I-8 for the lambda-only query API, add a docstring invariant, record the docs conventions #703, Docs harness: run inline blocks with a prelude, run docstring examples, and check lambda names and error checks #704, Get started pages: home page and README, Why Ferro, installation and quickstart #705

Audit findings