docker/docs/README.md

Generated Documentation

Local generation

Install prerequisites:

sudo apt-get update
sudo apt-get install -y graphviz

Then generate and validate public docs:

chmod +x scripts/docs/*.sh
scripts/docs/generate-all.sh
python3 -m mkdocs build -f mkdocs-public.yml --strict

NixOS-friendly alternative:

nix shell nixpkgs#graphviz nixpkgs#python3 nixpkgs#python3Packages.pyyaml

This pipeline only runs docker compose config and static parsing. It does not start containers.

CI behaviour

GitHub Actions workflow .github/workflows/generate-docs.yml validates committed public docs and diagrams and runs a strict public MkDocs build.

Outputs

• docs/generated: resolved compose config and markdown inventories
• docs/diagrams: generated DOT and SVG diagrams
• docs/public: sanitized copy for public sharing

Publication safety

• docs/public is intended for public sharing after sanitization.
• docs/generated and docs/diagrams may include internal details and should be treated as internal by default.