58 lines
3.1 KiB
Markdown
58 lines
3.1 KiB
Markdown
# beffroi-tools
|
|
|
|
This repository contains small Python command-line tools for everyday local
|
|
document and media workflows. Keep them simple to run. Keep `README.md` minimal,
|
|
with quick-start examples and links to detailed documentation in `docs/`.
|
|
|
|
## Current tools
|
|
|
|
- `tools/pptx_videos.py` discovers and extracts embedded PPTX videos, maps them to
|
|
slides, probes metadata with FFmpeg's `ffprobe`, and generates timing reports
|
|
in Markdown, plain text, JSON, HTML, Typst, PDF, and Ontime 4 JSON. Markdown
|
|
and Ontime are the defaults. PDF reports compile through the Typst CLI.
|
|
- `tools/ontime.py` maps video references into an importable Ontime rundown.
|
|
- `tools/progress.py` provides shared transient terminal progress and plain logs
|
|
for redirected output; `tests/test_progress.py` checks display cleanup.
|
|
- `tools/exporter.py` uses DeckCraft to export PPTX presentations to PDF or PNG slides,
|
|
and PdfCraft to render PDF pages as PNGs. It discovers CLI executables or
|
|
locally installed AppImages. PDF-to-PDF is a successful no-op.
|
|
- `tests/test_exporter.py` covers exporter validation, no-op behavior, conversion
|
|
failures, and overwrite behavior.
|
|
- `tests/test_pptx_videos.py` covers slide discovery, extraction, temporary probing,
|
|
report formatting, and error handling.
|
|
- `Jenkinsfile` runs the Python unit tests on `rust_no_docker`. CI is test-only:
|
|
no publishing, badges, or archived artifacts.
|
|
|
|
## Working conventions
|
|
|
|
- Prefer Python's standard library and existing external CLI tools over adding
|
|
dependencies.
|
|
- Preserve source documents. Keep temporary files temporary and require an
|
|
explicit overwrite option when replacing existing exports.
|
|
- Provide useful progress and actionable errors. Terminal colors should respect
|
|
`NO_COLOR` and disappear when output is redirected.
|
|
- Preserve slide order, readable aligned text reports, and consistent styling
|
|
in visual reports.
|
|
- Keep tools in `tools/`, tests in `tests/`, and specialized documentation in
|
|
`docs/`. Update the relevant docs when options or workflows change; keep the
|
|
README's examples and links current.
|
|
- Run checks appropriate to the change before committing. Exporter regression
|
|
tests and video-report tests run with
|
|
`python3 -m unittest discover -s tests -v`. For rendering changes,
|
|
test with the actual external tools when available and inspect visual output.
|
|
Report any checks that could not be completed.
|
|
|
|
## Commit every task
|
|
|
|
- Every completed task that changes repository files must end with a Git commit.
|
|
Committing the task is part of completing it; do not wait for a separate user
|
|
request to commit.
|
|
- Inspect the working tree first. Stage only changes belonging to the task;
|
|
preserve unrelated or pre-existing changes.
|
|
- Use a concise, descriptive commit message explaining the change.
|
|
- Do not commit generated exports, temporary files, credentials, or caches.
|
|
- Include the commit hash and validation summary in the final response.
|
|
- If committing is blocked, explain why and identify the uncommitted changes.
|
|
Do not claim the task was committed.
|
|
- Read-only tasks need no empty commit. Do not push commits unless requested.
|