From 79179b2f6844bc76ee062d18a6b4cc4c9a736121 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Wed, 16 Sep 2026 02:03:08 +0200 Subject: [PATCH] docs: focus readme on standalone report making --- README.md | 78 ++++++++++++------------------------------------------- 1 file changed, 16 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index edbeb65..a0765ac 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,32 @@ # Reportist -Reportist is a standalone Typst-based renderer for structured reports. It -validates YAML or JSON input and produces sober, reproducible PDF documents. +Reportist is a standalone structured-report maker. Give it a YAML or JSON report +definition and it produces a PDF with Typst. It has no dependency on the Beffroi +integration repository or diagnostic tools. -```text -report.yaml or report.json → validate → Typst → report.pdf -``` - -Reportist handles report structure, branding, presentation, and rendering. It -does not collect evidence or interpret diagnostics, and it has no dependency on -Beffroi-specific repositories. - -## Requirements - -Runtime rendering requires Bash, Typst 0.15 or newer, standard POSIX -utilities, and the fonts selected by the report. The examples use DejaVu Sans -and DejaVu Sans Mono. - -## Render a report +## Render one report ```bash -bash tools/render.sh report.yaml --output report.pdf +bash tools/render.sh examples/example-report.yaml --output report.pdf ``` -Render every YAML and JSON report in a directory tree with: +The renderer validates the input, loads an optional report-relative logo, and +writes the completed PDF. Existing output requires `--force`. + +## Render every report in a directory ```bash -bash tools/render-all.sh reports --output-dir output +bash tools/render-all.sh /path/to/reports --output-dir /path/to/pdfs ``` -The renderer validates input before invoking Typst. It stages the report and its -branding asset in an isolated temporary project, then publishes the completed -PDF after a successful render. Existing output is rejected unless `--force` is explicit. - -Logo paths resolve relative to the input report. Absolute paths, parent -traversal, and symlinked assets are rejected. Reports without branding use the -neutral default theme. - -Use `--typst /path/to/typst` when Typst is not available under the default -command name. - -## Validate a report +## Validate without rendering ```bash bash tools/validate.sh examples/example-report.yaml +bash tools/validate-all.sh /path/to/reports ``` -Use `bash tools/validate-all.sh DIRECTORY` to validate a directory tree. - -The version 1 format supports metadata, branding, summaries, timelines, -findings, generic content sections, action plans, provenance, and appendices. -See [docs/report-contract.md](docs/report-contract.md) and -[schema/report.schema.json](schema/report.schema.json) for the complete public -contract. - -## Exit codes - -| Code | Meaning | -| --- | --- | -| `0` | Validation or rendering succeeded | -| `1` | Input, validation, asset, Typst, or I/O failure | -| `2` | Invalid command-line usage | - -## Reproducibility - -Record the Reportist revision, `typst --version`, and installed font files when -recreating a historical document. PDF bytes can vary across Typst or font -versions even when the report content and layout remain equivalent. - -## Contributing - -See the [contributor guide](docs/development.md). - -## License - -The software is licensed under the MIT License. Examples and bundled assets may -carry their own terms where indicated. +Start with [`examples/example-report.yaml`](examples/example-report.yaml) or the +smaller [`examples/minimal-report.json`](examples/minimal-report.json). See +[`docs/report-contract.md`](docs/report-contract.md) for all fields and +[`docs/development.md`](docs/development.md) for tests and template development.