Generating Documentation

This manual uses mdBook, the standard Rust documentation tool. The source files are individual Markdown chapters in doc/book/src/, with SUMMARY.md defining the table of contents.

Building the Website

Works on Linux, macOS, and Windows — anywhere Rust is installed:

# One-time install
cargo install mdbook

# Build the website
cd doc
mdbook build

# Or serve locally with live reload (opens browser automatically)
mdbook serve --port 3000 --open

Output: doc/dist/site/index.html

Generating a PDF

Option A: Print from browser (easiest, any platform)

The website includes a print-optimized single page at dist/site/print.html that contains the entire manual. Open it in any browser and use File > Print > Save as PDF.

cd doc
mdbook build
# Open dist/site/print.html in your browser, then File > Print > Save as PDF

Option B: mdbook-pdf (automated, requires Chrome/Chromium)

The mdbook-pdf backend generates a PDF automatically using headless Chrome:

# One-time install
cargo install mdbook-pdf

# In doc/book.toml, uncomment the [output.pdf] line, then:
cd doc
mdbook build

Output: doc/dist/site/output.pdf

Option C: pandoc (best typographic quality, Linux)

For publication-quality PDF with LaTeX typesetting:

# Install dependencies (Ubuntu/Debian)
sudo apt install pandoc texlive-latex-recommended texlive-fonts-extra texlive-latex-extra lmodern

# Generate PDF
cd doc
./build-docs.sh pdf

Output: doc/dist/pdf/autocore_user_manual.pdf

Editing the Manual

Each chapter is a separate Markdown file:

doc/book/src/
├── SUMMARY.md                              ← Table of contents
├── introduction.md                         ← Front page
├── ch01-welcome-to-autocore.md
├── ch02-generating-documentation.md        ← This chapter
├── ch03-setting-up-your-development-machine.md
├── ch09-hardware-integration-ni-daqmx.md
├── ch17-appendix-b-function-block-reference.md
└── ...

To add a new chapter:

1. Create a new .md file in doc/book/src/
2. Add a - [Title](filename.md) entry to SUMMARY.md
3. Run mdbook serve to preview

To reorder chapters, edit SUMMARY.md. The file names don’t affect ordering — only the order in SUMMARY.md matters.

Rust API Documentation

For API-level documentation of autocore-std (function blocks, ControlProgram trait, CommandClient, etc.):

cd autocore-std
cargo doc --open