The Problem

Teams that need a structured, language‑by‑language onboarding path to Rust often cobble together scattered articles, videos, and official docs. The result is duplicated effort, inconsistent depth, and gaps in best‑practice coverage.

What This Does

The repository ships seven self‑contained training books (e.g., c-cpp-book/, csharp-book/, async-book/) written in Markdown and rendered with mdBook. The single Rust binary in xtask/src/main.rs implements a custom xtask CLI that orchestrates book generation, validation, and optional Docker image creation. Core files:

  • Cargo.toml – defines the workspace and pulls in mdbook and clap.
  • xtask/Cargo.toml – builds the xtask binary.
  • docker/Dockerfile – packages the generated site into a minimal image.

Running the xtask CLI produces a static site that GitHub Pages can serve, while the Docker workflow (.github/workflows/docker.yml) builds and pushes the image automatically.

How It Is Wired

Entry point – xtask/src/main.rs. The main function creates a clap::App (see src/main.rs line 12) with subcommands build, serve, and docker.

  • build → calls mdbook::MDBook::load on each */book.toml (e.g., async-book/book.toml) and invokes mdbook::build::build. This reads every src/*.md file and writes HTML to target/site/<book>/.
  • serve → spawns mdbook::serve::serve on the same output directory, exposing a local HTTP server (no external networking beyond localhost).
  • docker → after a successful build, the command runs docker build -f docker/Dockerfile . (see .github/workflows/docker.yml for the exact CLI). The Dockerfile copies target/site into /usr/share/nginx/html, producing a ready‑to‑deploy image.

The workspace Cargo.toml declares the xtask member and sets the workspace root, so cargo run --bin xtask -- <subcommand> resolves the binary without extra path handling. No other runtime side‑effects (database, external services) exist; the code’s blast radius is limited to the filesystem under target/ and the Docker daemon when invoked.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/RustTraining
cd RustTraining

# Build the helper binary
cargo build --workspace   # builds xtask and its dependencies

# Generate all books locally
cargo run -p xtask -- build

# Preview a single book (example: async)
cargo run -p xtask -- serve --book async-book

# Build the Docker image (requires Docker daemon)
cargo run -p xtask -- docker

Configuration: No external config files are required; the book.toml files inside each book directory drive the mdBook build. The Docker workflow expects a Docker daemon on the host.

Real‑World Use

A corporate learning portal can pull the generated target/site directory into its static‑site pipeline, or deploy the Docker image (docker pull <repo>/rusttraining:latest) behind an internal reverse proxy. The same xtask binary can be added to CI to verify that all Markdown renders without errors before a release.

Code Health & Issues

  • Low – No unit tests for xtask logic – only 6 test files exist, none target the CLI (see xtask/tests/).
  • Low – Missing CI lint for Markdown – GitHub Actions only build Docker; a lint step (e.g., mdbook test) would catch broken links early.
  • Info – License files present – LICENSE (MIT) and LICENSE-DOCS (CC‑BY‑4.0) are correctly included.

No structural red flags detected; workspace layout, lockfiles, and CI artifacts exist as expected.

The Bottom Line

The repo delivers a ready‑to‑use, multi‑track Rust curriculum with a thin Rust‑based build tool that automates static site generation and Docker packaging. It is well‑organized but lacks automated tests for the build tool itself, so teams extending the curriculum should add coverage early. Ideal for organizations that want a self‑hosted, version‑controlled Rust learning portal.