docs: focus readme on standalone report making
This commit is contained in:
parent
7a7ba72524
commit
79179b2f68
78
README.md
78
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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue