docs: add mdBook guide site and Pages deploy workflow (#15)
* docs(book): add mdBook guide scaffold and chapters * fix(book): correct mdBook summary external link handling * ci(docs): add mdBook build and pages deploy workflow * docs(readme): document mdBook guide site and paths * chore(gitignore): ignore mdbook output directory * ci(docs): split mdbook build and deploy permissions
This commit is contained in:
Milind Sharma
GitHub
parent
066ddea096
commit
0b078379bd
|
|
@ -0,0 +1,56 @@
|
|||
name: docs-mdbook
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
pull_request:
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: mdbook-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup mdBook
|
||||
uses: peaceiris/actions-mdbook@v2
|
||||
with:
|
||||
mdbook-version: latest
|
||||
|
||||
- name: Build book
|
||||
run: mdbook build docs/book
|
||||
|
||||
- name: Upload book artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: mdbook-site
|
||||
path: ./book
|
||||
if-no-files-found: error
|
||||
|
||||
deploy:
|
||||
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
|
||||
needs: build
|
||||
permissions:
|
||||
contents: write
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Download book artifact
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: mdbook-site
|
||||
path: ./book
|
||||
|
||||
- name: Deploy to GitHub Pages
|
||||
uses: peaceiris/actions-gh-pages@v4
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./book
|
||||
|
|
@ -23,3 +23,4 @@ target
|
|||
prompts/
|
||||
|
||||
*.DS_Store
|
||||
book/
|
||||
|
|
|
|||
|
|
@ -15,6 +15,15 @@ Alpha. `v0.3.0` released.
|
|||
- Real-world user testing: still limited.
|
||||
- Issues and PRs welcome.
|
||||
|
||||
## Guide Site (mdBook)
|
||||
|
||||
Book-style guide source lives under `docs/book/` and is deployed via GitHub Pages:
|
||||
|
||||
- Source: `docs/book/src/`
|
||||
- Build config: `docs/book/book.toml`
|
||||
- CI workflow: `.github/workflows/mdbook.yml`
|
||||
- Published URL: `https://milind220.github.io/kicad-ipc-rs/`
|
||||
|
||||
## Usage
|
||||
|
||||
### Async API (Default)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,13 @@
|
|||
[book]
|
||||
authors = ["Milind Sharma"]
|
||||
language = "en"
|
||||
src = "src"
|
||||
title = "KiCad IPC RS"
|
||||
|
||||
[build]
|
||||
build-dir = "../../book"
|
||||
|
||||
[output.html]
|
||||
default-theme = "light"
|
||||
git-repository-url = "https://github.com/Milind220/kicad-ipc-rs"
|
||||
site-url = "/kicad-ipc-rs/"
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
# KiCad IPC RS
|
||||
|
||||
- [Introduction](intro.md)
|
||||
- [Quickstart](quickstart.md)
|
||||
- [Usage Patterns](usage-patterns.md)
|
||||
- [Examples](examples.md)
|
||||
- [Validation and Testing](validation.md)
|
||||
- [API Reference](api-reference.md)
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
# API Reference
|
||||
|
||||
Primary API docs live on docs.rs:
|
||||
|
||||
- [kicad-ipc-rs API Reference](https://docs.rs/kicad-ipc-rs)
|
||||
|
||||
Key items:
|
||||
|
||||
- `KiCadClient` (async)
|
||||
- `KiCadClientBlocking` (`blocking` feature)
|
||||
- `KiCadError`
|
||||
- Typed models under `model::*`
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
# Examples
|
||||
|
||||
## Quick Version Probe (Async)
|
||||
|
||||
```rust,no_run
|
||||
use kicad_ipc_rs::KiCadClient;
|
||||
|
||||
#[tokio::main(flavor = "current_thread")]
|
||||
async fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
|
||||
let client = KiCadClient::connect().await?;
|
||||
let version = client.get_version().await?;
|
||||
println!("{:?}", version);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Open Board Detection (Blocking)
|
||||
|
||||
```rust,no_run
|
||||
use kicad_ipc_rs::KiCadClientBlocking;
|
||||
|
||||
fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
|
||||
let client = KiCadClientBlocking::connect()?;
|
||||
let has_board = client.has_open_board()?;
|
||||
println!("open board: {}", has_board);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## CLI-first Smoke Testing
|
||||
|
||||
Runbook commands:
|
||||
|
||||
```bash
|
||||
cargo run --features blocking --bin kicad-ipc-cli -- ping
|
||||
cargo run --features blocking --bin kicad-ipc-cli -- version
|
||||
cargo run --features blocking --bin kicad-ipc-cli -- board-open
|
||||
```
|
||||
|
||||
Full command catalog: [docs/TEST_CLI.md](https://github.com/Milind220/kicad-ipc-rs/blob/main/docs/TEST_CLI.md)
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
# Introduction
|
||||
|
||||
`kicad-ipc-rs` is an async-first Rust client for KiCad IPC.
|
||||
|
||||
Project goals:
|
||||
|
||||
- Rust-native API for KiCad IPC commands.
|
||||
- Typed models for common board/editor operations.
|
||||
- Blocking wrapper parity via `feature = "blocking"`.
|
||||
- Maintainer-friendly release and proto-regeneration flow.
|
||||
|
||||
Current scope:
|
||||
|
||||
- KiCad API proto snapshot pinned in repo (`src/proto/generated/`).
|
||||
- 56/56 wrapped command families from the current snapshot.
|
||||
- Runtime compatibility verified against KiCad `10.0.0-rc1`.
|
||||
|
||||
Core entrypoints:
|
||||
|
||||
- Async: `kicad_ipc_rs::KiCadClient`
|
||||
- Blocking: `kicad_ipc_rs::KiCadClientBlocking` (`blocking` feature)
|
||||
- Error type: `kicad_ipc_rs::KiCadError`
|
||||
|
||||
Related docs:
|
||||
|
||||
- Crate README: [README.md](https://github.com/Milind220/kicad-ipc-rs/blob/main/README.md)
|
||||
- CLI runbook: [docs/TEST_CLI.md](https://github.com/Milind220/kicad-ipc-rs/blob/main/docs/TEST_CLI.md)
|
||||
- API docs: [docs.rs/kicad-ipc-rs](https://docs.rs/kicad-ipc-rs)
|
||||
|
|
@ -0,0 +1,70 @@
|
|||
# Quickstart
|
||||
|
||||
## Prereqs
|
||||
|
||||
1. KiCad running on the same machine.
|
||||
2. IPC socket available (default discovery, or `KICAD_API_SOCKET`).
|
||||
3. Optional auth token in `KICAD_API_TOKEN` if your setup requires it.
|
||||
|
||||
## Async API (default)
|
||||
|
||||
`Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
kicad-ipc-rs = "0.3.1"
|
||||
tokio = { version = "1", features = ["macros", "rt"] }
|
||||
```
|
||||
|
||||
```rust,no_run
|
||||
use kicad_ipc_rs::KiCadClient;
|
||||
|
||||
#[tokio::main(flavor = "current_thread")]
|
||||
async fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
|
||||
let client = KiCadClient::builder()
|
||||
.client_name("quickstart-async")
|
||||
.connect()
|
||||
.await?;
|
||||
|
||||
client.ping().await?;
|
||||
let version = client.get_version().await?;
|
||||
println!("KiCad: {}", version.full_version);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Blocking API
|
||||
|
||||
`Cargo.toml`:
|
||||
|
||||
```toml
|
||||
[dependencies]
|
||||
kicad-ipc-rs = { version = "0.3.1", features = ["blocking"] }
|
||||
```
|
||||
|
||||
```rust,no_run
|
||||
use kicad_ipc_rs::KiCadClientBlocking;
|
||||
|
||||
fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
|
||||
let client = KiCadClientBlocking::builder()
|
||||
.client_name("quickstart-blocking")
|
||||
.connect()?;
|
||||
|
||||
client.ping()?;
|
||||
let version = client.get_version()?;
|
||||
println!("KiCad: {}", version.full_version);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose | Used by |
|
||||
| --- | --- | --- |
|
||||
| `KICAD_API_SOCKET` | Explicit IPC socket URI/path override | async + blocking |
|
||||
| `KICAD_API_TOKEN` | IPC auth token | async + blocking |
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Use [`kicad-ipc-cli`](https://github.com/Milind220/kicad-ipc-rs/blob/main/test-scripts/kicad-ipc-cli.rs) for rapid command checks.
|
||||
- Follow [Validation and Testing](validation.md) before CI/release.
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
# Usage Patterns
|
||||
|
||||
This chapter targets repeatable integration patterns for tool builders and code generators.
|
||||
|
||||
## Pattern: Cheap Health Check
|
||||
|
||||
Use at process startup to validate socket + auth + server liveness.
|
||||
|
||||
```rust,no_run
|
||||
use kicad_ipc_rs::KiCadClient;
|
||||
|
||||
#[tokio::main(flavor = "current_thread")]
|
||||
async fn main() -> Result<(), kicad_ipc_rs::KiCadError> {
|
||||
let client = KiCadClient::connect().await?;
|
||||
client.ping().await?;
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Pattern: Read-only Query Pipeline
|
||||
|
||||
Recommended order for board-aware reads:
|
||||
|
||||
1. `get_open_documents()`
|
||||
2. `get_nets()`
|
||||
3. `get_items_by_net(...)` or `get_items_by_type_codes(...)`
|
||||
|
||||
Reason: fail fast on document state before expensive item traversal.
|
||||
|
||||
## Pattern: Safe Write Session
|
||||
|
||||
Use begin/end commit around mutating commands.
|
||||
|
||||
1. `begin_commit(...)`
|
||||
2. `create_items(...)` / `update_items(...)` / `delete_items(...)`
|
||||
3. `end_commit(..., CommitAction::Commit, ...)`
|
||||
|
||||
If errors mid-flight: close with `CommitAction::Abort`/`Drop` per flow.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
| Pitfall | Symptom | Avoidance |
|
||||
| --- | --- | --- |
|
||||
| Assume KiCad always running | connect errors at startup | explicit prereq check + `ping()` |
|
||||
| Skip open-document check | downstream command failures | call `get_open_documents()` first |
|
||||
| Mix sync + async API unintentionally | duplicate runtime ownership | pick one surface per process |
|
||||
| Fire write commands without commit session | partial or rejected mutations | always bracket writes with commit APIs |
|
||||
| Hardcode unsupported commands | `AS_UNHANDLED` at runtime | map/handle `RunActionStatus` and runtime flags |
|
||||
|
||||
## Async vs Blocking Selection
|
||||
|
||||
| Requirement | Preferred API |
|
||||
| --- | --- |
|
||||
| Tokio app / async daemon | `KiCadClient` |
|
||||
| Existing sync binary | `KiCadClientBlocking` |
|
||||
| Lowest integration friction for scripts | `KiCadClientBlocking` + CLI |
|
||||
|
||||
## Reliability Checklist
|
||||
|
||||
- Set explicit `client_name` for traceability.
|
||||
- Keep request timeout defaults unless measured need.
|
||||
- Handle transport + protocol errors as recoverable boundary.
|
||||
- Use typed wrappers when available; drop to raw only when needed.
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
# Validation and Testing
|
||||
|
||||
Before handoff or release:
|
||||
|
||||
```bash
|
||||
cargo fmt --all
|
||||
cargo test
|
||||
cargo test --features blocking
|
||||
```
|
||||
|
||||
## Evidence Pointers
|
||||
|
||||
- Unit tests across client/model/blocking/CLI parser paths:
|
||||
- [`src/client.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/src/client.rs)
|
||||
- [`src/blocking.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/src/blocking.rs)
|
||||
- [`src/model/common.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/src/model/common.rs)
|
||||
- [`src/model/board.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/src/model/board.rs)
|
||||
- [`test-scripts/kicad-ipc-cli.rs`](https://github.com/Milind220/kicad-ipc-rs/blob/main/test-scripts/kicad-ipc-cli.rs)
|
||||
- Runtime command coverage matrix:
|
||||
- [README coverage section](https://github.com/Milind220/kicad-ipc-rs#kicad-v10-rc11-api-completion-matrix)
|
||||
- Runtime CLI verification flow:
|
||||
- [docs/TEST_CLI.md](https://github.com/Milind220/kicad-ipc-rs/blob/main/docs/TEST_CLI.md)
|
||||
|
||||
## CI Notes
|
||||
|
||||
- API/release pipeline: `.github/workflows/release-plz.yml`
|
||||
- Book deploy pipeline: `.github/workflows/mdbook.yml`
|
||||
Loading…
Reference in New Issue