Skip to content

1. Reference pages are generated from the code

Status: accepted, October 2026

Context

The README had grown to nearly 500 lines covering installation, tutorials, every feature and a code map. Lists that also exist in the code (the building blocks, interface profiles, MCP tools, JLCPCB limits, settings) were written out by hand and had started to drift from it. The designer AI is given its own detailed description of the design spec, which was the most accurate description of the format anywhere, but no person could read it.

Decision

  • Documentation is an MkDocs site with the Material theme, in docs/, organised by the Diátaxis framework: tutorials, how-to guides, reference and explanation.
  • Reference pages whose content lives in the code are generated by docs/gen.py at build time: building blocks, interface profiles, mains requirements, MCP tools, JLCPCB limits, settings, and the Python API (mkdocstrings).
  • The design spec page is generated from the designer's own system prompt, so people and the AI read the same text.
  • The site is built with --strict in CI, so broken links and missing pages fail the build.

Consequences

  • Changing a block, profile or limit updates the documentation with no extra step.
  • Generated pages cannot be edited in docs/; the "edit" link points at the source file.
  • Improving the spec page means improving the AI's prompt, which is usually what is wanted anyway.
  • Building the docs imports wholeboard, so the package's dependencies must be installed.