beffroi-tools/docs/manuals
Dandaedre a1df81ff78 Separate Midra manual quick start and advanced guides 2026-11-14 22:29:16 +01:00
..
ascii-names Build and publish project mdBook manuals through Jenkins 2026-11-14 20:44:11 +01:00
exporter Build and publish project mdBook manuals through Jenkins 2026-11-14 20:44:11 +01:00
media-player-classic Build and publish project mdBook manuals through Jenkins 2026-11-14 20:44:11 +01:00
midra-layout Separate Midra manual quick start and advanced guides 2026-11-14 22:29:16 +01:00
pptx-reporter Build and publish project mdBook manuals through Jenkins 2026-11-14 20:44:11 +01:00
rundown-converter Build and publish project mdBook manuals through Jenkins 2026-11-14 20:44:11 +01:00
README.md Link published mdBook manuals from project READMEs 2026-11-14 22:23:34 +01:00
mdbook-version Build and publish project mdBook manuals through Jenkins 2026-11-14 20:44:11 +01:00

README.md

Project manuals

Documentation · CI and coverage

Read all manuals online →

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 Read online Chapter sources
ASCII Names Full manual Chapter list
Document Exporter Full manual Chapter list
MPC-HC Companion Full manual Chapter list
Midra Layout Full manual Chapter list
PPTX Reporter Full manual Chapter list
Rundown Converter Full manual Chapter list

The published site is served from /mnt/books/manuals/ at https://books.dandaedre.com/manuals/. Each book.toml declares a relative site-url for its 404 page, so local previews also work.

Build and preview

Requires Python 3.11+, Rust/Cargo for installation, and mdBook 0.5.4, pinned in mdbook-version. No mdBook plugins are required. From the repository root:

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/<project>/; 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 follows the supplied Deathwatch mdBook pipeline: 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.

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