Skip to content

Building the documentation

The documentation has three supported workflows: local preview, strict HTML validation, and combined PDF export.

Reproducible toolchain

The docs dependencies are pinned in tools/docs/uv.lock. Commands use uv run --project tools/docs --locked so local and CI builds resolve the same MkDocs, Material, and PDF-renderer versions.

Do not replace the repository commands with an unpinned global MkDocs installation when validating a release.

Local preview

uv run --project tools/docs --locked mkdocs serve

The watch configuration reloads changes in docs/, the package-local documentation directories, and the Docker tutorial sources.

Strict HTML and search-index build

./scripts/build-docs.sh

Output:

site/
├── index.html
├── search/search_index.json
└── ...

The build fails for invalid navigation, broken internal links, unresolved snippets, or unrecognized links.

Combined PDF build

./scripts/build-docs-pdf.sh

Output:

site/assets/call-baxter-documentation.pdf

The script performs two passes:

  1. a strict HTML/link/search-index validation pass;
  2. a PDF-enabled rendering pass followed by PDF header, size, and EOF integrity checks.

The passes are intentionally separate. WeasyPrint reports unsupported browser-only Material CSS rules while still producing a valid print document; enabling MkDocs strict mode during that rendering pass would promote those harmless renderer diagnostics to build failures.

PDF styling

Print-specific rules live in:

tools/docs/pdf/styles.scss

The stylesheet defines A4 output, printable margins, local system fonts, wrapped code blocks, repeated table headers, and page-break avoidance for tables, figures, admonitions, and code blocks.

CI artifacts

Both documentation workflows generate the PDF:

  • .github/workflows/ci.yml uploads call-baxter-documentation-pdf as a workflow artifact;
  • .github/workflows/docs.yml uploads the same standalone artifact and includes it in the GitHub Pages site.

Workspace bridge commands

docs-site   strict HTML/search build
docs-pdf    strict HTML validation plus PDF export
docs-serve  local live preview