From f88450be835ebaed7fc8ad1dd8ba895538d40c92 Mon Sep 17 00:00:00 2001
From: Dandaedre
Date: Sat, 14 Nov 2026 20:44:11 +0100
Subject: [PATCH] Build and publish project mdBook manuals through Jenkins
---
Jenkinsfile | 20 ++
README.md | 1 +
docs/README.md | 2 +
docs/ascii-names/changelog.md | 2 +
docs/development/ci.md | 22 +-
docs/exporter/changelog.md | 2 +
docs/manuals/README.md | 104 +++++++
docs/manuals/ascii-names/SUMMARY.md | 6 +
docs/manuals/ascii-names/book.toml | 25 ++
docs/manuals/exporter/SUMMARY.md | 5 +
docs/manuals/exporter/book.toml | 25 ++
docs/manuals/mdbook-version | 1 +
docs/manuals/media-player-classic/SUMMARY.md | 6 +
docs/manuals/media-player-classic/book.toml | 25 ++
docs/manuals/midra-layout/SUMMARY.md | 25 ++
docs/manuals/midra-layout/book.toml | 25 ++
docs/manuals/pptx-reporter/SUMMARY.md | 8 +
docs/manuals/pptx-reporter/book.toml | 25 ++
docs/manuals/rundown-converter/SUMMARY.md | 8 +
docs/manuals/rundown-converter/book.toml | 25 ++
docs/media-player-classic/changelog.md | 2 +
docs/midra-layout/changelog.md | 2 +
docs/pptx-reporter/changelog.md | 2 +
docs/rundown-converter/changelog.md | 2 +
scripts/manuals.py | 282 +++++++++++++++++++
tests/test_manuals.py | 187 ++++++++++++
26 files changed, 838 insertions(+), 1 deletion(-)
create mode 100644 docs/manuals/README.md
create mode 100644 docs/manuals/ascii-names/SUMMARY.md
create mode 100644 docs/manuals/ascii-names/book.toml
create mode 100644 docs/manuals/exporter/SUMMARY.md
create mode 100644 docs/manuals/exporter/book.toml
create mode 100644 docs/manuals/mdbook-version
create mode 100644 docs/manuals/media-player-classic/SUMMARY.md
create mode 100644 docs/manuals/media-player-classic/book.toml
create mode 100644 docs/manuals/midra-layout/SUMMARY.md
create mode 100644 docs/manuals/midra-layout/book.toml
create mode 100644 docs/manuals/pptx-reporter/SUMMARY.md
create mode 100644 docs/manuals/pptx-reporter/book.toml
create mode 100644 docs/manuals/rundown-converter/SUMMARY.md
create mode 100644 docs/manuals/rundown-converter/book.toml
create mode 100644 scripts/manuals.py
create mode 100644 tests/test_manuals.py
diff --git a/Jenkinsfile b/Jenkinsfile
index 8ef0545..5b1d475 100644
--- a/Jenkinsfile
+++ b/Jenkinsfile
@@ -4,6 +4,7 @@ pipeline {
options {
skipDefaultCheckout(true)
+ disableConcurrentBuilds()
timeout(time: 45, unit: 'MINUTES')
}
@@ -13,6 +14,7 @@ pipeline {
NO_COLOR = '1'
CARGO_TERM_COLOR = 'never'
BADGE_ROOT = '/mnt/assets/coverage'
+ MANUALS_ROOT = '/mnt/books/manuals'
}
stages {
@@ -36,6 +38,11 @@ pipeline {
cargo install cargo-llvm-cov --version 0.9.1 --locked
fi
rustup component add llvm-tools-preview clippy rustfmt
+ mdbook_version=$(cat docs/manuals/mdbook-version)
+ if ! mdbook --version 2>/dev/null | grep -Fx "mdbook v${mdbook_version}"; then
+ cargo install mdbook --version "$mdbook_version" --locked
+ fi
+ command -v rsync
'''
}
}
@@ -68,9 +75,22 @@ pipeline {
}
}
}
+ stage('Build manuals') {
+ steps { sh 'python3 scripts/manuals.py build' }
+ }
stage('Coverage') {
steps { sh 'python3 scripts/ci.py coverage' }
}
+ stage('Publish manuals') {
+ when {
+ allOf {
+ branch 'main'
+ not { changeRequest() }
+ expression { currentBuild.currentResult == 'SUCCESS' }
+ }
+ }
+ steps { sh 'python3 scripts/manuals.py publish --destination "$MANUALS_ROOT"' }
+ }
}
post {
diff --git a/README.md b/README.md
index 87dd654..44b1332 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,7 @@
Portable releases ·
Quick start ·
Documentation ·
+ Manuals ·
What's new ·
Development
diff --git a/docs/README.md b/docs/README.md
index 43d1845..2586cef 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -15,6 +15,8 @@
## Shared resources
+- **mdBook manuals:** [all six manuals, local preview and Jenkins publication](manuals/README.md).
+
- **Development:** [setup and checks](development/README.md), [CI and coverage](development/ci.md), [builds and portable releases](development/releases.md), [application artwork](development/releases.md#application-artwork).
- **File and device contracts:** [interface index](interfaces/README.md), including versioned examples and compatibility rules.
- **Starter files:** [Midra Layout catalog](templates/midra-layout/README.md), with Full HD and 4K base files in all nine exchange formats.
diff --git a/docs/ascii-names/changelog.md b/docs/ascii-names/changelog.md
index a18babb..787a085 100644
--- a/docs/ascii-names/changelog.md
+++ b/docs/ascii-names/changelog.md
@@ -4,6 +4,8 @@
## Unreleased
+- Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under `/mnt/books/manuals/`; staging, link validation and scoped publication have regression coverage.
+
- Use absolute Gitea main-branch URLs for repository file links in the root README; verify linked files exist.
## v0.6.0 — 2026-11-14
diff --git a/docs/development/ci.md b/docs/development/ci.md
index 88c476d..e1fe1f9 100644
--- a/docs/development/ci.md
+++ b/docs/development/ci.md
@@ -8,7 +8,9 @@ of its successful-rename paths. Those paths must also run on a supported host;
see [FreeBSD test coverage](../ascii-names/README.md#freebsd-ci-hosts).
SCM credentials, webhooks and the publication mount are administrator setup.
CI checks formatting, Clippy, rustdoc, Python/Rust tests and
-whole-workspace Rust coverage. It never creates tags or release artifacts.
+whole-workspace Rust coverage. It also builds six mdBook manuals and publishes
+successful non-PR main builds to `/mnt/books/manuals/`. It never creates tags or
+release artifacts.
The Python reporter and cross-language parity checks are retired. CI uses the
Rust reporter's own regression tests and embedded PDF engine, plus Python
@@ -85,3 +87,21 @@ Actual Jenkins archival/publication and public URL retrieval are separate
external checkpoints. Local checks do not establish that badges are live.
The asset server should mount assets read-only, disable listings, serve SVG
with restrictive CSP, and revalidate mutable URLs or use a short cache lifetime.
+
+## Project manuals
+
+The Tools stage installs the mdBook version pinned in
+[`docs/manuals/mdbook-version`](../manuals/mdbook-version) and requires `rsync`.
+The Build manuals stage stages existing documentation, builds all six books, and
+checks rendered links, anchors and downloadable assets. No mdBook plugins or
+additional Jenkins plugins are needed. Tests cover staging and publication into
+temporary directories, including stale-file cleanup and preservation of unrelated
+manuals. Publication runs after coverage, only when the whole build is successful,
+on non-PR main. The helper independently enforces the branch/PR restriction.
+
+The worker must expose the existing writable `/mnt/books` mount. The six manuals
+and a shared landing page are published under `/mnt/books/manuals/`; deletion is
+scoped to each owned book directory. This follows the referenced mdBook pipeline's
+Cargo/build/rsync method while keeping the existing badge cleanup behavior intact.
+See [manual configuration, preview and publication](../manuals/README.md) for
+paths, prerequisites and update behavior.
diff --git a/docs/exporter/changelog.md b/docs/exporter/changelog.md
index 3a76a4b..56d8455 100644
--- a/docs/exporter/changelog.md
+++ b/docs/exporter/changelog.md
@@ -4,6 +4,8 @@
## Unreleased
+- Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under `/mnt/books/manuals/`; staging, link validation and scoped publication have regression coverage.
+
- Use absolute Gitea main-branch URLs for repository file links in the root README; verify linked files exist.
## v0.6.0 — 2026-11-14
diff --git a/docs/manuals/README.md b/docs/manuals/README.md
new file mode 100644
index 0000000..c7ac3c1
--- /dev/null
+++ b/docs/manuals/README.md
@@ -0,0 +1,104 @@
+# Project manuals
+
+[Documentation](../README.md) · [CI and coverage](../development/ci.md)
+
+Each project has an mdBook manual, built from the existing documentation. Edit the
+original guides; the build stages them without creating a second maintained copy.
+The published landing page includes all six project icons and manual links.
+
+| Manual | Contents | Published directory |
+| --- | --- | --- |
+| ASCII Names | [Chapter list](ascii-names/SUMMARY.md) | `/mnt/books/manuals/ascii-names/` |
+| Document Exporter | [Chapter list](exporter/SUMMARY.md) | `/mnt/books/manuals/exporter/` |
+| MPC-HC Companion | [Chapter list](media-player-classic/SUMMARY.md) | `/mnt/books/manuals/media-player-classic/` |
+| Midra Layout | [Chapter list](midra-layout/SUMMARY.md) | `/mnt/books/manuals/midra-layout/` |
+| PPTX Reporter | [Chapter list](pptx-reporter/SUMMARY.md) | `/mnt/books/manuals/pptx-reporter/` |
+| Rundown Converter | [Chapter list](rundown-converter/SUMMARY.md) | `/mnt/books/manuals/rundown-converter/` |
+
+The landing page is `/mnt/books/manuals/index.html`. The books assume the books
+server exposes that directory as `/manuals/`; each `book.toml` declares the
+corresponding `site-url` for its 404 page. No public hostname is hardcoded.
+
+## Build and preview
+
+Requires Python 3.11+, Rust/Cargo for installation, and mdBook **0.5.4**, pinned in
+[mdbook-version](mdbook-version). No mdBook plugins are required. From the repository root:
+
+```sh
+cargo install mdbook --version "$(cat docs/manuals/mdbook-version)" --locked
+python3 scripts/manuals.py build
+python3 scripts/manuals.py check
+python3 -m http.server 8000 --directory build/manuals/site
+```
+
+Open `http://localhost:8000/manuals/`. Search, chapter navigation, themes and
+printable manuals are supplied by mdBook. To use a separately installed binary,
+pass `--mdbook /path/to/mdbook` to the build command.
+
+Generated source trees are in `build/manuals/sources//`; rendered files
+are in `build/manuals/site/manuals/`. Both are ignored. All books must build and
+pass rendered-link validation before the output is made available for publication.
+The validator checks local assets, downloads, chapter links and heading fragments;
+it does not request external websites. mdBook's generated 404 heading links are
+adjusted to remain on the 404 page despite its HTML base URL.
+
+## Maintain a manual
+
+Each project directory here contains a `book.toml` and `SUMMARY.md`:
+
+- `SUMMARY.md` lists canonical Markdown chapters with paths relative to itself.
+ Add or reorder entries here. The linked files remain readable in the repository.
+- `book.toml` configures the staged mdBook. Its `[manual]` table provides the
+ repository-relative project icon used by the landing page; the staging script
+ removes this table before calling mdBook.
+- Run the helper rather than running `mdbook build` directly in these configuration
+ directories: it creates the `src` tree and rewrites chapter and asset links.
+- Included chapters link to other included chapters locally. References to guides
+ outside the current book, source code and repository directories link to Gitea.
+ Referenced screenshots, icons, text quick starts, schema examples and starter
+ files are copied into the book with their original bytes. Midra's catalog includes
+ all 18 starter files, including native PPTX, FIG and AI downloads.
+- Fenced code blocks retain their literal command examples. Keep documentation
+ links in ordinary Markdown or quoted HTML `href`/`src` attributes; the helper
+ currently handles inline Markdown links without optional title attributes.
+- Update the tool's changelog for documentation changes. Keep generated HTML and
+ staging files out of Git.
+
+## Jenkins publication
+
+The repository [Jenkinsfile](../../Jenkinsfile) follows the supplied
+[Deathwatch mdBook pipeline](https://proxy.dandaedre.com/gitea/Books/deathwatch-d10/raw/branch/main/Jenkinsfile):
+use `rust_no_docker`, install mdBook with Cargo, build HTML, then publish using
+`rsync -a --delete`. Here mdBook is pinned, installation errors fail the build,
+and no unused preprocessors or custom Jenkins warning-parser plugins are installed.
+Rendered-link validation supplies a build gate before publication.
+
+Jenkins needs `rsync` on PATH and an existing writable `/mnt/books` mount visible
+inside the worker jail. The helper creates `manuals/` and the six book directories;
+it fails if the parent mount is missing. Web server routing and that mount are
+administrator setup. Jenkins does not create them.
+
+Every branch builds the manuals. Only a successful non-PR `main` build publishes,
+after the test and coverage stages. Concurrent builds of the same job are disabled.
+The publication helper also rejects any environment without `BRANCH_NAME=main`
+or with `CHANGE_ID` set.
+
+```sh
+# Run by Jenkins, with its existing branch/PR environment:
+python3 scripts/manuals.py publish --destination /mnt/books/manuals
+```
+
+Publication validates the whole rendered set before writing, refuses symlinked
+source/destination directories, and runs `rsync --delete` separately inside each
+of the six owned book directories. It never synchronizes or deletes the shared
+`/mnt/books` or `manuals` root. Unrelated manuals and root files survive. The landing
+page is replaced atomically after all book synchronizations succeed. Each book's
+rsync is an in-place update, not an atomic release of the entire collection; a
+failed rsync fails Jenkins and leaves the existing landing page in place. A later
+successful build retries the complete set. Removing a manual configuration does
+not automatically delete its previously published directory.
+
+Existing badge archival/publication stays separate and still archives exactly
+three SVGs. This workflow does not create tags, releases or release binaries.
+Local builds and temporary publication tests do not mean the live books server
+has been updated; that happens when this commit runs successfully on Jenkins main.
diff --git a/docs/manuals/ascii-names/SUMMARY.md b/docs/manuals/ascii-names/SUMMARY.md
new file mode 100644
index 0000000..9663712
--- /dev/null
+++ b/docs/manuals/ascii-names/SUMMARY.md
@@ -0,0 +1,6 @@
+# Summary
+
+- [User guide](../../ascii-names/README.md)
+- [Builds and portable releases](../../development/releases.md)
+- [Development](../../development/README.md)
+- [Changelog](../../ascii-names/changelog.md)
diff --git a/docs/manuals/ascii-names/book.toml b/docs/manuals/ascii-names/book.toml
new file mode 100644
index 0000000..e68320e
--- /dev/null
+++ b/docs/manuals/ascii-names/book.toml
@@ -0,0 +1,25 @@
+[book]
+title = "ASCII Names Manual"
+description = "Clean up filenames while preserving file contents."
+language = "en"
+src = "src"
+
+[build]
+create-missing = false
+
+[output.html]
+site-url = "/manuals/ascii-names/"
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.playground]
+runnable = false
+
+# Consumed by scripts/manuals.py when staging the book and landing page.
+[manual]
+icon = "crates/ascii-names/assets/app-icon.png"
diff --git a/docs/manuals/exporter/SUMMARY.md b/docs/manuals/exporter/SUMMARY.md
new file mode 100644
index 0000000..f035e32
--- /dev/null
+++ b/docs/manuals/exporter/SUMMARY.md
@@ -0,0 +1,5 @@
+# Summary
+
+- [User guide](../../exporter/README.md)
+- [Development](../../development/README.md)
+- [Changelog](../../exporter/changelog.md)
diff --git a/docs/manuals/exporter/book.toml b/docs/manuals/exporter/book.toml
new file mode 100644
index 0000000..c2ec466
--- /dev/null
+++ b/docs/manuals/exporter/book.toml
@@ -0,0 +1,25 @@
+[book]
+title = "Document Exporter Manual"
+description = "Export presentations and PDF pages, and compress PDFs."
+language = "en"
+src = "src"
+
+[build]
+create-missing = false
+
+[output.html]
+site-url = "/manuals/exporter/"
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.playground]
+runnable = false
+
+# Consumed by scripts/manuals.py when staging the book and landing page.
+[manual]
+icon = "tools/assets/exporter/app-icon.png"
diff --git a/docs/manuals/mdbook-version b/docs/manuals/mdbook-version
new file mode 100644
index 0000000..7d85683
--- /dev/null
+++ b/docs/manuals/mdbook-version
@@ -0,0 +1 @@
+0.5.4
diff --git a/docs/manuals/media-player-classic/SUMMARY.md b/docs/manuals/media-player-classic/SUMMARY.md
new file mode 100644
index 0000000..a995c72
--- /dev/null
+++ b/docs/manuals/media-player-classic/SUMMARY.md
@@ -0,0 +1,6 @@
+# Summary
+
+- [Setup and workflows](../../../companion-modules/media-player-classic/README.md)
+- [Connection help and presets](../../../companion-modules/media-player-classic/companion/HELP.md)
+- [Upstream attribution](../../../companion-modules/media-player-classic/UPSTREAM.md)
+- [Changelog](../../media-player-classic/changelog.md)
diff --git a/docs/manuals/media-player-classic/book.toml b/docs/manuals/media-player-classic/book.toml
new file mode 100644
index 0000000..c99d81c
--- /dev/null
+++ b/docs/manuals/media-player-classic/book.toml
@@ -0,0 +1,25 @@
+[book]
+title = "MPC-HC Companion Manual"
+description = "Control Media Player Classic Home Cinema from Companion."
+language = "en"
+src = "src"
+
+[build]
+create-missing = false
+
+[output.html]
+site-url = "/manuals/media-player-classic/"
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.playground]
+runnable = false
+
+# Consumed by scripts/manuals.py when staging the book and landing page.
+[manual]
+icon = "companion-modules/media-player-classic/companion/assets/app-icon.png"
diff --git a/docs/manuals/midra-layout/SUMMARY.md b/docs/manuals/midra-layout/SUMMARY.md
new file mode 100644
index 0000000..045ff83
--- /dev/null
+++ b/docs/manuals/midra-layout/SUMMARY.md
@@ -0,0 +1,25 @@
+# Summary
+
+- [Introduction](../../midra-layout/README.md)
+- [User guide contents](../../midra-layout/guide/README.md)
+- [Layers and editing](../../midra-layout/guide/editing.md)
+- [Canvas and reference images](../../midra-layout/guide/canvas.md)
+- [Formats, crop and precision](../../midra-layout/guide/formats-and-crop.md)
+- [Import, export and project files](../../midra-layout/guide/files.md)
+- [Menus and preferences](../../midra-layout/guide/preferences.md)
+- [Midra connection and transfers](../../midra-layout/guide/device.md)
+- [Starter files for every format](../../templates/midra-layout/README.md)
+- [Resolution and cropping model](../../midra-layout/resolutions.md)
+- [Project file contract](../../interfaces/midra-layout.md)
+- [Geometry exchange contract](../../interfaces/midra-layout-exchange.md)
+- [Settings contract](../../interfaces/midra-layout-settings.md)
+- [Recovery contract](../../interfaces/midra-layout-recovery.md)
+- [Device import contract](../../interfaces/midra-device-import.md)
+- [Device send contract](../../interfaces/midra-device-send.md)
+- [Input preview contract](../../interfaces/midra-input-preview.md)
+- [Hardware verification](../../midra-layout/device-check.md)
+- [Viewport performance](../../midra-layout/guide/performance.md)
+- [Updating screenshots](../../midra-layout/images/README.md)
+- [Plan and limitations](../../midra-layout/plan.md)
+- [Development](../../development/README.md)
+- [Changelog](../../midra-layout/changelog.md)
diff --git a/docs/manuals/midra-layout/book.toml b/docs/manuals/midra-layout/book.toml
new file mode 100644
index 0000000..060d8eb
--- /dev/null
+++ b/docs/manuals/midra-layout/book.toml
@@ -0,0 +1,25 @@
+[book]
+title = "Midra Layout Manual"
+description = "Prepare screen layouts, exchange geometry and review device transfers."
+language = "en"
+src = "src"
+
+[build]
+create-missing = false
+
+[output.html]
+site-url = "/manuals/midra-layout/"
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.playground]
+runnable = false
+
+# Consumed by scripts/manuals.py when staging the book and landing page.
+[manual]
+icon = "crates/midra-layout/assets/app-icon.png"
diff --git a/docs/manuals/pptx-reporter/SUMMARY.md b/docs/manuals/pptx-reporter/SUMMARY.md
new file mode 100644
index 0000000..c970d98
--- /dev/null
+++ b/docs/manuals/pptx-reporter/SUMMARY.md
@@ -0,0 +1,8 @@
+# Summary
+
+- [Getting started](../../pptx-reporter/README.md)
+- [Visual walkthrough](../../pptx-reporter/visual-guide.md)
+- [Report formats and timing](../../pptx-reporter/report-formats.md)
+- [Builds and portable releases](../../development/releases.md)
+- [Development](../../development/README.md)
+- [Changelog](../../pptx-reporter/changelog.md)
diff --git a/docs/manuals/pptx-reporter/book.toml b/docs/manuals/pptx-reporter/book.toml
new file mode 100644
index 0000000..09bc120
--- /dev/null
+++ b/docs/manuals/pptx-reporter/book.toml
@@ -0,0 +1,25 @@
+[book]
+title = "PPTX Reporter Manual"
+description = "Inspect presentation videos and export timing reports."
+language = "en"
+src = "src"
+
+[build]
+create-missing = false
+
+[output.html]
+site-url = "/manuals/pptx-reporter/"
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.playground]
+runnable = false
+
+# Consumed by scripts/manuals.py when staging the book and landing page.
+[manual]
+icon = "crates/pptx-reporter/assets/app-icon.png"
diff --git a/docs/manuals/rundown-converter/SUMMARY.md b/docs/manuals/rundown-converter/SUMMARY.md
new file mode 100644
index 0000000..bc15182
--- /dev/null
+++ b/docs/manuals/rundown-converter/SUMMARY.md
@@ -0,0 +1,8 @@
+# Summary
+
+- [User guide](../../rundown-converter/README.md)
+- [Sample findings](../../rundown-converter/corpus.md)
+- [Plan and limitations](../../rundown-converter/plan.md)
+- [Builds and portable releases](../../development/releases.md)
+- [Development](../../development/README.md)
+- [Changelog](../../rundown-converter/changelog.md)
diff --git a/docs/manuals/rundown-converter/book.toml b/docs/manuals/rundown-converter/book.toml
new file mode 100644
index 0000000..a67d733
--- /dev/null
+++ b/docs/manuals/rundown-converter/book.toml
@@ -0,0 +1,25 @@
+[book]
+title = "Rundown Converter Manual"
+description = "Convert spreadsheet rundowns into validated show schedules."
+language = "en"
+src = "src"
+
+[build]
+create-missing = false
+
+[output.html]
+site-url = "/manuals/rundown-converter/"
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools"
+
+[output.html.fold]
+enable = true
+level = 1
+
+[output.html.playground]
+runnable = false
+
+# Consumed by scripts/manuals.py when staging the book and landing page.
+[manual]
+icon = "crates/rundown-converter/assets/app-icon.png"
diff --git a/docs/media-player-classic/changelog.md b/docs/media-player-classic/changelog.md
index 03a09f7..2f0bb71 100644
--- a/docs/media-player-classic/changelog.md
+++ b/docs/media-player-classic/changelog.md
@@ -4,6 +4,8 @@
## Unreleased
+- Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under `/mnt/books/manuals/`; staging, link validation and scoped publication have regression coverage.
+
- Use absolute Gitea main-branch URLs for repository file links in the root README; verify linked files exist.
## v0.6.0 — 2026-11-14
diff --git a/docs/midra-layout/changelog.md b/docs/midra-layout/changelog.md
index 09a503c..b17620c 100644
--- a/docs/midra-layout/changelog.md
+++ b/docs/midra-layout/changelog.md
@@ -4,6 +4,8 @@
## Unreleased
+- Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under `/mnt/books/manuals/`; staging, link validation and scoped publication have regression coverage.
+
- Replace the long overview with a visual quick start, move detailed workflows into topic guides, and centralize all nine starter-file formats in one catalog. Add real application screenshots with reproducible capture notes; retain the existing template files and validation contracts.
- Clarify shared Midra links: warn with other linked layer/folder names while allowing link edits; disable conflicting scoped sends and list all overlapping destinations. Preserve conflict-free folder/selection sends and remapping. Remove nested-folder/additional-codec backlog items and replace the extra-links proposal with this shared-destination workflow. Regression tests cover warning text, send blocking and scope isolation.
diff --git a/docs/pptx-reporter/changelog.md b/docs/pptx-reporter/changelog.md
index 32fdedc..0de2cc1 100644
--- a/docs/pptx-reporter/changelog.md
+++ b/docs/pptx-reporter/changelog.md
@@ -4,6 +4,8 @@
## Unreleased
+- Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under `/mnt/books/manuals/`; staging, link validation and scoped publication have regression coverage.
+
- Use absolute Gitea main-branch URLs for repository file links in the root README; verify linked files exist.
## v0.6.0 — 2026-11-14
diff --git a/docs/rundown-converter/changelog.md b/docs/rundown-converter/changelog.md
index 13dbd63..13fb9fe 100644
--- a/docs/rundown-converter/changelog.md
+++ b/docs/rundown-converter/changelog.md
@@ -4,6 +4,8 @@
## Unreleased
+- Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under `/mnt/books/manuals/`; staging, link validation and scoped publication have regression coverage.
+
- Use absolute Gitea main-branch URLs for repository file links in the root README; verify linked files exist.
## v0.6.0 — 2026-11-14
diff --git a/scripts/manuals.py b/scripts/manuals.py
new file mode 100644
index 0000000..15d02bc
--- /dev/null
+++ b/scripts/manuals.py
@@ -0,0 +1,282 @@
+#!/usr/bin/env python3
+"""Stage, build, check and publish the project's mdBook manuals (Python 3.11+)."""
+
+import argparse
+import html
+from html.parser import HTMLParser
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import tempfile
+import tomllib
+from urllib.parse import quote, unquote, urljoin, urlsplit
+
+ROOT = Path(__file__).resolve().parents[1]
+CONFIG = ROOT / "docs/manuals"
+OUTPUT = ROOT / "build/manuals"
+REPOSITORY = "https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/"
+DOWNLOADS = {".png", ".jpg", ".jpeg", ".svg", ".gif", ".json", ".csv", ".dxf",
+ ".html", ".drawio", ".pptx", ".fig", ".ai", ".txt"}
+LINK = re.compile(r"(?P\]\()(?P[^\s)]+)(?P\))"
+ r"|(?P(?:href|src)=[\"'])(?P[^\"']+)(?P[\"'])")
+
+
+def source_path(root, base, path):
+ """Resolve an existing source inside the repository, never following a symlink."""
+ target = Path(os.path.abspath(base / unquote(path)))
+ relative = target.relative_to(root)
+ if target.resolve() != target or not target.exists():
+ raise ValueError(f"Missing or symlinked manual source: {relative}")
+ return relative
+
+
+def chapter_path(path):
+ # Avoid mdBook's special handling of README.md when rewriting links.
+ return path.with_name("index.md") if path.name == "README.md" else path
+
+
+def books(root=ROOT):
+ result = []
+ for config in sorted((root / "docs/manuals").glob("*/book.toml")):
+ slug = config.parent.name
+ if not re.fullmatch(r"[a-z][a-z0-9-]+", slug):
+ raise ValueError(f"Invalid manual directory: {slug}")
+ data = tomllib.loads(config.read_text())
+ summary = config.with_name("SUMMARY.md").read_text()
+ chapters = {}
+
+ def entry(match):
+ path = source_path(root, config.parent, match[1])
+ if path.suffix != ".md" or not (root / path).is_file() or path in chapters:
+ raise ValueError(f"Invalid or duplicate chapter: {path}")
+ chapters[path] = chapter_path(path) if chapters else Path("index.md")
+ return f"]({chapters[path].as_posix()})"
+
+ staged_summary = re.sub(r"\]\(([^)]+)\)", entry, summary)
+ if not chapters:
+ raise ValueError(f"Empty manual: {slug}")
+ icon = source_path(root, root, data["manual"]["icon"])
+ result.append(dict(slug=slug, config=config, data=data, chapters=chapters,
+ summary=staged_summary, icon=icon))
+ if not result:
+ raise ValueError("No manual configurations found")
+ return result
+
+
+def stage_book(book, destination, root=ROOT):
+ src = destination / "src"
+ src.mkdir(parents=True)
+ # mdBook sees only its own configuration, not the staging metadata.
+ config = book["config"].read_text().split("[manual]", 1)[0]
+ (destination / "book.toml").write_text(config)
+ (src / "SUMMARY.md").write_text(book["summary"])
+
+ def copy_asset(path):
+ target = src / path
+ target.parent.mkdir(parents=True, exist_ok=True)
+ shutil.copyfile(root / path, target)
+
+ copy_asset(book["icon"])
+ for original, staged in book["chapters"].items():
+ def rewrite(url):
+ parsed = urlsplit(html.unescape(url))
+ if parsed.scheme or parsed.netloc or not parsed.path:
+ return url
+ path = source_path(root, (root / original).parent, parsed.path)
+ suffix = ("?" + parsed.query if parsed.query else "")
+ suffix += ("#" + parsed.fragment if parsed.fragment else "")
+ if path in book["chapters"]:
+ target = book["chapters"][path].with_suffix(".html")
+ elif (root / path).is_file() and path.suffix.lower() in DOWNLOADS:
+ copy_asset(path)
+ target = path
+ else:
+ # Out-of-book documentation/code stays a working repository link.
+ return REPOSITORY + quote(path.as_posix()) + suffix
+ return quote(os.path.relpath(target, staged.parent).replace(os.sep, "/")) + suffix
+
+ def replace(match):
+ if match["url"] is not None:
+ return match["start"] + rewrite(match["url"]) + match["end"]
+ return match["attr"] + rewrite(match["html"]) + match["quote"]
+
+ # Commands and examples must retain their literal paths and markup.
+ chunks = re.split(r"(^```[^\n]*\n.*?^```[^\n]*(?:\n|$))",
+ (root / original).read_text(), flags=re.M | re.S)
+ text = "".join(chunk if i % 2 else LINK.sub(replace, chunk)
+ for i, chunk in enumerate(chunks))
+ portal = os.path.relpath("../index.html", staged.parent).replace(os.sep, "/")
+ text = f'All manuals
\n\n' + text
+ target = src / staged
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_text(text)
+
+
+class Page(HTMLParser):
+ def __init__(self, text):
+ super().__init__(convert_charrefs=True)
+ self.links = []
+ self.ids = set()
+ self.base = None
+ self.feed(text)
+
+ def handle_starttag(self, tag, attrs):
+ attrs = dict(attrs)
+ if tag == "base":
+ self.base = attrs.get("href")
+ return
+ for key in ("id", "name"):
+ if key in attrs:
+ self.ids.add(attrs[key])
+ for key in ("href", "src"):
+ if key in attrs:
+ self.links.append(attrs[key])
+
+
+def validate_site(site, manuals):
+ """Check real rendered pages, including chapter fragments and downloads."""
+ site = site.absolute()
+ required = [site / "index.html"] + [site / b["slug"] / "index.html" for b in manuals]
+ if any(not path.is_file() for path in required):
+ raise ValueError("Manual output is incomplete: missing landing page or book index")
+ if any(path.is_symlink() for path in [site, *site.rglob("*")]):
+ raise ValueError("Manual output must not contain symlinks")
+ pages = {p: Page(p.read_text()) for p in site.rglob("*.html")}
+ count = 0
+ for file, page in pages.items():
+ for url in page.links:
+ location = "/manuals/" + file.relative_to(site).as_posix()
+ parsed = urlsplit(urljoin(page.base or location, url))
+ if parsed.scheme or parsed.netloc:
+ continue
+ path = unquote(parsed.path)
+ if not path.startswith("/manuals/"):
+ raise ValueError(f"Link escapes manual site: {file}: {url}")
+ dest = Path(os.path.abspath(site / path.removeprefix("/manuals/")))
+ if not dest.is_relative_to(site):
+ raise ValueError(f"Link escapes manual site: {file}: {url}")
+ if dest.is_dir():
+ dest /= "index.html"
+ if not dest.exists():
+ raise ValueError(f"Broken manual link: {file}: {url}")
+ fragment = unquote(parsed.fragment)
+ if fragment and dest in pages and fragment not in pages[dest].ids:
+ raise ValueError(f"Broken manual anchor: {file}: {url}")
+ count += 1
+ print(f"Validated {len(pages)} HTML pages and {count} local links/assets.", flush=True)
+
+
+def landing_page(manuals):
+ cards = []
+ for book in manuals:
+ info = book["data"]["book"]
+ cards.append(f''
+ f'
'
+ f'{html.escape(info["title"])}
'
+ f'{html.escape(info["description"])}
')
+ return '''
+
+beffroi-tools manualsbeffroi-tools manuals
+Guides and reference for local document, show and media workflows.
+''' + "\n".join(cards) + "\n\n"
+
+
+def build(mdbook, root=ROOT, output=OUTPUT):
+ manuals = books(root)
+ version = (root / "docs/manuals/mdbook-version").read_text().strip()
+ actual = subprocess.check_output([mdbook, "--version"], text=True).strip()
+ if actual != f"mdbook v{version}":
+ raise ValueError(f"Expected mdbook v{version}, got {actual}")
+ if output.is_symlink():
+ raise ValueError("Refusing symlinked manual build directory")
+ if output.exists():
+ shutil.rmtree(output)
+ output.parent.mkdir(parents=True, exist_ok=True)
+ with tempfile.TemporaryDirectory(prefix=".manuals-", dir=output.parent) as temp:
+ work = Path(temp)
+ site = work / "site/manuals"
+ site.mkdir(parents=True)
+ for book in manuals:
+ source = work / "sources" / book["slug"]
+ stage_book(book, source, root)
+ subprocess.run([mdbook, "build", str(source), "--dest-dir", str(site / book["slug"])],
+ check=True)
+ # mdBook's 404 otherwise sends its own heading links to index.html.
+ not_found = site / book["slug"] / "404.html"
+ not_found.write_text(not_found.read_text().replace('href="#', 'href="404.html#'))
+ (site / "index.html").write_text(landing_page(manuals))
+ validate_site(site, manuals)
+ work.rename(output)
+ print(f"Manuals ready: {output / 'site/manuals/index.html'}", flush=True)
+
+
+def safe_destination(path):
+ if not path.is_absolute():
+ raise ValueError("Publication destination must be absolute")
+ for component in [*reversed(path.parents), path]:
+ if component.is_symlink() or (component.exists() and not component.is_dir()):
+ raise ValueError(f"Unsafe publication directory: {component}")
+
+
+def publish(site, destination, manuals, environment=None):
+ environment = os.environ if environment is None else environment
+ if environment.get("BRANCH_NAME") != "main" or environment.get("CHANGE_ID"):
+ raise ValueError("Only non-PR main builds may publish manuals")
+ safe_destination(destination)
+ # A missing mount is an infrastructure error, not a reason to create /mnt/books.
+ if not destination.parent.is_dir():
+ raise ValueError(f"Publication parent/mount is missing: {destination.parent}")
+ for book in manuals:
+ safe_destination(destination / book["slug"])
+ if (destination / "index.html").is_symlink() or (destination / "index.html").is_dir():
+ raise ValueError("Unsafe manual landing-page destination")
+ validate_site(site, manuals)
+ destination.mkdir(exist_ok=True)
+ # Delete stale pages only within each explicitly owned book, never the shared root.
+ for book in manuals:
+ target = destination / book["slug"]
+ target.mkdir(exist_ok=True)
+ subprocess.run(["rsync", "-a", "--delete", str(site / book["slug"]) + "/",
+ str(target) + "/"], check=True)
+ with tempfile.NamedTemporaryFile(prefix=".manual-index-", dir=destination, delete=False) as temp:
+ temporary = Path(temp.name)
+ try:
+ shutil.copyfile(site / "index.html", temporary)
+ temporary.chmod(0o644)
+ temporary.replace(destination / "index.html")
+ finally:
+ temporary.unlink(missing_ok=True)
+ print(f"Published {len(manuals)} manuals to {destination}", flush=True)
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ commands = parser.add_subparsers(dest="command", required=True)
+ builder = commands.add_parser("build")
+ builder.add_argument("--mdbook", default="mdbook")
+ commands.add_parser("check")
+ publisher = commands.add_parser("publish")
+ publisher.add_argument("--destination", type=Path, default=Path("/mnt/books/manuals"))
+ args = parser.parse_args()
+ try:
+ if args.command == "build":
+ build(args.mdbook)
+ elif args.command == "check":
+ validate_site(OUTPUT / "site/manuals", books())
+ else:
+ publish(OUTPUT / "site/manuals", args.destination, books())
+ except (ValueError, OSError, subprocess.CalledProcessError) as error:
+ parser.exit(1, f"Manuals: {error}\n")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tests/test_manuals.py b/tests/test_manuals.py
new file mode 100644
index 0000000..a32afa7
--- /dev/null
+++ b/tests/test_manuals.py
@@ -0,0 +1,187 @@
+import importlib.util
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+import unittest
+from unittest.mock import patch
+
+ROOT = Path(__file__).resolve().parents[1]
+SPEC = importlib.util.spec_from_file_location("manuals", ROOT / "scripts/manuals.py")
+manuals = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(manuals)
+
+
+class ManualTests(unittest.TestCase):
+ def setUp(self):
+ self.temp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.temp.cleanup)
+ self.root = Path(self.temp.name)
+
+ def write(self, name, text):
+ path = self.root / name
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text)
+ return path
+
+ def book(self):
+ self.write("docs/manuals/example/book.toml", '''[book]
+title = "Example"
+description = "Example manual"
+src = "src"
+[manual]
+icon = "docs/icon.png"
+''')
+ self.write("docs/manuals/example/SUMMARY.md", "# Summary\n\n"
+ "- [Intro](../../tool/README.md)\n- [Details](../../tool/detail.md)\n")
+ self.write("docs/icon.png", "image fixture")
+ self.write("docs/tool/README.md", '# Intro\n\n[Detail](detail.md#values)\n'
+ '[Other](../other.md)\n\n'
+ '
\n[Data](../sample.json)\n'
+ '```md\n[Literal](missing.md)\n```\n')
+ self.write("docs/tool/detail.md", "# Details\n\n## Values\n\n[Home](README.md)\n")
+ self.write("docs/other.md", "# Other")
+ self.write("docs/sample.json", '{"value": 42}')
+ return manuals.books(self.root)[0]
+
+ def test_stage_rebases_chapters_assets_and_repository_links_without_copying_prose(self):
+ book = self.book()
+ before = (self.root / "docs/tool/README.md").read_bytes()
+ stage = self.root / "stage"
+ manuals.stage_book(book, stage, self.root)
+ intro = (stage / "src/index.md").read_text()
+ self.assertIn("](docs/tool/detail.html#values)", intro)
+ self.assertIn(manuals.REPOSITORY + "docs/other.md", intro)
+ self.assertIn('src="docs/icon.png"', intro)
+ self.assertIn("[Data](docs/sample.json)", intro)
+ self.assertIn("[Literal](missing.md)", intro)
+ self.assertIn("[Home](../../index.html)", (stage / "src/docs/tool/detail.md").read_text())
+ self.assertEqual((stage / "src/docs/sample.json").read_bytes(),
+ (self.root / "docs/sample.json").read_bytes())
+ self.assertFalse((stage / "src/docs/other.md").exists())
+ self.assertNotIn("[manual]", (stage / "book.toml").read_text())
+ self.assertEqual((self.root / "docs/tool/README.md").read_bytes(), before)
+
+ def test_missing_duplicate_outside_and_symlinked_sources_are_rejected(self):
+ self.book()
+ summary = self.root / "docs/manuals/example/SUMMARY.md"
+ for links in ("../../missing.md", "../../../../outside.md"):
+ summary.write_text(f"- [Bad]({links})\n")
+ with self.assertRaises(ValueError):
+ manuals.books(self.root)
+ summary.write_text("- [One](../../tool/README.md)\n- [Again](../../tool/README.md)\n")
+ with self.assertRaises(ValueError):
+ manuals.books(self.root)
+ summary.write_text("- [Link](../../linked.md)\n")
+ (self.root / "docs/linked.md").symlink_to(self.root / "docs/tool/README.md")
+ with self.assertRaises(ValueError):
+ manuals.books(self.root)
+
+ def site(self):
+ site = self.root / "site"
+ self.write("site/index.html", 'Example')
+ self.write("site/example/index.html", 'Intro
'
+ 'ManualsIntro'
+ 'File')
+ self.write("site/example/downloads/file.json", '{"value": 42}')
+ return site, [{"slug": "example"}]
+
+ def test_rendered_validation_checks_fragments_downloads_and_subpath_404_base(self):
+ site, books = self.site()
+ page = self.write("site/example/404.html", ''
+ 'Missing
Missing')
+ manuals.validate_site(site, books)
+ for url in ("index.html#missing", "absent.json", "../../outside.html"):
+ page.write_text(f'Invalid')
+ with self.assertRaises(ValueError):
+ manuals.validate_site(site, books)
+ page.unlink()
+ (site / "example/downloads/file.json").unlink()
+ with self.assertRaises(ValueError):
+ manuals.validate_site(site, books)
+
+ @unittest.skipUnless(shutil.which("rsync"), "rsync is required for publication integration")
+ def test_publish_replaces_only_owned_manual_and_landing_page(self):
+ site, books = self.site()
+ destination = self.root / "public/manuals"
+ self.write("public/manuals/example/stale.html", "stale")
+ sibling = self.write("public/manuals/unrelated-book/keep.html", "keep")
+ root_file = self.write("public/manuals/keep.txt", "keep")
+ self.write("public/manuals/index.html", "old")
+ manuals.publish(site, destination, books, {"BRANCH_NAME": "main"})
+ self.assertFalse((destination / "example/stale.html").exists())
+ self.assertEqual((destination / "index.html").read_bytes(), (site / "index.html").read_bytes())
+ self.assertEqual((destination / "example/downloads/file.json").read_bytes(),
+ (site / "example/downloads/file.json").read_bytes())
+ self.assertEqual(sibling.read_text(), "keep")
+ self.assertEqual(root_file.read_text(), "keep")
+
+ def test_publish_rejects_non_main_pr_incomplete_output_and_missing_mount(self):
+ site, books = self.site()
+ destination = self.root / "manuals"
+ for env in ({}, {"BRANCH_NAME": "feature"}, {"BRANCH_NAME": "main", "CHANGE_ID": "3"}):
+ with self.assertRaises(ValueError):
+ manuals.publish(site, destination, books, env)
+ with self.assertRaises(ValueError):
+ manuals.publish(site, destination, books + [{"slug": "absent"}], {"BRANCH_NAME": "main"})
+ self.assertFalse(destination.exists())
+ with self.assertRaises(ValueError):
+ manuals.publish(site, self.root / "missing-mount/manuals", books, {"BRANCH_NAME": "main"})
+ self.assertFalse((self.root / "missing-mount").exists())
+
+ def test_publish_rejects_symlinked_output_and_destination_before_writing(self):
+ site, books = self.site()
+ destination = self.root / "manuals"
+ destination.mkdir()
+ outside = self.root / "outside"
+ outside.mkdir()
+ (destination / "example").symlink_to(outside, target_is_directory=True)
+ with self.assertRaises(ValueError):
+ manuals.publish(site, destination, books, {"BRANCH_NAME": "main"})
+ self.assertEqual(list(outside.iterdir()), [])
+ (destination / "example").unlink()
+ (site / "escape").symlink_to(outside, target_is_directory=True)
+ with self.assertRaises(ValueError):
+ manuals.publish(site, destination, books, {"BRANCH_NAME": "main"})
+ self.assertEqual(list(destination.iterdir()), [])
+
+ def test_all_six_manifests_stage_real_assets_and_every_midra_starter(self):
+ books = manuals.books()
+ self.assertEqual({book["slug"] for book in books},
+ {"ascii-names", "exporter", "media-player-classic", "midra-layout",
+ "pptx-reporter", "rundown-converter"})
+ for book in books:
+ manuals.stage_book(book, self.root / book["slug"])
+ assets = ROOT / "docs/templates/midra-layout"
+ for original in assets.iterdir():
+ if original.suffix == ".md":
+ continue
+ copied = self.root / "midra-layout/src/docs/templates/midra-layout" / original.name
+ self.assertEqual(original.read_bytes(), copied.read_bytes())
+
+ def test_failed_build_does_not_leave_a_publishable_partial_or_old_site(self):
+ self.book()
+ self.write("docs/manuals/mdbook-version", "0.5.4\n")
+ self.write("build/manuals/site/manuals/index.html", "old")
+ tool = self.write("fake-mdbook", '#!/bin/sh\n'
+ 'if [ "$1" = "--version" ]; then echo "mdbook v0.5.4"; else exit 7; fi\n')
+ tool.chmod(0o755)
+ output = self.root / "build/manuals"
+ with self.assertRaises(subprocess.CalledProcessError):
+ manuals.build(str(tool), self.root, output)
+ self.assertFalse(output.exists())
+ self.assertEqual(list(output.parent.iterdir()), [])
+
+ def test_rsync_failure_keeps_previous_landing_page(self):
+ site, books = self.site()
+ destination = self.root / "manuals"
+ landing = self.write("manuals/index.html", "old landing")
+ with patch.object(manuals.subprocess, "run",
+ side_effect=subprocess.CalledProcessError(23, "rsync")):
+ with self.assertRaises(subprocess.CalledProcessError):
+ manuals.publish(site, destination, books, {"BRANCH_NAME": "main"})
+ self.assertEqual(landing.read_text(), "old landing")
+
+
+if __name__ == "__main__":
+ unittest.main()