opencode
6c92b6358d
Full documentation hub replacing the release-notes-only view: - Handbook pages (docs/handbook) for all features and admin/betrieb - API reference generated from lib/api-spec/openapi.yaml via scripts/src/generate-docs.mjs (replaces sync-release-docs.mjs): endpoints, schemas/fields, search index, per-release snapshots - mkdocs layout: sidebar nav, right TOC with scrollspy, search overlay, version dropdown, repo link - FieldHelp (?) buttons in forms linking to reference field docs - v0.7.0 release notes backfilled, v0.8.0 release notes added
52 lines
2.1 KiB
Markdown
52 lines
2.1 KiB
Markdown
# Dokumentation (Handbuch, API-Referenz, Release-Notes)
|
|
|
|
Die App zeigt unter `/docs` eine MkDocs-artige Doku-Seite mit drei Bereichen:
|
|
|
|
- **Handbuch** (`docs/handbook/*.md`) — von Hand gepflegte Anleitungen
|
|
- **API-Referenz** (`lib/api-spec/openapi.yaml`) — automatisch generierte
|
|
Endpunkte & Datenfelder (Schema-Detailseiten mit Feld-Ankern; die `?`-Icons
|
|
in Formularen verlinken auf diese Felder)
|
|
- **Release-Notes** (`docs/releases/vX.Y.Z.md`) — pro Release
|
|
|
|
## Struktur
|
|
|
|
- `docs/handbook/` — Handbuch-Seiten mit Frontmatter (`title`, `order`)
|
|
- `docs/releases/TEMPLATE.md` — Vorlage für neue Releases
|
|
- `docs/releases/vX.Y.Z.md` — Notes pro Release
|
|
- `docs/releases/vX.Y.Z/reference.json` — API-Snapshot der jeweiligen Version
|
|
|
|
## Generator
|
|
|
|
`scripts/src/generate-docs.mjs` wird beim Frontend-Build (und `dev`) automatisch
|
|
ausgeführt und schreibt die Artefakte nach `artifacts/toolrate/public/docs/`:
|
|
|
|
- `reference.json` (aktuelle API), `search.json` (Suchindex),
|
|
`index.json` (Releases), `handbook/*.md` + `handbook/index.json`
|
|
- `releases/vX.Y.Z.md` und `versions/vX.Y.Z.json` (API-Snapshots alter Versionen)
|
|
|
|
Manuell aufrufbar:
|
|
|
|
```sh
|
|
node scripts/src/generate-docs.mjs # Build-Modus
|
|
node scripts/src/generate-docs.mjs --snapshot v0.9.0 # Snapshot für neue Version
|
|
```
|
|
|
|
## Workflow beim Release
|
|
|
|
1. **Version taggen** wie bisher (`git tag vX.Y.Z`, CI baut und deployed).
|
|
2. **`docs/releases/vX.Y.Z.md` anlegen** — Vorlage aus `TEMPLATE.md` kopieren,
|
|
Entwurf aus der Git-Historie ableiten:
|
|
```sh
|
|
git log --oneline vX.Y.Z-1..vX.Y.Z
|
|
```
|
|
(API-Delta anhand `lib/api-spec/openapi.yaml` prüfen.)
|
|
3. **API-Snapshot erzeugen:** `node scripts/src/generate-docs.mjs --snapshot vX.Y.Z`
|
|
erzeugt `docs/releases/vX.Y.Z/reference.json`.
|
|
4. **Committen & pushen.** Der Build kopiert die Dokumentation automatisch nach
|
|
`artifacts/toolrate/public/docs/` und generiert `index.json`.
|
|
|
|
> Hinweis: Alle Dateien unter `artifacts/toolrate/public/docs/` sind
|
|
> Build-Artefakte und werden bei jedem Build neu generiert — nicht von Hand
|
|
> bearbeiten. Einzige Quellen sind `docs/handbook/`, `docs/releases/` und
|
|
> `lib/api-spec/openapi.yaml`.
|