mpm-documentation-kit/_STANDARDS

_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

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.