107 lines
6.0 KiB
Markdown
107 lines
6.0 KiB
Markdown
# Project manuals
|
|
|
|
[Documentation](../README.md) · [CI and coverage](../development/ci.md)
|
|
|
|
**[Read all manuals online →](https://books.dandaedre.com/manuals/)**
|
|
|
|
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](https://books.dandaedre.com/manuals/ascii-names/) | [Chapter list](ascii-names/SUMMARY.md) |
|
|
| Document Exporter | [Full manual](https://books.dandaedre.com/manuals/exporter/) | [Chapter list](exporter/SUMMARY.md) |
|
|
| MPC-HC Companion | [Full manual](https://books.dandaedre.com/manuals/media-player-classic/) | [Chapter list](media-player-classic/SUMMARY.md) |
|
|
| Canvas Pilot | [Full manual](https://books.dandaedre.com/manuals/canvas-pilot/) | [Chapter list](canvas-pilot/SUMMARY.md) |
|
|
| PPTX Reporter | [Full manual](https://books.dandaedre.com/manuals/pptx-reporter/) | [Chapter list](pptx-reporter/SUMMARY.md) |
|
|
| Rundown Converter | [Full manual](https://books.dandaedre.com/manuals/rundown-converter/) | [Chapter list](rundown-converter/SUMMARY.md) |
|
|
|
|
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](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/<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](../../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.
|