Documentation style guide¶
What every Kokeb Labs documentation site contains, how its pages are written and what a README looks like. The pilot
site, kokeb-labs/driver-tmc9660, follows every rule here; copy its structure.
Voice¶
- Plain and specific. "SPI mode 3, up to 10 MHz", not "supports high-speed SPI". Numbers, names, units.
- Second person, present tense, active voice. "Call
init()before anything else", not "The init function should be called". - Short sentences. One idea each. A paragraph is three to five sentences.
- No hype, no filler. No "simply", "just", "easily", "powerful", "comprehensive", "seamless", "robust".
- No emoji in headings, lists or tables. No walls of bold. No exclamation marks.
- Sentence case for titles and headings: "Bus settings", not "Bus Settings".
- British or American spelling: either, consistently within a repository.
- True statements only. Every API name, signature, pin, register and number is checked against the headers or the datasheet. When something is derived rather than measured, say so.
- Never mention how the page was produced. No "generated by", no tool or assistant names.
Every page¶
- A title (
# Title, level one, exactly one), matching its navigation entry. - A purpose line right under it: one sentence saying what the reader gets from the page. The theme renders it as the lead paragraph.
- Sections (
##) in the order a reader needs them. A section that is only a link list belongs in a table or in the navigation instead. - A next step when there is an obvious one (
Next: [Porting](porting.md)).
No Jekyll front matter, no Liquid. Material front matter is allowed only for hide: (the home page hides the
navigation and table of contents).
Components¶
The theme styles these; use them instead of inventing markup.
| Need | Write | Notes |
|---|---|---|
| A warning that prevents damage or lost hours | !!! warning "Title" / !!! danger |
At most two per page. note, tip, example for the rest |
| Optional detail | ??? note "Title" |
Collapsed by default |
| Alternatives (SPI / UART, ESP-IDF / CMake) | === "SPI" tabs |
Same structure in each tab |
| Code | fenced block with a language; title="file.cpp" for a file |
Code from a compiled file: --8<-- "tests/docs/x.cpp:section" |
| Registers, parameters, pins, options | a table | Header row, units in the header, code font for names |
| Bit fields | a table inside <div class="kb-registers" markdown> |
Offset and name columns get code font |
| Sequence or state machine | a mermaid fence |
Themed for light and dark automatically |
| Architecture, signal flow, layouts | a figkit figure | Light and dark from one layout, checked for contrast |
| A light-only image (vendor SVG, photo) | { .kb-plate } |
Sits on a white plate in dark mode |
| Steps | <div class="kb-steps" markdown> around an ordered list |
Numbered circles and a rail |
| The chip or board summary | the chip card (below) | Home page of a driver or HAL |
| A short label | <span class="kb-badge">SPI</span> |
Tones: kb-badge--teal, --amber, --rose |
| A link into Doxygen | [Class::method](api/....html){ .kb-api } |
From api-reference.md, or any page |
| Landing hero | <div class="kb-hero" markdown> with kb-kicker, # Title, a paragraph, buttons |
Home page only |
| Navigation cards | <div class="grid cards" markdown> |
Home page; four to six cards |
Chip card¶
<div class="kb-chip" markdown>
<div class="kb-chip__head">
<span class="kb-chip__kicker">Smart gate driver with on-chip FOC</span>
<span class="kb-chip__name">TMC9660</span>
<span class="kb-chip__vendor">Analog Devices (Trinamic)</span>
</div>
Interface
: SPI mode 3 up to 10 MHz, or UART
Supply
: 7.7 V to 70 V
[Datasheet](datasheet/tmc9660.pdf) ยท [Reference manual](datasheet/ref.pdf)
</div>
Five to seven rows: function, interface (mode, speed, address), supply, key limits, package, and the mode the
driver uses. A board uses class="kb-chip kb-chip--board" with MCU, power input, connectors, chips on board.
Code¶
- It compiles against the real API. In a C++ repository, every snippet longer than one line lives in
build (an
OBJECTlibrary, warnings on) and is included in the page with--8<-- "tests/docs/x.cpp:name". Instantiate the driver template over the documented port so the whole API is compiled. - It is the smallest complete thing. Includes, the object, the calls, the error check. No
// ...in a block that claims to be complete. - It checks results. Every driver call returns a status: show what to do with it.
- Names are real. A reader can paste them. One-line inline names (
setTargetVelocityRpm()) are checked by searching the headers. - The README quickstart is a generated region (
<!-- generated: quickstart-code -->) copied from the same compiled file, so it cannot drift.
Figures¶
- figkit for architecture and anything drawn from the code: one module per figure in
docs/diagrams/figures/<id>.py,data()reads the facts from the headers,build()lays out cards. The build refuses text under 4.5:1 contrast in either theme, overlaps and missing alt text;kokeb-docs figures --checkfails CI when the code changed and the figure did not. Embed with<!-- figure: <id> -->/<!-- /figure -->. - Mermaid for sequences and state machines.
- Chip figures (pinout, block diagram, application circuit) are not written as modules: they are drawn from
docs/hardware.yml(Chip hardware).
Chip hardware¶
Every driver describes its chip once, in docs/hardware.yml (Chip diagrams), and its Hardware
page shows, in this order:
- The pinout (
<!-- figure: chip-pinout -->): the package from the top, pins on the sides and in the order of the datasheet, pin 1 marked, coloured by electrical type, each pin's port hook beside it. - The pin table (
<!-- generated: chip-pins -->): pin, name, type and domain, function, driver hook, what to do when unused, datasheet section and page. No hand-written pin table next to it. - The block diagram (
<!-- figure: chip-blocks -->), from the datasheet's own, with the pins that reach each block. - The application circuit (
<!-- figure: chip-circuit-<id> -->) and its parts (<!-- generated: chip-parts -->): MCU, supplies, decoupling, pull-ups, loads and sense resistors as schematic symbols, every MCU wire labelled with the hook that drives it (GpioSet(CtrlPin::Reset)). A second circuit (the minimal wiring, a variant) is a second entry undercircuits.
The README shows the same chip at a glance, under "At a glance": <!-- figure: chip-pinout -->,
<!-- figure: chip-outline --> (the to-scale package body, from package.outline) and
<!-- figure: chip-blocks -->, then the <!-- generated: chip-card --> table (package, pins, body size, pitch,
supply, other packages), all from the same file.
Every fact cites the datasheet section and printed page. A value the datasheet does not give (a pull-up chosen by
the application, an example load) carries unverified with the reason, and the page shows it as such. The
reference circuit can be exported for a board design with kokeb-docs hardware --kicad-netlist.
How a figure reads¶
Most confusing diagrams mix up what an arrow means or which way to read. Every figure follows these rules:
- One reading direction, said in the subtitle. Top to bottom for layers and calls, left to right for steps in time. When two things happen at different times (a push and a tag), draw two lanes, one per trigger, each with its trigger as the lane title.
- Every arrow is a verb. Solid arrows run or call something; dashed arrows carry data (a file, an artifact, a
setting). Label an arrow whenever the verb isn't obvious from the legend (
uploads,reads,forwards to your hooks). An arrow points from the one acting to the one acted on. - Colour is ownership, three tones at most.
tealis what the reader writes or owns,brandis this repository,slateis outside (hardware, GitHub, ESP-IDF). Draw owned cards withaccent=Trueso they match the legend swatches. Add("~solid", ...)and("~dashed", ...)to the legend when both arrow kinds appear. - Few boxes, short text. At most about eight cards, a title and one or two short lines each. Lists that come from the code (public calls, commands) go in chips inside a region.
- Say the point. The subtitle states the one thing the reader should take away; a
noteanswers the question the figure raises (for example, why the release does not rebuild). - Vendor diagrams only as SVG or compressed PNG, with
{ .kb-plate }, never screenshots of PDFs. - Alt text on every image: one sentence that says what the figure shows, not "diagram". The build fails on a missing alt.
- PDFs (datasheets, manuals) live in
docs/datasheet/and are linked, never embedded; the site links them on GitHub, which renders them.
Tables¶
Use a table whenever there are three or more items with the same attributes: pins, registers, parameters, options,
commands, error codes, compile-time switches. Put units in the header (Range (V)), names in code font, and keep
cells short; long prose goes under the table.
Links¶
- Link pages by file (
[Porting](porting.md#threads)); MkDocs checks them in strict mode. - Link repository files relatively (
[`inc/x.hpp`](../inc/x.hpp)); the plugin turns them into GitHub links at the commit that was built. - Link the API reference with
api/...html; the link check verifies it after Doxygen is merged. - External links go to the primary source (vendor page, datasheet, specification).
Standard page sets¶
Driver (driver-*)¶
| Page | File | Contains |
|---|---|---|
| Home | index.md |
Hero (what, one-sentence why, buttons), the "no platform code" paragraph, chip card, "What you get" (5-7 bullets, each linking its page), navigation cards |
| Quickstart | quickstart.md |
Safety note if it moves hardware; wiring table; add the driver; the port (compiled); a ~15-line example (compiled); what each step does; a "if it does not work" table |
| Installation | installation.md |
Requirements; submodule; CMake target and options; ESP-IDF component; build layout; version; compile-time switches |
| Hardware | hardware.md |
The chip figures and the pin table from docs/hardware.yml (below): pinout, generated pin table, block diagram, application circuit and its parts; control pins; bus settings table (mode, speed, frame, timing); a timing diagram or Mermaid sequence for the protocol; power ranges; errata that affect the host; evaluation boards; reference documents table |
| Architecture | architecture.md |
The layer figure (core, communication interface, platform port); a table of layers with files; one call traced through the layers (Mermaid); design choices (CRTP, no heap); source map |
| API guide | api-guide.md |
Task-oriented, compiled snippets: the shape of the API (subsystems table); initialise; configure; read; write; batch or stream if any; raw register / parameter access; errors and faults (a table of signals); tuning |
| API reference | api-reference.md |
Button to api/index.html; a "start here" table of the five most useful Doxygen pages |
| Examples | examples.md |
<!-- generated: examples --> (from examples/*/app_config.yml); one-time setup; "what to read in an example" table |
| Porting | porting.md |
The interface methods table with contracts; the port for each bus (compiled); rules for the transfer; control-pin levels; reference implementation; how to check a port; threads |
| Testing and CI | testing.md |
Host tests (how to run, what each file covers); compiled snippets; CI workflows table; hardware tests |
| Troubleshooting | troubleshooting.md |
Symptom, cause, fix; start with the cheapest check |
| Changelog | changelog.md |
# Changelog, a purpose line and --8<-- "CHANGELOG.md:N" (from the line after the file's own title) |
| Figures | diagrams/index.md |
Written by kokeb-docs figures |
Deep-dive pages (bootloader, protocols, timing, units, calibration) go under Concepts; configuration
references under Guides. Navigation (docs/.nav.yml) is always five tabs:
nav:
- Home: index.md
- Get started: [Quickstart, Installation, Hardware]
- Concepts: [Architecture, deep dives ...]
- Guides: [API guide, Configuration, Porting, Examples, Troubleshooting]
- Reference: [API reference, Testing and CI, Figures, Changelog]
Core library (kb-core)¶
Home (hero, what problem it solves, a feature list, a "used by" table), Quickstart (smallest use), Concepts (the model the library implements, with a figure), API guide (by task), API reference, Integration (CMake / ESP-IDF, configuration macros), Testing and CI, Changelog. A utilities collection gets one page per utility under Guides, each with purpose, a compiled example and complexity or memory notes.
Board support (HAL) repositories¶
Home with a board card (kb-chip kb-chip--board): MCU, power, connectors, chips on board; Quickstart (flash
an example, see output); Hardware (block diagram figure, pin map as a generated table from the pin configuration,
connectors, power tree); Architecture (managers, how drivers are wired, figure); one guide page per board function;
API reference; Examples; Bring-up and troubleshooting; Changelog.
Firmware products¶
Home (what the product does, a photo or render with alt text, status), Getting started (flash, connect, first run), Architecture (tasks, data flow, figures), Operation (modes, commands, configuration), Hardware (link the HAL site), Development (build, test, release), Troubleshooting, Changelog. Decisions as ADRs under Reference.
CI and tool repositories (ci-tools, espidf-tools)¶
Home (what it provides, a table of workflows or scripts), Quickstart (the smallest caller), one page per workflow or script (purpose, jobs and permissions, inputs table generated from the YAML, example caller, failure modes), Versioning, Migration guides, Changelog.
Organisation (.github, kokeb-labs.github.io)¶
The portal (kokeb-labs.github.io) is the org home: what Kokeb Labs is, a card per product and HAL, a table of every
driver with its chip, bus and docs link, and contribution links. .github holds the profile README following the
README standard, plus community files.
README standard¶
The README is the front door on GitHub. It is short and points to the site.
# Nameand a hero line: one sentence, what it is and what it does.- Badges that are true, in this order, only those that exist: CI (the main test workflow,
branch=main), docs (the docs workflow, linking the site), license, latest release (only once a release exists). No coverage badge without coverage, no "PRs welcome", no badge for a language version. - The documentation link in bold.
- One diagram: the layer or block figure (figkit marker).
- A 30-second example: the generated quickstart region.
- What it does: five to seven bullets.
- Install: the submodule line and the CMake lines.
- Documentation: a table of the five or six most useful pages, linked to the site (
/latest/...). - Tests: one command line.
- License: one line.
No table of contents, no walls of emoji, no feature lists with check marks, no badges that link nowhere, no duplicated API tables (that is the site's job).
Checks that enforce this¶
| Check | Where | Fails on |
|---|---|---|
mkdocs build --strict |
PR CI | broken links and anchors, pages missing from the nav, no H1, Jekyll front matter, Liquid, a page colliding with api/, an image without alt text or file |
kokeb-docs check |
PR CI | an invalid docs/hardware.yml; a figure or generated region that no longer matches the code |
Host build of tests/docs/ |
PR CI (repository) | a snippet that does not compile |
| lychee offline | PR CI | a broken link or anchor in the built site, API included |
| Lighthouse | PR CI | performance, accessibility, best practices or SEO under budget |
| markdownlint | PR CI (repository) | Markdown style |