76 lines
4.4 KiB
Markdown
76 lines
4.4 KiB
Markdown
|
# _STANDARDS
|
||
|
|
|
||
|
|
Standards, engine and templates for documents produced in this project.
|
||
|
|
|
||
|
|
| File | What it is |
|
||
|
|
|---|---|
|
||
|
|
| `MPM_Document_Standard.md` | **The rules**: types, numbering, revisions, files, layout, writing. Read this first. |
|
||
|
|
| `glossary_zh.md` | Master English → Simplified Chinese terms for Chinese editions (standard §12). |
|
||
|
|
| `registry.md` | Customer codes and every issued document number (a snapshot: claim numbers in the shared master registry, standard §11). |
|
||
|
|
| `mpmdoc/` | The build engine: stylesheet, header/footer, components, PDF renderer. Fonts and logos come from `../_ASSETS/mpm/`. |
|
||
|
|
| `templates/<TYPE>/` | Starter `build.py` + `figs.py` per MPM document type (TN, INS, SOP, BOM, SVY, TAP, DWG, TSB, PRO, SOW, WO), with a `_preview_*.pdf`. TN and DWG also have `build_zh.py` (Chinese edition). |
|
||
|
|
|
||
|
|
## Start a new document
|
||
|
|
|
||
|
|
1. Register the number in `registry.md` (and the customer code in `mpmdoc/brand.py` if new).
|
||
|
|
2. Copy `templates/<TYPE>/` to `<PROJECT FOLDER>/source/`.
|
||
|
|
3. Fill in `build.py` (content) and `figs.py` (source numbers + figures).
|
||
|
|
4. Run `python3 build.py` from `source/`. The PDF lands in the project folder.
|
||
|
|
|
||
|
|
`build.py` finds `_STANDARDS` by walking up from its own folder, so a project folder
|
||
|
|
can sit anywhere under DOCUMENTATION PROJECT.
|
||
|
|
|
||
|
|
## Requirements
|
||
|
|
|
||
|
|
Python 3.10+, `pip install playwright && playwright install chromium`.
|
||
|
|
Run `setup.sh` in the kit root once to install them, plus poppler (see `START_HERE.md`).
|
||
|
|
|
||
|
|
## Engine cheat sheet
|
||
|
|
|
||
|
|
```python
|
||
|
|
doc = Doc(number, rev, date, title, lede, meta=[(k, v), (k, v)], slug, history,
|
||
|
|
customer=None, subject="", kicker=None, footer=None, classification=None)
|
||
|
|
doc.add(
|
||
|
|
doc.kpis([(label, value, sub, tone)]), # tone: None|key|strong|ok|bad
|
||
|
|
doc.result([...]) / doc.before_you_start([...]),
|
||
|
|
doc.section("Title", new_page=False),
|
||
|
|
doc.table(cols, rows, caption=, ref=), # KeyRow([...]), TotalRow([...]), up(), dn(), TBC
|
||
|
|
doc.calc(["# comment", (name, working, result, "PASS")]),
|
||
|
|
doc.figure(svg, caption, ref=), # cite as [[fig:ref]] / [[tab:ref]]
|
||
|
|
doc.note(kicker, body, tone="info|warn|ok|verify"),
|
||
|
|
doc.two(left_html, right_html), doc.bullets([...], check=True),
|
||
|
|
doc.assumptions([...], [...]), doc.signoff(),
|
||
|
|
# procedures (INS / SOP)
|
||
|
|
doc.before_you_start([...]), doc.glance([(label, sub[, mark, other])]),
|
||
|
|
doc.step(n, kicker, title, doc.steps([...]) + doc.note(...), figure, wide=False, side="35%"),
|
||
|
|
doc.shot("img/x.jpg", caption, width), doc.shots(...), ui("Button"), doc.chain([...]),
|
||
|
|
doc.special(kicker, title, body, figure), doc.checklist(title, [...], cols=2),
|
||
|
|
# BOM
|
||
|
|
doc.bom([(section, [(item, spec, qty, uom[, part_no])], subtotal_label)]),
|
||
|
|
# surveys / plans (SVY / TAP)
|
||
|
|
doc.kv([(label, value)]), doc.part(label, title, internal=False), doc.photo("img/x.jpg", caption, ref),
|
||
|
|
doc.photos(...), verify(), doc.transcript(heading, [lines]), doc.approval(name, role, date),
|
||
|
|
# commercial and field (PRO / SOW / WO / TSB); MPM provider block: from mpmdoc.brand import PROVIDER
|
||
|
|
doc.parties([(heading, {name, contact, address, phone, email, web, coordinates})]),
|
||
|
|
doc.priced([(subtotal_label, [(sku, description, qty, extended)])]), # totals computed -> doc.price_total
|
||
|
|
doc.milestones([(milestone, criteria, share, amount)], expect=doc.price_total), doc.money(v),
|
||
|
|
doc.pill(text, "red|gold|grey|ink|green"), doc.fields([label | (label, hint)], cols=2, title=),
|
||
|
|
doc.table(cols, [[""] * n] * 6, cls="fill"), doc.signatures([(role, who)]),
|
||
|
|
)
|
||
|
|
# Chinese edition (TN / DWG): source/build_zh.py next to build.py, same figs.py; build English first
|
||
|
|
# tr = i18n.Translator({doc phrases}); F = {k: tr.svg(f()) for k, f in FIGS.items()}; tr.check()
|
||
|
|
# Doc(..., lang="zh") / Drawing(..., lang="zh") -> {NUMBER}_{slug}_ZH_Rev{X.Y}.pdf
|
||
|
|
# TSB: one build.py loops over editions ("customer", slug "_TSB") and ("internal", slug "_TSB-Internal")
|
||
|
|
|
||
|
|
# drawings (DWG): see templates/DWG/build.py
|
||
|
|
dwg = Drawing(number, rev, date, title, subtitle, project, client, slug, history, location, discipline, drawn, checked, approved)
|
||
|
|
dwg.sheet(views=[dwg.view(svg, n, title, scale, area="1 / 1 / 5 / 3")], schedule=[(tag, name, desc, qty)], notes=[...])
|
||
|
|
dwg.build()
|
||
|
|
doc.build()
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
## Changing the standard
|
||
|
|
|
||
|
|
Edit `MPM_Document_Standard.md` and the engine together, bump the standard's version line,
|
||
|
|
and rebuild one document of each affected type to check.
|