Comment générer automatiquement des docs à partir du code — CI

Structurer les sources de vérité doc-générables dans le repo

Versionnez les contrats avec le code applicatif. Placez REST sous /specs/openapi, GraphQL sous /schema/graphql et gRPC sous /proto; ces chemins donnent des filtres CI simples et ciblés.

Pipeline CI/CD: build, préviews et déploiement des docs

Un workflow GitHub Actions dédié déclenche la chaîne docs sur push et pull_request, puis exécute lint, build et publication sans dépendre du langage applicatif (source: GitHub Actions documentation (consulted 2026-07)).

on: [push, pull_request]
jobs:
  docs:
    strategy:
      matrix:
        path: [specs, proto, packages/*]

Générer la référence d’API depuis REST, GraphQL et gRPC

La référence générée doit lire uniquement les contrats versionnés du repo: openapi.yaml, schema.graphql, JSON d’introspection et fichiers .proto.

Placez des exemples exécutables à côté des opérations générées:

curl -sS ${API_URL}/users/${USER_ID}

query User($id: ID!) { user(id: $id) { id email } }

grpcurl -plaintext -d '{}' ${GRPC_HOST} users.UserService/ListUsers

Les badges doivent venir des métadonnées: deprecated: true et une extension de stabilité côté OpenAPI, directive @deprecated côté GraphQL, option de dépréciation ou option custom côté .proto.

Contrôler la dérive: gates de couverture et diff de contrats

Le gate principal compare le contrat généré au contrat de référence. Si le diff OpenAPI, SDL GraphQL ou .proto supprime un champ, renomme un enum, durcit une validation ou change un type, le job échoue sauf si la PR porte le marqueur breaking-change.

Gates à exécuter sur chaque PR

Mesurez la couverture seulement sur les fichiers modifiés: symboles exportés, endpoints, queries, mutations, messages et services doivent avoir un commentaire exploitable. Le seuil vient du repo, par exemple docs/coverage.yml, pas du script CI.

Validez chaque exemple versionné contre le contrat courant. Une request exemple doit parser, respecter les champs requis et produire une réponse conforme au schéma attendu; sinon le job bloque.

Diff révisable

Générez un changelog de docs attaché à la PR: contrats modifiés, symboles sans commentaire, exemples revalidés ou rejetés. Le reviewer lit l’écart documentaire dans le même diff que le code.

Publication, versioning et contributions côté docs

Publier par release, pas par branche

Taguez le site de docs avec la même release que l’API ou le SDK publié. Le sélecteur de version affiche alors la documentation correspondant au client installé, au lieu de mélanger main, beta et versions maintenues. Docusaurus fournit un mécanisme de versioning des docs et un sélecteur associé (source: Docusaurus documentation (Meta Open Source, consulted 2026-07)).

Conservez les anciennes versions en lecture seule. Une correction de typo passe encore, mais aucun changement de contrat ne doit être backporté sans release produit associée.

Rendre la contribution triviale

Activez le lien « Modifier cette page » vers le fichier Markdown, MDX ou généré qui sert de source. Un dev corrige un exemple cassé depuis la page publiée; un PM ajuste une description sans chercher le chemin dans le repo.

Fermer la boucle après déploiement

Générez l’index de recherche et les URLs canoniques pendant le build. Après déploiement, déclenchez les mises à jour prévues par votre pile de recherche et d’analytics avec les URLs finales.

Ajoutez make docs au repo pour reproduire localement le rendu CI. La preview de PR valide navigation, recherche, liens canoniques et version affichée avant merge.