docs(authoring): explain generated bindings with reusable examples

Merged
VI
25d ago
+617-20

Summary

Authors lacked an explicit generation/import workflow and composed examples for the section calculations. Document setup, regeneration, generated runtime files and type stubs, Git-ignore policy, and a short Convex comparison. Expand the two-panel walkthrough and add two section-property comparisons:

compare_hot_formed / compare_tapered
  baseline section calculation
  candidate section calculation
  compare_properties(area, centroidal inertia)

Rename the section directories to Python identifiers so their generated modules can be imported. Both original calculation files remain byte-for-byte unchanged. Add composition/document-preservation checks and installed consumers. Fix the installed acceptance snapshot to handle unstaged renames and include new nonignored fixture files.

Closes #60. Related findings remain separate: #56, #57, #58, #59 and #61.

Evidence

  • Before: installed acceptance crashed with ENOENT while hashing a renamed example's old path. After: npm run test:packages passed using fresh npm archives and a Python wheel outside the checkout.
  • npm test: 884 TypeScript tests and 120 Python tests passed. npm run typecheck and npm run lint passed, with existing lint warnings.
  • After Cubic review, strengthened exact symbol-preservation assertions and clarified consistency versus numerical expectations. The focused three-test suite passed. Added default-area and ratio assertions, then reran the external installed consumer successfully.
  • Checked 156 local documentation links and verified that generated bindings remain ignored. Submitted files match the recorded verification hashes.
  • Inspected every page of the comparison PDFs: all 9 hot-formed pages passed visual inspection; the 21-page tapered report has clipped formulas despite passing automated rendering checks. Filed #61 with a minimal installed-package reproduction and documented the limitation. No claim of publication-ready tapered output.

Merge Danger

Door: two-way. No package runtime or canonical calculation formula changes.

Blast Radius: examples. Existing commands using the old hyphenated section-directory paths need the new underscore paths. Generated bindings must be regenerated. Known tapered geometry failures in #59 and PDF clipping in #61 remain open.