docs: separate user and contributor guides
Reportist CI Reportist failed CI.
Beffroi/reportist/pipeline/head There was a failure building this commit
Details
Reportist CI Reportist failed CI.
Beffroi/reportist/pipeline/head There was a failure building this commit
Details
This commit is contained in:
parent
1d04ac9b44
commit
ee00bb3df9
14
README.md
14
README.md
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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/`.
|
||||
Loading…
Reference in New Issue