beatz174-bit
42 lines
1.0 KiB
Markdown
42 lines
1.0 KiB
Markdown
# 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.
|