6.3 KiB
Project manuals
Documentation · CI and coverage
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 five owned manuals and an external link to Canvas Pilot.
| Manual | Read online | Chapter sources |
|---|---|---|
| ASCII Names | Full manual | Chapter list |
| Document Exporter | Full manual | Chapter list |
| MPC-HC Companion | Full manual | Chapter list |
| Canvas Pilot | 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.mdlists canonical Markdown chapters with paths relative to itself. Add or reorder entries here. The linked files remain readable in the repository.book.tomlconfigures 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 builddirectly in these configuration directories: it creates thesrctree 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. Canvas Pilot's starter catalog is built and published from its own repository.
- Fenced code blocks retain their literal command examples. Keep documentation
links in ordinary Markdown or quoted HTML
href/srcattributes; 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 five owned 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 five 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.
Canvas Pilot is independently built and published by its own repository. This
publisher leaves canvas-pilot/ intact and owns the shared landing page. The Canvas
Pilot publisher must never replace that page or any of these five books.