Aller au contenu

Référence

La plus grande partie de cette section est générée lors de la construction du site : la référence de l’API, les pages du schéma de la base de données, le tableau de configuration d’installation et les décisions d’architecture (ADR). Quelques pages sont rédigées à la main :

  • Pipeline de prévisualisation 3D : comment les posters, les turntables, les sprite sheets et les vues de référence sont rendus pour les assets 3D.
  • API par lots de l’outil sprite : comment piloter la disposition des frames, les tags et les variantes de l’outil sprite via l’API HTTP, depuis un script ou une tâche par lots. Les exports restent dans le navigateur.

Quand une page générée est erronée, corrigez-la à la source du problème. Pour les pages de référence issues du dépôt OSS, cela signifie la spécification OpenAPI, les migrations de la base de données, le modèle de configuration ou l’ADR dans le dépôt principal. La feuille de route provient du fichier src/content/roadmap/roadmap.json, tenu à jour à la main dans ce site ; une vérification planifiée de dérive le compare aux publications et jalons GitHub enregistrés dans les données du site. Les problèmes de mise en page ou d’analyse relèvent des scripts de génération de ce site.

Les liens vers les sources pointent vers la branche dev du dépôt principal. Une construction utilise le commit qui a été extrait.

PageGénérée à partir de
Référence de l’APIapp/api/openapi.yaml : copié dans le site par sync-openapi.mjs et rendu par starlight-openapi. Les types d’API du serveur Go sont générés à partir du même fichier par oapi-codegen dans le dépôt principal ; le site ne l’exécute pas.
Schéma de la base de donnéesapp/schema.sql, un dump du schéma seul d’une base construite à partir des migrations : analysé par generate-schema-docs.mjs
Tableau de configuration d’installation dans Installationdocs/install/config/aa.env.example : analysé par sync-install-config.mjs. Seules les variables non commentées deviennent des lignes ; les paramètres facultatifs commentés ne sont pas listés.
Feuille de route (en anglais)src/content/roadmap/roadmap.json dans le dépôt de ce site, tenu à jour à la main : sync-roadmap.mjs écrit la page qui l’affiche. Une vérification planifiée le compare aux publications et jalons GitHub enregistrés dans les données du site.
Décisions d’architecture (barre latérale)docs/adr/*.md : validées et copiées par sync-adrs.mjs

pnpm build et pnpm dev exécutent d’abord les étapes de génération, via les scripts prebuild et predev de package.json ; les pages générées reflètent donc le dépôt principal tel qu’il était extrait à ce moment-là. Exécuter directement astro build ou astro dev les ignore. Les étapes s’exécutent dans cet ordre :

  1. scripts/sync-adrs.mjs analyse et valide le frontmatter YAML de chaque ADR (docs/adr/*.md), vérifie les références croisées entre ADR, puis écrit les pages des ADR ainsi que les données utilisées par le catalogue.
  2. scripts/sync-openapi.mjs copie app/api/openapi.yaml vers public/openapi.yaml, où starlight-openapi le lit, en faisant au passage pointer les liens relatifs de la spécification vers les fichiers sources correspondants. La copie est aussi publiée à /openapi.yaml.
  3. scripts/generate-schema-docs.mjs analyse app/schema.sql et écrit les pages developers/database/ (une vue d’ensemble, une page par table et le visualiseur de schéma) ainsi que le schema.json que lit le visualiseur.
  4. scripts/sync-install-config.mjs analyse docs/install/config/aa.env.example pour en faire un partial Starlight que le guide d’installation importe.
  5. scripts/sync-roadmap.mjs écrit la page Feuille de route, qui affiche le fichier src/content/roadmap/roadmap.json de ce dépôt. C’est la seule étape qui ne lit rien dans le dépôt principal.
  6. scripts/sync-screenshots.mjs copie les captures d’écran du produit utilisées par la page d’accueil depuis docs/screenshots/ vers src/assets/screenshots/ pour qu’Astro puisse les optimiser.

Ajouter une autre étape de génération revient à l’ajouter aux deux chaînes prebuild et predev.