Building the documentation

This book is built with mdBook, and the API reference with rustdoc. The two are combined into one site, with the rustdoc output under api/.

One command

$ nix develop -c scripts/build-docs.sh

The script does five things:

1. Builds the xianyun binary.
2. Regenerates book/src/cli/reference.md from the binary’s --help output.
3. Runs mdbook build book.
4. Checks the book’s links with mdbook-linkcheck2.
5. Runs cargo doc --workspace --no-deps with rustdoc warnings denied, and copies the result to book/build/html/api/.

When CI_PAGES_URL is set, the script passes its path to mdBook as the site URL, so the 404 page works under a project path such as /xianyun/.

Open book/build/html/index.html in a browser. For a live preview of the prose only, run mdbook serve book; the API links won’t resolve until step 4 has run once.

Nix

$ nix build .#docs
$ xdg-open result/index.html

The same site, built in the Nix sandbox. It uses the committed command reference rather than regenerating it.

Publishing

GitLab CI builds and publishes the site; see .gitlab-ci.yml.

• The docs job runs scripts/build-docs.sh on merge requests and on the default branch, and keeps book/build/html as an artifact. A broken link, a stale command reference, or a rustdoc warning fails the merge request. A reviewer can download the artifact to read the result.
• The pages job runs on the default branch only. It moves that artifact to public/, which GitLab Pages serves. It doesn’t rebuild anything, so what’s published is exactly what was checked.

The site’s address is https://jhebden.gitlab.io/xianyun/. Enable Pages for the project under Deploy > Pages if it isn’t already, and check that access control matches what you want: a project can be public while its Pages site is limited to members.

I verified the site serves correctly from a sub-path by building with CI_PAGES_URL set and requesting pages under /xianyun/ from a local server. The pipeline itself hasn’t run on GitLab.

Checks

$ scripts/gen-cli-reference.sh target/debug/xianyun --check
$ nix develop -c rumdl check
$ scripts/validate-examples.sh

The first fails when the committed command reference is out of date. The second runs the repository’s Markdown linter, including its link and anchor checks. The third validates every example configuration with the built binary.

Writing

Pages are plain Markdown. Write in sentence case, use contractions, and keep commands in console blocks and file contents in blocks tagged with their language. Name the xianyun binary, not the Go one. Don’t quote a number you haven’t measured; the project’s habit is to say how a claim was checked. book/STYLE_GUIDE.md has the details, including the accessibility and theme decisions.