Working on quawa

The docs are the truth

These docs are the single source of truth for everyone who develops quawa. Decisions are requirements: every feature and every piece of code must fit them. Each statement that needs a decision is a Sphinx-Needs object with an id and a status.

Object	Prefix	Status	Meaning
Decision	DEC_	approved	decided by Daniel – binding
Proposal	PROP_	draft → review → approved / rejected	part of the technical details, not binding yet
Question	Q_	open → answered	someone has to decide something – see Open questions

An approved proposal becomes a decision: it gets a DEC_ object in Decisions, and the technical page links to it.

Building the docs

The docs are Markdown (MyST) in docs/, built with Sphinx. Their Python tools live in docs/pyproject.toml.

$ cd docs && uv sync
$ .venv/bin/sphinx-autobuild . _build/html --port 4342   # live preview
$ .venv/bin/sphinx-build -W -b html . _build/html        # check build, warnings fail

The docs are public, the code is not (The code stays private for ... (DEC_CODE_PRIVATE)): on every push to main that changes the docs, .github/workflows/docs.yml builds them and publishes the HTML to the gh-pages branch of the public repository danwos/quawa.docs – https://quawa.danwos.dev. Pull requests only check the build.