Skip to content

Commit 8a00c14

Browse files
benbrandtbenbrandt
authored
docs: Add mdbook build (#120)
* docs: Add mdbook build * UPdate ci * remove js assets
1 parent d6c9d51 commit 8a00c14

15 files changed

Lines changed: 3594 additions & 0 deletions

‎.github/workflows/mdbook.yml‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Sample workflow for building and deploying a mdBook site to GitHub Pages
2+
#
3+
# To get started with mdBook see: https://rust-lang.github.io/mdBook/index.html
4+
#
5+
name: Deploy mdBook site to Pages
6+
7+
on:
8+
# Runs on pushes targeting the default branch
9+
push:
10+
branches: ["main"]
11+
12+
# Allows you to run this workflow manually from the Actions tab
13+
workflow_dispatch:
14+
15+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
16+
permissions:
17+
contents: read
18+
pages: write
19+
id-token: write
20+
21+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
22+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
23+
concurrency:
24+
group: "pages"
25+
cancel-in-progress: false
26+
27+
jobs:
28+
# Build job
29+
build:
30+
runs-on: ubuntu-latest
31+
# Only run on the main repository, not on forks
32+
if: github.repository == 'agentclientprotocol/rust-sdk'
33+
steps:
34+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
35+
36+
- name: Install mdBook
37+
uses: taiki-e/install-action@a2352fc6ce487f030a3aa709482d57823eadfb37
38+
with:
39+
tool: mdbook,mdbook-mermaid
40+
41+
- name: Setup Pages
42+
id: pages
43+
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
44+
45+
- name: Install mermaid assets
46+
run: mdbook-mermaid install .
47+
48+
- name: Build with mdBook
49+
run: mdbook build
50+
51+
- name: Upload artifact
52+
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
53+
with:
54+
path: ./book
55+
56+
# Deployment job
57+
deploy:
58+
environment:
59+
name: github-pages
60+
url: ${{ steps.deployment.outputs.page_url }}
61+
runs-on: ubuntu-latest
62+
needs: build
63+
# Only run on the main repository, not on forks
64+
if: github.repository == 'agentclientprotocol/rust-sdk'
65+
steps:
66+
- name: Deploy to GitHub Pages
67+
id: deployment
68+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
target
22
.DS_Store
33
book
4+
mermaid.min.js
5+
mermaid-init.js

‎AGENTS.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
This repository is the Rust SDK for the Agent Client Protocol (ACP).
2+
3+
The mdbook Table of Contents in `md/SUMMARY.md` contains all relevant documentation. You should keep it up to date as you work.
4+
5+
The crates are found in `src/*`. Each crate's `README.md` and `CHANGELOG.md` describe its purpose and history; the `md/introduction.md` chapter gives a map of how the crates fit together.
6+
7+
## Crate Layout
8+
9+
- `agent-client-protocol` – Core protocol SDK (roles, connections, handlers, schema)
10+
- `agent-client-protocol-tokio` – Tokio utilities (process spawning, stdio transports)
11+
- `agent-client-protocol-rmcp` – Integration with the `rmcp` crate
12+
- `agent-client-protocol-cookbook` – Usage patterns rendered as rustdoc
13+
- `agent-client-protocol-derive` – Proc macros
14+
- `agent-client-protocol-conductor` – Conductor binary and library for proxy chains
15+
- `agent-client-protocol-test` – Shared test utilities and fixtures
16+
- `agent-client-protocol-trace-viewer` – Interactive sequence diagram viewer
17+
- `yopo` – "You Only Prompt Once" example client
18+
19+
## Working With the Book
20+
21+
- Source lives under `md/` and is configured by `book.toml`.
22+
- The `mdbook-mermaid` preprocessor is required for diagrams; install both tools with `cargo install mdbook mdbook-mermaid`.
23+
- Before the first local build, run `mdbook-mermaid install .` from the repo root to drop `mermaid.min.js` and `mermaid-init.js` alongside `book.toml` (both files are git-ignored).
24+
- Build the book with `mdbook build`; preview with `mdbook serve`.
25+
- Publishing is automated by `.github/workflows/mdbook.yml`, which installs the mermaid assets and deploys to GitHub Pages on pushes to `main`.
26+
27+
## Conventional Commits
28+
29+
This repository uses **Conventional Commits** for automated releases via release-plz. All commit messages should follow this format:
30+
31+
```
32+
<type>[optional scope]: <description>
33+
34+
[optional body]
35+
36+
[optional footer(s)]
37+
```
38+
39+
### Commit Types
40+
41+
- **feat:** A new feature (triggers minor version bump)
42+
- **fix:** A bug fix (triggers patch version bump)
43+
- **docs:** Documentation only changes
44+
- **style:** Code style changes (formatting, missing semicolons, etc.)
45+
- **refactor:** Code changes that neither fix bugs nor add features
46+
- **perf:** Performance improvements
47+
- **test:** Adding or updating tests
48+
- **chore:** Maintenance tasks, dependency updates, etc.
49+
- **ci:** CI/CD configuration changes
50+
- **build:** Build system or external dependency changes
51+
52+
### Breaking Changes
53+
54+
Add `!` after the type to indicate breaking changes (triggers major version bump):
55+
56+
```
57+
feat!: change API to use async traits
58+
```
59+
60+
Or include `BREAKING CHANGE:` in the footer:
61+
62+
```
63+
feat: redesign conductor protocol
64+
65+
BREAKING CHANGE: conductor now requires explicit capability registration
66+
```
67+
68+
### Examples
69+
70+
```
71+
feat(conductor): add support for dynamic proxy chains
72+
fix(agent-client-protocol): resolve deadlock in message routing
73+
docs: update README with installation instructions
74+
chore: bump tokio to 1.40
75+
```
76+
77+
### Scope Guidelines
78+
79+
Common scopes for this repository (typically the crate name without the `agent-client-protocol-` prefix where unambiguous):
80+
81+
- `acp` – Core protocol changes
82+
- `conductor` – Conductor-specific changes
83+
- `tokio` – Tokio utility changes
84+
- `rmcp` – rmcp integration changes
85+
- `cookbook` – Cookbook patterns and docs
86+
- `trace-viewer` – Trace viewer changes
87+
- `deps` – Dependency updates
88+
89+
**Agents should help ensure commit messages follow this format.**

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

‎book.toml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[book]
2+
authors = ["Niko Matsakis"]
3+
language = "en"
4+
src = "md"
5+
title = "Agent Client Protocol Rust SDK"
6+
description = "Design and architecture documentation for the Agent Client Protocol Rust SDK"
7+
8+
[preprocessor.mermaid]
9+
command = "mdbook-mermaid"
10+
11+
[output.html]
12+
additional-js = ["mermaid.min.js", "mermaid-init.js"]
13+
git-repository-url = "https://github.com/agentclientprotocol/rust-sdk"
14+
edit-url-template = "https://github.com/agentclientprotocol/rust-sdk/edit/main/{path}"

‎md/SUMMARY.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Summary
2+
3+
[Introduction](./introduction.md)
4+
5+
# Core Library (agent-client-protocol)
6+
7+
- [Design Overview](./design.md)
8+
- [Protocol Reference](./protocol.md)
9+
10+
# Conductor (agent-client-protocol-conductor)
11+
12+
- [Conductor Design](./conductor.md)
13+
- [MCP Bridge](./mcp-bridge.md)
14+
15+
# Tools
16+
17+
- [Trace Viewer](./trace-viewer.md)
18+
19+
# Reference
20+
21+
- [Migrating to v0.11](./migration_v0.11.x.md)
22+
- [P/ACP Specification](./proxying-acp.md)
23+
24+
# Archive
25+
26+
- [Transport Architecture](./transport-architecture.md)

0 commit comments

Comments
 (0)