Office Docs Builder

Office files are judged on opening: does it look intentional, do the numbers compute, do the slides fit? Build them with code so they are reproducible, then verify by reading the file back.

Step 0 — Choose format and gather content

• docx for narrative documents: reports, proposals, memos, SOPs, letters.
• pptx for presentations: one message per slide, spoken alongside.
• xlsx for anything with numbers someone will edit or recalculate.

Collect the content first: outline, data (CSV/JSON), brand basics (font, two colours, logo path), audience and length. If a template file exists, use it (Document('template.docx'), Presentation('template.pptx')) and its styles/layouts instead of inventing new ones.

Step 1 — Plan the structure before coding

Write the outline as a data structure (list of sections/slides/sheets with their content) and generate from it. This keeps content separate from styling and makes revisions cheap.

Word (.docx) rules

• Use built-in styles (Title, Heading 1–3, Normal, List Bullet, Caption); modify the style once rather than formatting runs individually.
• Set page margins, default font and size on the document; add page numbers in the footer and a table of contents field for documents over five pages (TOC field updates on open; tell the user).
• Tables: header row bold with shading, repeat header on page break, consistent column widths, numbers right-aligned.
• Images: add_picture with width in inches; add captions.
• Headers/footers with title and date; cover page for formal reports. Use space_after, not empty paragraphs, for spacing.

PowerPoint (.pptx) rules

• Pick one layout family from the template and stick to 16:9.
• Every slide: an action title (a sentence stating the takeaway, not "Results"), at most five bullets or one chart or one visual, speaker notes with the narrative.
• Use native charts (chart_data in python-pptx / addChart in pptxgenjs) so numbers remain editable; never paste chart screenshots.
• Text must fit: cap titles at ~60 characters and body at ~90 words; set autofit off and check overflow by reading shape text lengths.
• Consistent typography: two sizes for body (18–24 pt) and titles (28–36 pt); brand colours from the template theme.
• Include section divider slides for decks over 15 slides and a closing slide with next steps.

Excel (.xlsx) rules

• One sheet for inputs, one or more for calculations, one for outputs/summary; raw data on its own sheet as a proper table.
• Write formulas, not computed values (ws['D2'] = '=B2*C2'), so the model stays live. Use absolute references for assumptions ($B$1).
• Freeze header rows, apply number formats ('#,##0.00', '0.0%', dates), set column widths, bold headers with fill.
• Named ranges for key assumptions; data validation lists for categorical inputs.
• Add native charts with openpyxl/exceljs referencing ranges.
• No merged cells inside data regions; no formulas referencing empty ranges.

Step 2 — Generate

Write a single script (build_<name>.py) that reads the content structure and produces the file into an out/ folder. Keep styling in one place (constants or a small theme dict). Re-running must overwrite cleanly.

Step 3 — Verify by reading the file back

• Reopen with the same library and assert: expected section/slide/sheet count, no empty slides, every table has a header, no text box exceeds its capacity, formulas present where expected.
• Recalculate formulas: soffice --headless --convert-to xlsx --outdir tmp out/model.xlsx then read values with openpyxl data_only=True; check for #REF!, #DIV/0!, #NAME?.
• Render to PDF for a visual check when possible: soffice --headless --convert-to pdf out/deck.pptx and inspect page count and any overflow.
• Open metadata: set core_properties.title, author, remove template placeholder text.

Output format

Report: the generated file path(s), the build script path, a summary of structure (sections/slides/sheets), verification results (counts, formula recalculation status, rendered-page count), and any content that was assumed or left as a placeholder.

Checklist

• Built from a script, re-runnable.
• Uses template/theme styles; no ad-hoc fonts or colours.
• Charts and formulas are native, not images or pasted numbers.
• Verified by re-reading and, where possible, rendering.
• No placeholder text ("Lorem", "Click to add title") remains.
• File named clearly with a version or date.

Pitfalls

• python-pptx cannot compute text overflow; estimate by character count and keep margins generous.
• openpyxl does not evaluate formulas; do not read data_only=True from a file you just wrote and expect values.
• Very large xlsx writes: use write_only=True mode and avoid per-cell styling.
• Editing an existing docx with tracked changes or complex numbering can corrupt structure; prefer generating fresh from a template.
• Fonts not installed on the reader's machine will substitute; stick to Calibri, Arial or Aptos.