smillmorel
d5ac3fca7e
Collection of engineering calculation projects (Python + Typst), each with input, calc script, tests, results, and generated PDF where available.
73 lines
4.1 KiB
Markdown
73 lines
4.1 KiB
Markdown
# Task 004 — Documentation refresh: README.md + codemap.md
|
||
|
||
## Goal
|
||
|
||
Index the new concentric footing calculation in the shared documentation so the next engineer can discover and compile it without reading source.
|
||
|
||
## Background
|
||
|
||
Depends on footing.typ existing. This task is typst-builder-local (documentation only). Conventions per PROJECT_STATE.md: compile with --root ., hybrid pattern, no modification to existing calcs.
|
||
|
||
## Files to Modify
|
||
|
||
- `README.md` — the shared worksheets readme that lists calcs. At present this file lives at `calcs/wood-joist/README.md` which serves as the de-facto worksheets README (it documents all sheets). Also check for `README.md` at `worksheets/` root if it exists. Update whichever exists; if both exist update both with same concentric-footing entry. If only `calcs/wood-joist/README.md` exists, that is the file to edit.
|
||
- `codemap.md` — update at `worksheets/codemap.md` (and copy to `calcs/concentric-footing/codemap.md` if the per-calc map is expected). Regenerate the whole map rather than editing in place per codemap rules.
|
||
|
||
## Implementation
|
||
|
||
### 1. README.md
|
||
|
||
Add a new section `## Concentric footing` after the Wood joist section, following the same style. Include:
|
||
|
||
- One-sentence description: "Square concentric spread footing under axial load per ACI 318-19 — soil bearing, one-way/two-way shear, flexure, minimum steel, concrete bearing."
|
||
- Compile commands:
|
||
```
|
||
python calcs/concentric-footing/calc.py
|
||
typst compile --root . calcs/concentric-footing/footing.typ calcs/concentric-footing/generated/footing.pdf
|
||
python -m pytest calcs/concentric-footing/test_concentric_footing.py
|
||
```
|
||
- Stdout variant:
|
||
```
|
||
python calcs/concentric-footing/calc.py --input calcs/concentric-footing/input.yaml --stdout
|
||
```
|
||
and `--output` note.
|
||
- Note on load derivation: `input.yaml` supplies checked `Ps`/`Pu` (Pint quantities) and footing geometry/materials; `footing.typ` derives `Ps`/`Pu` inline from `DLr=10psf, LLr=20psf, Br=18.9ft, Lr=27.5ft, column 14in×14ft @145pcf` and reconciles via `<concentric-footing-loads>` query; bearing plate width `bp=6in` governs `A1`.
|
||
- Update the top index code block to add line:
|
||
```
|
||
calcs/concentric-footing/ YAML quantities → Pint → JSON → Typst (ACI 318-19)
|
||
```
|
||
- Ensure the 5-step New calculation list remains unchanged.
|
||
|
||
If editing `worksheets/README.md` vs `calcs/wood-joist/README.md`, keep both in sync; prefer editing the file that actually exists and then copying the change to the other if both are present.
|
||
|
||
### 2. codemap.md
|
||
|
||
Regenerate at `worksheets/codemap.md` (and also write copy to `calcs/concentric-footing/codemap.md` if needed for per-calc root check):
|
||
|
||
- Re-run classification for all 37+ files including the new `calcs/concentric-footing/calc.py [logic]`, `input.yaml [config]`, `footing.typ [logic]`, `test_concentric_footing.py [test]`, `results.json [state]`, `generated/footing.pdf [doc]`, `CONCENTRIC-FOOTING.pdf [doc]`.
|
||
- The layout section must now show `calcs/concentric-footing/` expanded with its 5 planned + 3 reference entries.
|
||
- Hot Spots must now include `calcs/concentric-footing/calc.py` as single source of truth.
|
||
- Conventions section must mention the new sheet's hybrid Pint pattern and Typst load derivation.
|
||
- Timestamp updated to now, Files indexed incremented.
|
||
|
||
Do not write summaries from imagination; if uncertain read first 20 lines.
|
||
|
||
## Acceptance Criteria
|
||
|
||
1. `README.md` contains a new `## Concentric footing` section with compile, stdout, and load-derivation notes; top index code block lists the new calc.
|
||
2. `codemap.md` at `worksheets/codemap.md` exists, is well-formed markdown with header, layout, hot spots, conventions; it lists `calcs/concentric-footing/` and its files.
|
||
3. `python -m pytest calcs/concentric-footing/test_concentric_footing.py -v` still passes (12 tests).
|
||
4. No existing calc logic files modified; only docs/maps changed.
|
||
|
||
## Tests
|
||
|
||
```
|
||
python -m pytest calcs/concentric-footing/test_concentric_footing.py -v
|
||
typst compile --root . calcs/concentric-footing/footing.typ calcs/concentric-footing/generated/footing.pdf
|
||
```
|
||
|
||
Both succeed; PDF still compiles.
|
||
|
||
## Dependencies
|
||
|
||
Task 003 must be DONE.
|