2.0 KiB
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, parity and release helpers |
docs/ |
Tool usage and specialized workflows |
Prototype in Python, then add a Rust workspace member when the workflow is stable. Keep the Python implementation as a parity reference while useful. 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:
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
python3 scripts/parity.py target/debug/pptx-reporter
Parity requires FFmpeg, FFprobe and the Typst CLI for the Python reference. It compares JSON/Ontime for real media with trims, loops, custom timing and orphan media, and generates every report format. 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 and cross builds and packaging.