Aller au contenu

Générer la documentation technique

La documentation d'API interne de BCard est produite par phpDocumentor à partir des docblocks présents dans src/.

Prérequis

  • PHP ≥ 8.2 en ligne de commande
  • L'archive phpDocumentor.phar à la racine du projet

Le .phar pèse une trentaine de mégaoctets : il est volontairement exclu du dépôt (.gitignore). Pour l'installer :

curl -L https://github.com/phpDocumentor/phpDocumentor/releases/latest/download/phpDocumentor.phar -o phpDocumentor.phar

Vérification :

php phpDocumentor.phar --version

Générer

Depuis la racine du projet :

php phpDocumentor.phar

La configuration est lue dans phpdoc.dist.xml. Aucune option supplémentaire n'est nécessaire.

Élément Emplacement
Sortie HTML docs/api-reference/
Cache d'analyse var/phpdoc/

Ouvrez ensuite docs/api-reference/index.html dans un navigateur.

Les deux répertoires sont exclus du dépôt : la documentation est un artefact régénérable, elle n'a pas vocation à être versionnée.

Regénérer intégralement

En cas de rendu incohérent après un changement important, videz le cache :

rm -rf var/phpdoc docs/api-reference
php phpDocumentor.phar

Configuration

phpdoc.dist.xml définit :

  • Source : src/ uniquement.
  • Exclusions : vendor/, var/, public/, tests/.
  • Visibilité : public, protected et private. Les méthodes privées portent une part importante de la logique métier (handlers de webhooks Stripe, helpers de contrôleurs) ; les exclure priverait la documentation de l'essentiel.
  • Graphes : désactivés (ils exigent l'outil Graphviz, absent des postes de développement).

Le portail documentaire

phpDocumentor produit la référence du code. Les pages rédigées de docs/ et cette référence sont assemblées en un site unique par Material for MkDocs.

Élément Emplacement
Configuration du site mkdocs.yml
Pages rédigées docs/*.md
Référence du code docs/api-reference/ (généré)
Site assemblé var/docs-site/ (généré)
Dépendances Python docs/requirements.txt

Consulter le portail

Rédaction, avec rechargement automatique à chaque enregistrement :

docker compose --profile docs up docs

→ http://localhost:8000

Site figé, tel qu'il sera déployé :

docker compose --profile docs up docs-static

→ http://localhost:8080

Référence du code en mode rédaction

Le service docs sert les pages Markdown montées depuis le disque ; il ne lance pas phpDocumentor. L'onglet Référence du code n'est donc rempli que si php phpDocumentor.phar a déjà tourné localement. Le service docs-static, lui, génère la référence pendant la construction de l'image.

L'image Docker n'utilise pas le .phar versionné

docker/docs/Dockerfile télécharge phpDocumentor.phar en version latest depuis GitHub au lieu de réutiliser le .phar versionné (3.9.1) présent à la racine du dépôt : .dockerignore exclut ce fichier du contexte de build, ce qui empêche de le copier dans l'image. Conséquence : la référence du code produite par docker compose --profile docs up docs-static peut différer de celle produite en local par php phpDocumentor.phar si une nouvelle version de phpDocumentor a été publiée entre-temps.

Ajouter une page

  1. Créer le fichier dans docs/.
  2. Déclarer la page dans la clé nav de mkdocs.yml — une page absente de la nav fait échouer le build en mode strict.
  3. Vérifier : docker compose --profile docs up docs-static --build.

Conventions de docblock

Les docblocks du projet sont rédigés en français, les identifiants de code restant en anglais. Le format retenu :

Classe

/**
 * Rôle du contrôleur ou du service, en une phrase.
 *
 * Une à quatre phrases sur le périmètre métier, les règles notables et les acteurs concernés.
 *
 * Préfixe de route : `/xxx`. Authentification requise (`IS_AUTHENTICATED`).
 */

Méthode de contrôleur

/**
 * Action réalisée par la méthode.
 *
 * Détail de la logique métier, des contrôles, des effets de bord et des cas d'erreur.
 *
 * Route : `/chemin/complet` (GET, POST), nom `nom_de_la_route`.
 *
 * @param Request $request Description du paramètre.
 *
 * @return Response Description du retour, y compris les différentes branches.
 * @throws \LogicException Condition dans laquelle l'exception est levée.
 */

Méthode d'API

Ajouter le contrat HTTP :

 * Corps attendu : `{"email": "string — adresse de connexion", "password": "string"}`
 *
 * Réponses : 200 succès, 400 charge utile invalide, 401 identifiants incorrects.

Règles

  • Décrire ce que le code fait réellement, jamais une paraphrase du nom de la méthode.
  • Indiquer systématiquement le chemin de route complet (préfixe de classe inclus) et le rôle requis lorsqu'un attribut #[IsGranted] est présent.
  • Typer les tableaux précisément : array<string, mixed>, list<Contact>.
  • Documenter les effets de bord des services : écritures en base, envois d'e-mails, appels HTTP externes, écritures de fichiers.
  • Ne jamais supprimer un @deprecated existant.