docs: separate user and contributor guides
Reportist CI Reportist failed CI.
Beffroi/reportist/pipeline/head There was a failure building this commit Details

This commit is contained in:
Dandaedre 2026-09-16 00:47:13 +02:00
parent 1d04ac9b44
commit ee00bb3df9
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
2 changed files with 44 additions and 11 deletions

View File

@ -15,7 +15,7 @@ Beffroi-specific repositories.
Runtime rendering requires Bash, jq, Typst 0.15 or newer, standard POSIX
utilities, and the fonts selected by the report. The examples use DejaVu Sans
and DejaVu Sans Mono. Python and uv are used only for tests.
and DejaVu Sans Mono.
## Render a report
@ -68,17 +68,9 @@ 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.
## Testing
## Contributing
Run validation, rendering, branding, pagination, and standalone tests in a
uv-managed environment:
```bash
make test
```
Poppler's `pdfinfo` and `pdftotext` enable additional pagination and extracted
text checks when installed.
See the [contributor guide](docs/development.md).
## License

41
docs/development.md Normal file
View File

@ -0,0 +1,41 @@
# Development
This document covers contributor workflows for Reportist. Rendering and report
authoring are documented in the main [README](../README.md) and
[report contract](report-contract.md).
## Test environment
Tests require uv and Typst. The Makefile creates `.venv`, synchronizes the pinned
packages from `requirements.txt`, and invokes Python only from that environment.
```bash
make test
```
Poppler's `pdfinfo` and `pdftotext` enable additional pagination and extracted
text checks. Those checks are skipped when Poppler is unavailable.
The suite covers JSON and YAML input, contract failures, optional fields,
replaceable branding, asset safety, overwrite behavior, pagination, extracted
content, and rendering from a standalone component copy.
## Contract maintenance
`schema/report.schema.json` is the public report interface. Keep the jq
production validator, Typst assertions, examples, and test oracle aligned with
the schema. Preserve version 1 compatibility or introduce a documented new
version and migration path.
## Visual changes
Exercise all supported content blocks and inspect representative PDFs after
changing templates, typography, colors, spacing, headers, footers, or pagination.
Record the Typst version and installed fonts because they can affect layout and
PDF bytes.
## Repository boundaries
Reportist stays generic. Do not add diagnostic interpretation, Beffroi branding,
incident storage, publication, or packaging. Production validation and rendering
remain shell, jq, and Typst based; Python stays under `tests/`.