beffroi-tools/docs/development
Dandaedre a09b73e583 Rename Midra Layout to Canvas Pilot 2026-11-15 13:14:33 +01:00
..
README.md Organize documentation by tool and update references 2026-11-14 17:57:06 +01:00
ci.md Build and publish project mdBook manuals through Jenkins 2026-11-14 20:44:11 +01:00
icon-prompts.json Rename Midra Layout to Canvas Pilot 2026-11-15 13:14:33 +01:00
releases.md Rename Midra Layout to Canvas Pilot 2026-11-15 13:14:33 +01:00

README.md

Development

Documentation · CI and coverage · Releases

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 is a separate Rust workspace member with CLI and egui interfaces. Its implementation checklist and evaluation corpus 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:

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 and cross builds and packaging.

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.

The ASCII filename cleaner is a separate Rust workspace member. Run cargo run --locked -p ascii-names for its drag-and-drop window, or pass a folder for CLI cleanup. It uses the same workspace checks and coverage gates.