apollo-sheets
sheet.py turns Markdown into a PDF through headless Chrome. Start from template.md. The reference sheet
examples/apollo/apollo.md shows every block beside its source; README.md summarizes the syntax.
Workflow
Write or take the report as Markdown. Add front matter (title, section, tab, system, doc, mission, date). Quote any value that contains a colon.
Use the blocks where they carry information:
:::diagramfor a signal or data path, or a graph withdiamonddecisions,bend=Rback-edges andloopself-edges;:::timelinefor a sequence,:::plotfor CSV data or exactfncurves (panelfor a second panel on the same x),:::tablefor anything tabular,:::checklistfor a procedure,:::caution/:::warningfor hazards,:::sequencefor hand-offs or protocols,:::signalsfor timing,:::budgetfor used-against-capacity,:::stackfor layers or a memory map,:::bitsfor register or packet fields,:::barsfor categories,:::matrixfor a feature comparison,:::treefor a hierarchy,:::calloutsto name the parts of a picture,:::scatter(point X Y "LABEL",fit) for two quantities,:::distfor a spread,:::sankeyfor flows,:::treemapfor nested shares,:::quadrant,:::vennand:::funnel,:::mapfor places, routes and choropleths,:::contour,:::rasterand:::polarfor fields and directions,:::waterfall,:::waffle,:::slope,:::paralleland:::network,:::equationsand:::symbolsfor derivations. Options worth knowing:area,percentanderr=on a plot,percentanddotson bars,stripandecdfon a dist,shadeon a matrix for a heatmap,ends=1:Nandlaneon a diagram,milestoneandafteron a timeline, a::::rowof three or more for small multiples,[[spark 3 5 4 8]]inline.CATALOG.mdpicks a figure by the job it does, and section A.9 of the reference sheet is a table for choosing one. A block that holds blocks takes four colons (::::changedaround:::equations). A long document organizes with parts (# Partthen:::partwiththesis:), astatus=on each mechanism's##heading (built,prototyped,designed,speculative),link=#anchoron the nodes of a system-map:::diagram, a:::trace(step "label" | what happens | #anchor) to walk one thing through the system, and a:::glossary(term | definition);examples/core-blocksshows all five.Render with page PNGs and look at every page:
python <skill dir>/sheet.py report.md --pngFix what overlaps. Diagram edges route round other boxes (one elbow, else a Z through a gap); if none clears, move nodes or use
bend=Rrather than accept an edge through a box. Keep timelinecalllettering clear of the tick labels, and put callout points where their leaders do not cross the picture's own lettering. Keep wide figures (bits,signals,sankey,treemap,timeline, a heatmap) out of::::row. An unclosed block, a missing image or a bad figure spec stops the render with a message naming the block.
To ingest someone else's report without editing it, set front matter from the command line:
-s section=3 -s tab=PHY.
For a screen, the same source renders as an Interactive Whitepaper, one HTML file with a rail, cross-references
and light and dark: python <skill dir>/web.py report.md. Links between parts ([text](#heading-slug),
#fig-N.M, #tab-N.M) work there and print as their words on paper. It needs the page template, SHEET_TEMPLATE.
Requirements: Python 3.8+ with matplotlib, numpy and pyyaml, Chrome or Chromium, the URW base35 fonts.
SHEET_FONTS and SHEET_CHROME override the font directory and browser.