Contribuer à la documentation

Règles et marche à suivre pour l’équipe qui écrit la documentation.

Sur cette page03

Où vit la documentation
Ajouter une page
Captures d’écran

Cette page s’adresse à l’équipe SuperMDT.

Où vit la documentation

La documentation est un site Starlight dans apps/site. Le français est la langue de référence, servie sous /docs/ ; l’anglais est servi sous /en/docs/. Une page porte le même nom de fichier dans les deux langues : c’est ce qui permet à Starlight de relier les traductions (sélecteur de langue, repli sur le français quand une traduction manque).

Répertoireapps/site/src/
- Répertoireassets/screens/ captures générées (ne pas éditer à la main)
  - Répertoireen/ captures de l’interface en anglais
    …
- components/Screenshot.astro
- Répertoirecontent/docs/
  - Répertoiredocs/ pages françaises (/docs/…)
    index.mdx
    getting-started.mdx
  - Répertoireen/
    Répertoiredocs/ pages anglaises (/en/docs/…)
    index.mdx
    getting-started.mdx

Ajouter une page

Crée la page française dans apps/site/src/content/docs/docs/, par exemple patrols.mdx. Le nom de fichier devient l’URL : /docs/patrols/.

Renseigne le frontmatter : title, description et, pour placer la page dans la barre latérale, sidebar.order.

---
title: Patrouilles
description: Organiser les patrouilles depuis le dispatch.
sidebar:
  order: 10
---

Crée la traduction anglaise avec le même nom de fichier dans apps/site/src/content/docs/en/docs/. Elle sera servie sous /en/docs/patrols/.
Vérifie le rendu avec pnpm --filter @supermdt/site dev, puis ouvre http://localhost:4321/docs/.

La barre latérale est générée automatiquement à partir du dossier docs/ : aucune configuration supplémentaire n’est nécessaire.

Captures d’écran

Les captures ne se font jamais à la main : elles sont générées par tools/screenshots (Playwright), en thème sombre et clair, sur ordinateur et mobile.

Déclare la scène dans tools/screenshots/scenes.ts :

{ name: 'patrols', path: '/dispatch/patrols' }

Lance l’application web (http://localhost:5180), puis régénère les captures :
Fenêtre de terminal
```
pnpm screenshots
pnpm screenshots --lang en
```
Les fichiers sont écrits dans apps/site/src/assets/screens/ (et en/ pour l’anglais) sous la forme <nom>.<theme>.<device>.png.
Insère la capture dans la page avec le composant Screenshot :
```
import Screenshot from '../../../components/Screenshot.astro';

<Screenshot name="patrols" caption="Le tableau des patrouilles" />
```
Ajoute device="mobile" pour la version mobile. Le composant affiche la version sombre ou claire selon le thème choisi par le lecteur, et un encart « Capture à venir » tant que le fichier n’existe pas.

Écrans connectés et panneaux ouverts

La plupart des écrans exigent d’être connecté. Une scène peut le demander avec auth: 'demo' : le script régénère d’abord l’organisation de démonstration « San Andreas RP » (adresse demo) dans la langue des captures, puis se connecte une seule fois avec la connexion de développement (nom « demo ») et réutilise la session pour toutes les scènes. Il faut donc que le backend Convex local tourne, avec DEV_LOGIN=true (et VITE_DEV_LOGIN=true côté application).

Pour capturer un panneau ouvert, ajoute des actions, jouées dans l’ordre. On cible toujours un élément par son rôle et son nom accessibles, jamais par une classe CSS ; un nom peut être donné par langue.

{
  name: 'nav-panel',
  path: '/o/demo',
  auth: 'demo',
  devices: ['desktop'],
  actions: [{ click: { role: 'button', name: { fr: 'Dossiers', en: 'Records' } } }],
}

Actions possibles : click, fill (par libellé), press (raccourci clavier, par exemple 'Control+K'), waitFor et wait (délai, en dernier recours). La démo peut aussi être régénérée à la main :

pnpm --filter @supermdt/backend exec convex run seed:demo '{"locale":"fr"}'

pnpm screenshots --no-seed saute cette étape.