Documentation site and CI workflows
An mdBook under docs/book: a user guide (getting started, UI tour, sketching, features, parameters, components and joints, sheet metal, plastic, files, shortcuts, MCP) and a developer guide (CONTRIBUTING, architecture, command engine, kernel boundary, persistent naming, test harnesses, and the existing docs/*.md pages). `cargo xtask book` generates the command reference from `solvecraft-cli commands` and renders the screenshots with `solvecraft-cli snapshot`, then runs mdbook. .github/workflows/pages.yml publishes the book at /solvecraft/ and the web app at /solvecraft/app/ (skipped while the repository is private). .github/workflows/ci.yml runs `cargo xtask ci` on pull requests. README and Help → Documentation link to the book. Fixes #28 Fixes #8 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
2c3fec087e
commit
0d7e456bc1
35 files changed
+792
-5
No files matched your search
@@ -0,0 +1,37 @@
|
||||
# The kernel boundary and truck
|
||||
|
||||
`crates/kernel` is SolveCraft's B-rep kernel. It wraps
|
||||
[truck](https://github.com/ricosjp/truck) (Apache-2.0) for topology, NURBS geometry, booleans,
|
||||
tessellation and STEP parsing, and it is the only crate allowed to use truck. Callers get
|
||||
SolveCraft types (`Body`, face and edge indices, meshes, measures) and a
|
||||
`KernelError` instead of truck types and panics.
|
||||
|
||||
## `guard`
|
||||
|
||||
truck can panic on geometry it doesn't handle. Every call into it goes through
|
||||
`solvecraft_kernel::guard`, which catches the panic and turns it into
|
||||
`KernelError::Internal`, leaving the model unchanged:
|
||||
|
||||
```rust
|
||||
pub fn guard<T>(what: &str, f: impl FnOnce() -> Result<T>) -> Result<T>
|
||||
```
|
||||
|
||||
A failing feature shows an error on the timeline; it never takes the app down.
|
||||
|
||||
## What is our own
|
||||
|
||||
truck has no fillets, chamfers, shells or face edits, so these are SolveCraft code in the
|
||||
kernel: constant, chord and variable-radius fillets with corner blends, chamfers, shell and
|
||||
offset, Delete Face, Split Face, Replace Face, sewing, STEP and IGES reading and writing beyond
|
||||
truck's parser, and face provenance (which input face each output face came from, for
|
||||
[persistent naming](naming.md)).
|
||||
|
||||
## Vendored truck crates
|
||||
|
||||
Patched copies of `truck-shapeops`, `truck-stepio` and `truck-meshalgo` live in `vendor/`,
|
||||
wired in with `[patch.crates-io]`. The patches fix robustness bugs found by our tests and the
|
||||
STEP corpus. `vendor/` is excluded from our fmt and clippy rules, and each patch should go
|
||||
upstream when it can.
|
||||
|
||||
Some truck assertions only run in debug builds and can fail on valid geometry, so tests and CI
|
||||
run with `--release`.
|
||||
Reference in new issue
Block a user