Organize tools and tests and split detailed documentation
Beffroi/beffroi-tools/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-10-20 10:13:07 +02:00
parent 537339684b
commit e9c94d94d4
12 changed files with 121 additions and 83 deletions

View File

@ -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.

2
Jenkinsfile vendored
View File

@ -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
'''
}
}

View File

@ -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 `<presentation-stem>_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 `<file-stem>_export/`: `<file-stem>.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`.

47
docs/development.md Normal file
View File

@ -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.

19
docs/exporter.md Normal file
View File

@ -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 `<file-stem>_export/`: `<file-stem>.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.

26
docs/pptx-videos.md Normal file
View File

@ -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 `<presentation-stem>_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.

1
tests/__init__.py Normal file
View File

@ -0,0 +1 @@
"""Regression tests for beffroi-tools."""

View File

@ -5,7 +5,7 @@ import tempfile
import unittest
from unittest.mock import patch
import exporter
from tools import exporter
class ExporterTests(unittest.TestCase):

View File

@ -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):

1
tools/__init__.py Normal file
View File

@ -0,0 +1 @@
"""Local document and media command-line tools."""