# Generated Documentation

## Local generation

Install prerequisites:

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

Then generate and validate public docs:

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

NixOS-friendly alternative:

```bash
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.