# powersync-docs

Documentation ETM PowerSync — [docs.etm-powersync.fr](https://docs.etm-powersync.fr)

MkDocs Material, **docs-as-code**, trois langues : `fr` (défaut) · `de` · `en`.
Licence : CC-BY-4.0 pour la documentation, GPL-3.0 pour les exemples de code.

---

## La règle qui explique tout le reste

**95 % du volume est GÉNÉRÉ, pas rédigé.** Mesure du 2026-10-12 : 74 013 mots générés
contre 3 506 mots de prose, sur 107 pages. Tout ce qui est entre

```
<!-- BEGIN GENERATED: <clé> -->   …   <!-- END GENERATED -->
```

est produit par un script depuis une source de vérité, et **écrasé à chaque passage**.
Éditer à l'intérieur de ces marqueurs, c'est écrire quelque chose qui disparaîtra.

| Générateur | Source de vérité | Produit |
|---|---|---|
| `scripts/gen_device_reference.py` | `PORTING_STATUS.yaml` + les `integrationplugin*.json` et `meta.json` des 5 dépôts de plugins | fiches appareils, index de catégorie, matrice de compatibilité, `appareils/SUMMARY.md` |
| `scripts/gen_api_reference.py` | `introspect.json` (introspection nymea) | référence JSON-RPC (23 pages), `api/SUMMARY.md` |

## Multi-langue — où passe la frontière

Deux régimes, et ils ne se traitent pas pareil :

- **Le bloc de référence est en ANGLAIS, une seule fois, servi identique dans les trois
  langues.** Décision du 2026-10-12. La raison est une mesure, pas un goût : nymea ne sert
  **aucune** traduction sur notre parc — vérifié sur le banc `hems`, où
  `Integrations.GetThingClasses` rend la **même charge utile au sha256 près** (243 340 octets)
  pour `fr_FR`, `de_DE` et `en_US`. Les noms de modèles, de registres et d'unités sont donc
  déjà en anglais ; traduire les seuls en-têtes de colonnes autour aurait fabriqué des pages
  bilingues sans rien gagner. Le vocabulaire vit dans le dict `REF` de chaque générateur.
- **La prose et la navigation se TRADUISENT.** Fichiers suffixés (`page.md` = fr,
  `page.de.md`, `page.en.md`), libellés de nav par `nav_translations` dans `mkdocs.yml`,
  échafaudage des pages créées par le dict `SCAFFOLD` du générateur appareils.

> **Pourquoi `SCAFFOLD` existe.** Sans lui, chaque nouvel appareil ajouté créerait sa fiche
> dans la seule langue par défaut, et `fallback_to_default` la servirait **en français** sous
> `/de/` et `/en/`. Le générateur crée donc les trois variantes — et **ne réécrit jamais** une
> page existante, pour que la prose traduite à la main survive aux régénérations.

### Localisation ≠ traduction

`docs/tarifs.md` est l'exemple à connaître : la version FR parle de Tempo et du signal RTE,
la DE de `§14a EnWG` et de SMARD, l'EN des deux. Ce ne sont **pas** des traductions l'une de
l'autre, et c'est volontaire — les signaux tarifaires sont nationaux. Même traitement pour la
ligne correspondante de `docs/fonctionnalites/index.md`.

---

## Travailler dessus

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt

# Prévisualiser (les trois langues sont construites ensemble)
mkdocs serve

# Régénérer la référence appareils — exige les JSON des 5 dépôts de plugins
# dans .plugins-src/ (la CI les clone ; en local, copiez-les depuis le workspace)
python3 scripts/gen_device_reference.py --src .plugins-src --docs docs \
        --lang fr --locales fr,de,en

# Régénérer la référence API
python3 scripts/gen_api_reference.py --src introspect.json --docs docs

# Ce que vérifie la CI : rien ne doit changer après régénération
mkdocs build --strict
python3 scripts/gen_device_reference.py --src .plugins-src --docs docs \
        --lang fr --locales fr,de,en --check
```

⚠️ `mkdocs build --strict` **échoue sur un simple avertissement**. C'est pour cela que
`navigation.instant` est retiré de `theme.features` : il est incompatible avec le lien
contextuel du sélecteur de langue de `mkdocs-static-i18n`. Le commentaire est dans
`mkdocs.yml`, à l'endroit du retrait.

## Déploiement

CI Gitea (`.gitea/workflows/docs.yml`) sur push vers `main`, plus un passage nocturne à 3 h
(les `meta.json` des dépôts de plugins bougent sans que ce dépôt-ci bouge). Pipeline :
clone des 5 dépôts de plugins → génération appareils → génération API → `mkdocs build
--strict` → contrôle d'idempotence → `rsync` vers le serveur.

Le build produit `site/` (fr), `site/de/` et `site/en/` en une passe ; le `rsync --delete`
pousse l'ensemble.