59 lines
2.8 KiB
Markdown
59 lines
2.8 KiB
Markdown
# Development
|
|
|
|
## Layout and workflow
|
|
|
|
| Directory | Purpose |
|
|
| --- | --- |
|
|
| `tools/` | Python prototypes and document utilities |
|
|
| `tests/` | Python regression and CI/packaging tests |
|
|
| `crates/<tool>/` | Rust ports, each with its own source, tests and assets |
|
|
| `scripts/` | Shared CI and release helpers |
|
|
| `docs/` | Tool usage and specialized workflows |
|
|
|
|
Prototype in Python, then add a Rust workspace member when the workflow is
|
|
stable. Retire the Python implementation once the Rust port is validated.
|
|
The PPTX reporter is now Rust-only; the document exporter remains Python.
|
|
The [rundown converter](rundown-converter.md) is a separate Rust workspace member
|
|
with CLI and egui interfaces. Its [implementation checklist](rundown-converter-plan.md)
|
|
and [evaluation corpus](rundown-corpus.md) track coverage and remaining limitations.
|
|
Avoid speculative shared crates; extract common code when multiple tools need it.
|
|
|
|
The root `Cargo.toml` owns workspace metadata, the shared version and build
|
|
profiles. Members inherit that metadata. Keep one root `Cargo.lock` and `target/`.
|
|
The reporter is the default member; CI explicitly checks the entire workspace.
|
|
Use `-p pptx-reporter` to select it when building from a multi-tool workspace.
|
|
|
|
## Checks
|
|
|
|
Use a recent stable Rust toolchain. Python tools need 3.9+; CI helpers need 3.11+.
|
|
Run from the repository root:
|
|
|
|
```sh
|
|
cargo fmt --all --check
|
|
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
|
|
cargo test --locked --workspace --all-features
|
|
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
|
|
python3 -m unittest discover -s tests -v
|
|
cargo build --locked --workspace --all-features
|
|
```
|
|
|
|
Rust regression tests cover archive parsing, trimming, loops, report formats,
|
|
Ontime, CLI errors and GUI state; both PDF layouts compile with the embedded
|
|
engine. Probe-process tests use a controlled stub. No external FFmpeg, FFprobe
|
|
or Typst CLI is required for CI. The application still needs FFprobe at runtime.
|
|
Python exporter tests mock external document applications. Inspect rendering
|
|
changes visually as well.
|
|
|
|
`cargo build -p pptx-reporter --no-default-features` builds the CLI without the
|
|
GUI or PDF engine; add `--features pdf` to restore embedded PDFs.
|
|
|
|
Keep generated files out of Git. Commit each completed task after checks; do
|
|
not push without authorization. See [CI and coverage](ci.md) and
|
|
[cross builds and packaging](releases.md).
|
|
|
|
The converter can run without desktop dependencies using
|
|
`cargo run --locked -p rundown-converter --no-default-features --bin rundown-converter -- --help`.
|
|
Its tests generate synthetic XLSX inputs and never require private source files
|
|
or network downloads. The existing workspace test, lint, Rustdoc and coverage
|
|
commands include both tools; reporter release packaging remains separate.
|