build: add directory-oriented make workflows

docs/src/development.md

@@ -1,27 +1,46 @@
 # Development and verification
 
+## Command layout
+
+Each component owns its Makefile: the Cargo workspace, all-board workflows,
+individual boards, tools, and documentation each define commands in their own
+directory. The root Makefile contains repository-wide workflows and routes a
+directory path to that directory's Makefile.
+
+The standard `--` ends Make's own options. Every following argument uses the
+selected application's native command line. For example,
+`make firmware -- test --workspace --locked --offline` runs `cargo test
+--workspace --locked --offline` from `firmware`, while
+`make firmware/tools/sitl -- ready` runs `kaptan-sim ready`. Board paths are
+the complete build-and-package command, so they need no invented operation
+name.
+
 ## Fast host checks
 
 ```sh
-cd firmware
-cargo test --workspace --offline
-cargo clippy --workspace --all-targets --offline --exclude kaptan-geprc-f722-v2 --exclude kaptan-kakute-f7-mini-v3 -- -D warnings
-cargo clippy -p platform-stm32f7 --all-targets --offline -- -D warnings
-cargo fmt --all --check
-git diff --check
+make firmware -- fmt --all --check
+make firmware -- test --workspace --locked --offline
+make firmware -- clippy --workspace --all-targets \
+  --exclude kaptan-geprc-f722-v2 \
+  --exclude kaptan-kakute-f7-mini-v3 --locked --offline -- -D warnings
 ```
 
 ## Target checks
 
 ```sh
-cd firmware
-cargo clippy -p kaptan-geprc-f722-v2 -p kaptan-kakute-f7-mini-v3 \
-  --target thumbv7em-none-eabihf --offline -- -D warnings
-cargo build --release --locked \
+make firmware/boards
+make firmware -- clippy \
   -p kaptan-geprc-f722-v2 -p kaptan-kakute-f7-mini-v3 \
-  --target thumbv7em-none-eabihf --offline
+  --target thumbv7em-none-eabihf --locked --offline -- -D warnings
 ```
 
+`make firmware docs` builds Rust API documentation with warnings denied.
+`make docs` checks and builds the separate mdBook project. `make pre-commit`
+runs both documentation checks along with repository formatting, host and
+embedded Clippy, Rust and script tests, and SITL structure tests. `make check`
+adds a whitespace check. `make build` builds and packages release firmware and
+builds the mdBook project.
+
 ## Strict core coverage
 
 ```sh
@@ -38,10 +57,10 @@ the gate.
 ## Simulation acceptance
 
 ```sh
-cd firmware
-python3 tools/sitl/world-structure-test.py
-python3 -m unittest tools/sitl/test_kaptan_sim.py
-tools/sitl/e2e-smoke.sh
+cd firmware/tools/sitl
+python3 world-structure-test.py
+python3 -m unittest test_kaptan_sim.py
+./e2e-smoke.sh
 ```
 
 The Docker smoke is intentionally separate from host unit tests because it