diff --git a/AGENTS.md b/AGENTS.md index 7dc9d56..ad2e786 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,21 +1,21 @@ # beffroi-tools This repository contains small Python command-line tools for everyday local -document and media workflows. Keep them simple to run and document their usage -in `README.md`. +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 -- `pptx_videos.py` discovers and extracts embedded PPTX videos, maps them to +- `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, and PDF. PDF reports compile through the Typst CLI. -- `exporter.py` uses DeckCraft to export PPTX presentations to PDF or PNG slides, +- `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. -- `test_exporter.py` covers exporter validation, no-op behavior, conversion +- `tests/test_exporter.py` covers exporter validation, no-op behavior, conversion failures, and overwrite behavior. -- `test_pptx_videos.py` covers slide discovery, extraction, temporary probing, +- `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. @@ -30,10 +30,12 @@ in `README.md`. `NO_COLOR` and disappear when output is redirected. - Preserve slide order, readable aligned text reports, and consistent styling in visual reports. -- Update `README.md` when command-line options or workflows change. +- 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 -v test_exporter test_pptx_videos`. For rendering changes, + `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. diff --git a/Jenkinsfile b/Jenkinsfile index 18be62e..13ff746 100644 --- a/Jenkinsfile +++ b/Jenkinsfile @@ -38,7 +38,7 @@ pipeline { steps { sh ''' set -eu - python3 -m unittest -v test_exporter test_pptx_videos + python3 -m unittest discover -s tests -v ''' } } diff --git a/README.md b/README.md index c48f123..072cc72 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,21 @@ # beffroi-tools -Beffroi tools, for everyday usage - -## PPTX video reports - -Extract videos and create a Markdown timing report: +Small Python command-line tools for local document and media workflows. +Requires Python 3.9+. ```sh -python pptx_videos.py presentation.pptx +# Extract embedded videos and report their timings (requires ffprobe). +python3 tools/pptx_videos.py presentation.pptx + +# Export slides to PDF and PNG images (requires DeckCraft). +python3 tools/exporter.py presentation.pptx --output pdf,images + +# Render PDF pages as PNG images (requires PdfCraft). +python3 tools/exporter.py document.pdf --output images ``` -Generate one or more report formats without keeping newly extracted videos: +- [Video reports](docs/pptx-videos.md) — formats, extraction modes, and dependencies. +- [Document exports](docs/exporter.md) — image resolution, AppImages, and output options. +- [Development and CI](docs/development.md) — layout, tests, and Jenkins setup. -```sh -python pptx_videos.py presentation.pptx --timings-only --report html,pdf -python pptx_videos.py presentation.pptx --report html,typst,pdf,md,txt,json -``` - -`--report` accepts comma-separated formats and can be repeated. Markdown is the -default. Reports are saved as `timings.*` in `_videos`, or the -directory supplied with `-o`. PDF uses the Typst CLI and retains `timings.typ` -for editing. HTML and Typst/PDF include colored summary cards and pills; -Markdown and TXT use aligned tables. JSON includes numeric durations in seconds, -sizes in bytes, and slide references. - -Timings require `ffprobe` (from FFmpeg); PDF additionally requires `typst` on -`PATH`. Use `--extract-only` to extract without a report. Presentations with no -embedded videos produce no output. Terminal progress uses colors automatically; -set `NO_COLOR` to disable them. - -## Export presentations and PDF pages - -```sh -python exporter.py presentation.pptx --output pdf,images -python exporter.py document.pdf --output images -python exporter.py presentation.pptx --output images --dpi 192 -d exports -``` - -`exporter.py` uses DeckCraft for PPTX exports and PdfCraft for PDF page rendering. -It finds `deckcraft-cli` / `pdfcraft-cli` on `PATH`, or temporarily extracts the -bundled CLI from the newest matching AppImage in `~/Applications`. You can -specify a CLI executable or AppImage with `--deckcraft-cli` / `--pdfcraft-cli`, -or the `DECKCRAFT_CLI` / `PDFCRAFT_CLI` environment variables. - -Output goes to `_export/`: `.pdf` and/or numbered PNGs -inside `images/`. Images default to 144 DPI. Existing output requires -`--overwrite`, which replaces generated files and removes stale numbered -slide/page PNGs. PDF-to-PDF is a successful no-op; other input extensions are -errors. Rendering completes in temporary storage before output is copied. - -## Tests and Jenkins - -Run the same suite locally and in Jenkins: - -```sh -python3 -m unittest -v test_exporter test_pptx_videos -``` - -The declarative `Jenkinsfile` uses the `rust_no_docker` worker label and requires -Git and Python 3.9 or newer. It performs a clean SCM checkout, checks Python, -and runs the standard-library unit tests. No packages are installed. - -Tests cover export validation, overwrite handling, failed conversions, PPTX -discovery and slide order, temporary video cleanup, report formats, and PDF -compiler invocation. External CLI calls are mocked: CI does not require FFmpeg, -Typst, DeckCraft, or PdfCraft and does not claim to verify rendering fidelity. - -This is a test-only pipeline on every configured branch: no build artifacts, -archives, publication, badges, or Checks API calls. Status is reported in Jenkins. -There are no pipeline credential bindings; SCM access uses the Jenkins job's -configured repository credentials. - -Configure a Pipeline from SCM or multibranch job for this repository with -`Jenkinsfile` as the script path (`main` is the default branch). For a Gitea-aware -multibranch job, use the installation's Jenkins base URL plus -`/gitea-webhook/post` as the Gitea webhook target and enable push events. -The Jenkins administrator must supply the actual reachable URL and SCM -credentials. This repository does not create the job or register the webhook. +Run commands from the repository root. Each tool supports `--help`. diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..d888739 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,47 @@ +# Development and CI + +## Project layout + +| Path | Purpose | +| --- | --- | +| `tools/` | Standalone command-line scripts, also importable as Python modules | +| `tests/` | Standard-library unit tests | +| `docs/` | Detailed usage and development documentation | +| `Jenkinsfile` | Test-only Jenkins pipeline | +| `AGENTS.md` | Contributor instructions and commit policy | + +Run the commands below from the repository root. No Python package installation +is needed. To run an individual suite, use +`python3 -m unittest -v tests.test_exporter` or +`python3 -m unittest -v tests.test_pptx_videos`. + +## Tests + +Run the same suite locally and in Jenkins: + +```sh +python3 -m unittest discover -s tests -v +``` + +Tests cover export validation, overwrite handling, failed conversions, PPTX +discovery and slide order, temporary video cleanup, report formats, and PDF +compiler invocation. External CLI calls are mocked: CI does not require FFmpeg, +Typst, DeckCraft, or PdfCraft and does not claim to verify rendering fidelity. + +## Jenkins + +The declarative `Jenkinsfile` uses the `rust_no_docker` worker label and requires +Git and Python 3.9 or newer. It performs a clean SCM checkout, checks Python, +and runs the standard-library unit tests. No packages are installed. + +This is a test-only pipeline on every configured branch: no build artifacts, +archives, publication, badges, or Checks API calls. Status is reported in Jenkins. +There are no pipeline credential bindings; SCM access uses the Jenkins job's +configured repository credentials. + +Configure a Pipeline from SCM or multibranch job for this repository with +`Jenkinsfile` as the script path (`main` is the default branch). For a Gitea-aware +multibranch job, use the installation's Jenkins base URL plus +`/gitea-webhook/post` as the Gitea webhook target and enable push events. +The Jenkins administrator must supply the actual reachable URL and SCM +credentials. This repository does not create the job or register the webhook. diff --git a/docs/exporter.md b/docs/exporter.md new file mode 100644 index 0000000..9efd0f3 --- /dev/null +++ b/docs/exporter.md @@ -0,0 +1,19 @@ +# Export presentations and PDF pages + +```sh +python3 tools/exporter.py presentation.pptx --output pdf,images +python3 tools/exporter.py document.pdf --output images +python3 tools/exporter.py presentation.pptx --output images --dpi 192 -d exports +``` + +`exporter.py` uses DeckCraft for PPTX exports and PdfCraft for PDF page rendering. +It finds `deckcraft-cli` / `pdfcraft-cli` on `PATH`, or temporarily extracts the +bundled CLI from the newest matching AppImage in `~/Applications`. You can +specify a CLI executable or AppImage with `--deckcraft-cli` / `--pdfcraft-cli`, +or the `DECKCRAFT_CLI` / `PDFCRAFT_CLI` environment variables. + +Output goes to `_export/`: `.pdf` and/or numbered PNGs +inside `images/`. Images default to 144 DPI. Existing output requires +`--overwrite`, which replaces generated files and removes stale numbered +slide/page PNGs. PDF-to-PDF is a successful no-op; other input extensions are +errors. Rendering completes in temporary storage before output is copied. diff --git a/docs/pptx-videos.md b/docs/pptx-videos.md new file mode 100644 index 0000000..9df499f --- /dev/null +++ b/docs/pptx-videos.md @@ -0,0 +1,26 @@ +# PPTX video reports + +Extract videos and create a Markdown timing report: + +```sh +python3 tools/pptx_videos.py presentation.pptx +``` + +Generate one or more report formats without keeping newly extracted videos: + +```sh +python3 tools/pptx_videos.py presentation.pptx --timings-only --report html,pdf +python3 tools/pptx_videos.py presentation.pptx --report html,typst,pdf,md,txt,json +``` + +`--report` accepts comma-separated formats and can be repeated. Markdown is the +default. Reports are saved as `timings.*` in `_videos`, or the +directory supplied with `-o`. PDF uses the Typst CLI and retains `timings.typ` +for editing. HTML and Typst/PDF include colored summary cards and pills; +Markdown and TXT use aligned tables. JSON includes numeric durations in seconds, +sizes in bytes, and slide references. + +Timings require `ffprobe` (from FFmpeg); PDF additionally requires `typst` on +`PATH`. Use `--extract-only` to extract without a report. Presentations with no +embedded videos produce no output. Terminal progress uses colors automatically; +set `NO_COLOR` to disable them. diff --git a/tests/__init__.py b/tests/__init__.py new file mode 100644 index 0000000..c03eb7a --- /dev/null +++ b/tests/__init__.py @@ -0,0 +1 @@ +"""Regression tests for beffroi-tools.""" diff --git a/test_exporter.py b/tests/test_exporter.py similarity index 99% rename from test_exporter.py rename to tests/test_exporter.py index 4ed9e9e..ba64a63 100644 --- a/test_exporter.py +++ b/tests/test_exporter.py @@ -5,7 +5,7 @@ import tempfile import unittest from unittest.mock import patch -import exporter +from tools import exporter class ExporterTests(unittest.TestCase): diff --git a/test_pptx_videos.py b/tests/test_pptx_videos.py similarity index 99% rename from test_pptx_videos.py rename to tests/test_pptx_videos.py index eb93539..78261d9 100644 --- a/test_pptx_videos.py +++ b/tests/test_pptx_videos.py @@ -9,7 +9,7 @@ import unittest from unittest.mock import patch import zipfile -import pptx_videos as videos +from tools import pptx_videos as videos class VideoTests(unittest.TestCase): diff --git a/tools/__init__.py b/tools/__init__.py new file mode 100644 index 0000000..35c4f75 --- /dev/null +++ b/tools/__init__.py @@ -0,0 +1 @@ +"""Local document and media command-line tools.""" diff --git a/exporter.py b/tools/exporter.py similarity index 100% rename from exporter.py rename to tools/exporter.py diff --git a/pptx_videos.py b/tools/pptx_videos.py similarity index 100% rename from pptx_videos.py rename to tools/pptx_videos.py