Organize tools and tests and split detailed documentation
Beffroi/beffroi-tools/pipeline/head This commit looks good
Details
Beffroi/beffroi-tools/pipeline/head This commit looks good
Details
This commit is contained in:
parent
537339684b
commit
e9c94d94d4
18
AGENTS.md
18
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
'''
|
||||
}
|
||||
}
|
||||
|
|
|
|||
86
README.md
86
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 `<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`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -0,0 +1 @@
|
|||
"""Regression tests for beffroi-tools."""
|
||||
|
|
@ -5,7 +5,7 @@ import tempfile
|
|||
import unittest
|
||||
from unittest.mock import patch
|
||||
|
||||
import exporter
|
||||
from tools import exporter
|
||||
|
||||
|
||||
class ExporterTests(unittest.TestCase):
|
||||
|
|
@ -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):
|
||||
|
|
@ -0,0 +1 @@
|
|||
"""Local document and media command-line tools."""
|
||||
Loading…
Reference in New Issue