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 manuals

beffroi-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![Icon](../icon.png)\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()