Skip to content

What is here

How this site is organised

The topic sections follow what somebody is trying to do, not how the code is laid out.

Section Written for Answers
Studying A learner Signing in, sitting a session and what is in it, reading the results, cards, plans, the settings they own
Reading A learner What an article is made of, how to find one, what the figures and cross-references do
Writing An editor The Editorial queues, the article editor, drafting, revisions, decks, learners' reports
Question bank An editor Getting questions in, reviewing the drafts, writing a question, filing, exams and blueprints
Access Whoever hands out access Roles, grants, how to give somebody access, and what each one can and cannot reach
Administration Whoever runs the site Settings, site policy, models, people, lab values, jobs, the image bank
Operations Whoever runs the server Deploying, configuring, backing up, testing, troubleshooting
API Somebody writing a client Every endpoint, and the contract around them
Internals Somebody changing the code The existing design notes, kept as written

Two journeys run end to end through those sections rather than sitting in one of them:

What this site is built from

Everything on the topic pages was read out of the code in /home/danvics/docker/quiz before it was written down. Where a number appears — a threshold, a TTL, a retention window — it came from the constant that sets it, not from a previous document.

docs/openapi.json is a snapshot of the live schema, regenerated with:

docker exec -w /app -e PYTHONPATH=/app quiz-backend-1 \
  python -c "import json;from app.main import app;print(json.dumps(app.openapi()))" \
  > docs/openapi.json

Regenerate it whenever a route is added, removed or changed. The same document is served by the running application at /api/openapi.json; this copy exists so the documentation site renders without a backend behind it.

Building this site

python3 -m venv /tmp/mkdocsenv
/tmp/mkdocsenv/bin/pip install mkdocs-material
/tmp/mkdocsenv/bin/mkdocs build --strict     # from the repository root
/tmp/mkdocsenv/bin/mkdocs serve              # http://127.0.0.1:8000

--strict turns every broken link, bad anchor and page missing from the nav into a build failure. Keep it that way.

Three things in docs/ are deliberately not published, and are excluded in mkdocs.yml: TODO.md, the quiz-revamp-* planning notes with their screenshots, and figures/ (artwork belonging to articles, not to this site).

Where the old documents went

README.md at the repository root is still the front page of the repository. ADMIN.md is now a pointer: what it used to hold has moved into Operations, Access and Signing in, so there is one copy of each fact rather than two that drift.

The deep technical notes that were loose in docs/ moved to docs/internals/ unchanged.