Zero-effort device docs & gate d3 · PLESTY Report July 2026

Every device in plesty now ships reference docs generated straight from its live doc_model(). As a user you get docs that always match the real API; as a contributor you write none.

plesty-sdk 📖 docs [Device] tier

Using it — find & read any device's reference

Open a device module's documentation and you'll find four reference pages, regenerated from the device's schema on every build — so what you read is exactly what you can run, and it can't drift from the code.

Start on Usage to see how to connect and drive the device; reach for Parameters and Functions as the complete, typed list of what you can set and call.

Usage

how to drive it

Copy-ready connect / read / set examples for the device — the fastest way to get it moving.

Parameters

what you can set

Every config key with its type, unit, access, and valid range — so you know exactly what a value means before you change it.

Functions

what you can call

Each operation with its inputs and outputs — the callable surface of the device at a glance.

Standard Methods

the shared contract

The commands every device answers — connect, identity, check_errors, reset — so switching devices doesn't mean relearning basics.

Contributing — document your device for free

Declare the module a device

Auto-generation keys off module_type = "device". Your schemas already describe the parameters and operations, so the base device builds doc_model() for you — there are no reference .md files to write.

# pyproject.toml
[tool.plesty]
standard    = "quantum"
module_type = "device"

Build — the four pages appear

Generation runs before the Sphinx build (scaffolded by plesty init), so a plain build produces the reference pages from your live model. Preview them locally before you push.

Terminal

uv run plesty docs serve
# → generates Usage / Parameters / Functions / Standard Methods
# → builds the site and opens it for preview

The guardrail — gate d3 in plesty check

Because the docs are generated, a contributor needs to know they'll actually render. Gate d3 ([Device] tier) runs in plesty check / CI and, in an isolated subprocess, proves your device is documentable — so a broken model fails fast, on your machine, not on the published site:

# what d3 verifies, in essence
device = load_doc_device()          # imports the module, constructs WITHOUT hardware
model  = device.doc_model()

if not model.standard_methods:
    raise SystemExit("doc_model().standard_methods is empty")
if not (model.parameters or model.functions):
    raise SystemExit("device documents neither parameters nor functions")

render_device_pages(model)             # every page must render without error
print("D3_OK")

So to pass d3 your device must import and construct without real hardware, and expose a non-empty model that renders. Non-device modules print ✓ Device Docs (N/A — not a device module) and skip it.

What you do vs. what everyone gets

✗ Before

• Authors hand-wrote Usage / Parameters / Functions
• Every schema change meant re-editing docs
• Users hit reference that had drifted from the API
• Nothing checked the docs even built

✓ Now

• Contributors declare module_type = "device" — done
• Pages regenerate from doc_model() each build
• Users get reference that can't drift from the schema
• Gate d3 blocks CI if it won't render