Writing these docs¶
The site is MkDocs with the Material theme. Sources are in docs/src, the
configuration is docs/mkdocs.yml, and dependencies are managed by Poetry in
docs/pyproject.toml.
Build and preview¶
make docs # build into docs/site (strict: warnings fail the build)
make docs-serve # live preview on http://127.0.0.1:8000
make docs-clean # remove docs/site and docs/.venv
Without Poetry on the host, build in a container:
docker run --rm -v "$PWD":/src -w /src/docs python:3.13 sh -c \
'pip install -q poetry && poetry install -q --no-root && poetry run mkdocs build'
Generated content¶
- IAMClient field tables.
docs/hooks/crd_reference.pyreplaces<!-- crd-fields: spec -->and<!-- crd-fields: status -->with tables built fromdeploy/crd.yaml. Field descriptions come from the doc comments insrc/crd.rs, so fix wording there and regenerate the CRD. - Manifests. Pages include files from the repository with the snippets
syntax, for example
--8<-- "deploy/rbac.yaml", so examples cannot drift from what is deployed.
Conventions¶
- Every page starts with the SPDX header as an HTML comment (
make license-check). - Diagrams in Mermaid fences.
- No real infrastructure: no real tenant IDs, client IDs, hostnames or IP
addresses; use
example.comand obviously fake GUIDs. - No em-dashes; use a colon, comma, parentheses or a new sentence.
- New pages go in
navinmkdocs.yml(MkDocs only logs pages left out of it). The strict build fails on broken links and missing snippet files.