Documenting

How to write and check a page in this book. The book source is docs/, built by mdBook. The code is the only source of truth: verify every behavioural claim in renderer/src, supervisor/src or shared/src before writing it. DECISIONS.md records why things were built; it is history and may be stale, so cite an ADR only as a “why” pointer after the code confirms it.

Commands

Lua examples are tests

Every fenced block whose info string is lua or starts lua, runs in cargo test. The test is every_lua_block_in_the_docs_evaluates_and_lays_out in renderer/src/check.rs. Each block goes through the same evaluation and four layout passes as mantle check: no Wayland, no subprocesses, every capability nil, then one push each of the first, alternate and empty sample sets, one 704x396 output named DP-1. The test fails on a Lua error, a check error or a layout error, and names the block by file:line. Blocks inside > quotes count too.

Prefer lua over fragment, and fragment over no-check. mdBook turns the comma into a second CSS class, so every tag still highlights as Lua.

A widget example needs no surface around it:

rect {
    padding = 6,
    on_click = function() print("clicked") end,
    children = { text { content = "Click" } },
}

Evaluation accepts this width, but layout refuses it:

rect { width = "Wide", height = 10 }

A module file that only makes sense beside another one:

local clock = require("widgets.clock")
return panel { id = "bar", layer = "top", child = clock }

return { require("bar") }  -- fails
local bar = require("bar")
return { bar }             -- works

Screenshots

A lua,shot block also renders, headless over EGL, and must match its committed image, docs/images/<section>/<page>-<n>.png, the page’s n-th shot. tools/book_links.py puts the image under the block on the site, so a page never links it. Tag the example a reader wants to see; a block has to return a node or surfaces.

A quoted absolute path whose file name is in renderer/fixtures/shots/images points at that file. An icon missing from fixtures/shots/icons fails the test with its name; copy it in from Adwaita and note it in fixtures/shots/NOTICE.

A render within 2 per channel of the committed image passes and is not rewritten, so another GPU driver never shows up in git. EGL is required: without it the test fails.

Capability pages

docs/capabilities/<name>.md is generated by supervisor/src/stubs.rs from the payload types in shared/src/state/ and the action types in shared/src/action/. Never edit it: write prose in docs/capabilities/intro/<name>.md and run just stubs.

cargo test fails while a generated page differs from what just stubs would write. intro/ stays out of SUMMARY.md.

Property tables

The property table on each docs/nodes/<kind>.md and docs/surfaces/<role>.md, the common one on nodes/index.md and the box one on guide/paint.md are generated by renderer/src/lua/nodes/stubs.rs from the typed fields in renderer/src/layout/node/properties.rs, the same fields lua-meta/nodes.lua and surfaces.lua come from and the engine parses through. just stubs rewrites what sits between two markers inside the page and leaves the rest alone:

<!-- Generated from renderer/src/layout/node/properties.rs by `just stubs`: edit the table there. -->
<!-- End of the generated table. -->

A page links to the table’s anchors, not to rows. Prose about a property goes around the table, or into its row if every page showing it should say it.

A table a property takes, such as Edges or Transition, is declared with lua_shape! on the struct its parser reads it as (renderer/src/lua/luacats.rs): its /// blocks are what lua-meta says about the shape and each key. The struct fixes the key names and field types; which keys are optional and how Lua spells one (as Option<T>, as S) are marked by hand beside them. One struct has one shape, so anchor_rect, whose x and y may be left out, is declared as region’s Rect with every key required. The book describes a shape in prose on the page.

Page shape

Start with the action or example a reader came for. Put prerequisites and implementation detail after it. A reference page can then give property tables; a tutorial can explain the example in small steps. Add How do I… or Gotchas only when they answer questions the page owns. The introduction, sidebar and FAQ already route readers to topics and symptoms, so do not repeat their indexes on every page.

Keep each behavioral fact on one page and link to it elsewhere. End technical pages with a Source: line of code links. Links to code go out of docs/ as relative paths (../../renderer/src/... from docs/<dir>/x.md); the book turns them into GitHub links and fails the build on a missing target.