Contrôler la documentation DocC sur un Mac cloud en CI

Après le renommage d’une API publique par une équipe, le projet local peut encore se compiler alors que les anciens liens vers les symboles dans la documentation ne fonctionnent plus. Le problème n’apparaît généralement qu’au moment de parcourir manuellement la documentation avant une publication. Une méthode plus fiable consiste à exécuter un build DocC lors de chaque contrôle de fusion sur le Mac cloud. Les références impossibles à résoudre, les sujets en double et les avertissements de compilation provoquent alors directement l’échec du contrôle, tandis que le site statique et les journaux de diagnostic sont conservés comme artefacts.

Commencer par définir le périmètre du contrôle

Le contrôle DocC ne doit pas prendre en charge toutes les vérifications de la documentation. DocC est particulièrement adapté à la validation des symboles Swift, des répertoires d’articles, de la hiérarchie des sujets et des références internes. La disponibilité des URL externes et la cohérence du style rédactionnel doivent faire l’objet de tâches distinctes. Sans cette séparation, une simple expiration temporaire du délai réseau pourrait bloquer la fusion du code.

Il est recommandé de définir d’abord trois catégories de résultats :

L’objectif d’un contrôle de documentation n’est pas d’éliminer toutes les remarques, mais d’obtenir la même conclusion à partir des mêmes entrées dans un environnement fixe. Les règles doivent pouvoir être reproduites avec une commande identique sur les postes de développement et les nœuds CI.

L’arborescence doit également conserver une source unique de vérité. La documentation d’un module doit se trouver dans le répertoire .docc du target correspondant, tandis que les guides couvrant plusieurs modules doivent être placés dans le target de documentation chargé de les regrouper. Il ne faut pas copier le même article dans plusieurs catalogues, au risque de n’en mettre à jour qu’un seul après une révision.

Verrouiller Xcode et les entrées du build

Sur les nœuds distants, la dérive provient le plus souvent du chemin Xcode sélectionné par défaut. Au début de la tâche, il faut donc afficher la version, puis vérifier explicitement le répertoire des outils de développement. Si l’équipe maintient plusieurs versions, le chemin complet peut être transmis par une variable CI plutôt que de dépendre du choix conservé par une précédente session interactive.

set -euo pipefail

: "${DEVELOPER_DIR:?set DEVELOPER_DIR}"
: "${SCHEME:?set SCHEME}"

test -x "$DEVELOPER_DIR/usr/bin/xcodebuild"
xcodebuild -version
swift --version
git status --short

L’état du dépôt doit également être vérifié avant le build. La CI doit partir d’un checkout propre. Les fichiers de résolution des dépendances doivent être placés sous contrôle de version, et les ressources nécessaires à la génération de la documentation ne doivent pas dépendre de copies locales présentes dans le répertoire d’un développeur. Si un script génère du Markdown, il faut d’abord produire le résultat dans un répertoire temporaire, puis le comparer. La tâche doit échouer si des différences non validées sont détectées.

Éviter l’état implicite du workspace

Il ne faut pas réutiliser un répertoire DerivedData persistant. D’anciens graphes de symboles peuvent maintenir des types supprimés dans la documentation ou masquer l’absence de ressources. Chaque tâche doit utiliser un répertoire isolé et n’archiver à la fin que les diagnostics et les artefacts DocC nécessaires.

Exécuter un docbuild reproductible

Le script suivant crée un répertoire isolé pour chaque tâche, transforme les avertissements DocC en erreurs et conserve le journal complet. generic/platform=iOS ne dépend d’aucun simulateur déjà démarré. Cette destination convient donc aux contrôles qui nécessitent uniquement de compiler les graphes de symboles et la documentation.

set -euo pipefail

ROOT="$PWD/.build/docs"
DERIVED="$ROOT/DerivedData"
LOG="$ROOT/docc-build.log"

rm -rf "$ROOT"
mkdir -p "$ROOT"

set -o pipefail
xcodebuild docbuild \
  -scheme "$SCHEME" \
  -destination "generic/platform=iOS" \
  -derivedDataPath "$DERIVED" \
  OTHER_DOCC_FLAGS="--warnings-as-errors" \
  2>&1 | tee "$LOG"

ARCHIVE="$(find "$DERIVED/Build/Products" -name '*.doccarchive' -print -quit)"
test -n "$ARCHIVE"
printf '%s
' "$ARCHIVE" > "$ROOT/archive-path.txt"

Si le scheme contient également des targets pour lesquels aucune documentation ne doit être générée, le périmètre de compilation de la documentation doit être défini explicitement dans les réglages du projet. Il ne faut pas filtrer les avertissements dans les journaux, car cela masquerait aussi de véritables régressions. Lors de la première activation de --warnings-as-errors, il est possible de commencer par une exécution non bloquante. Une fois les problèmes existants corrigés, la tâche peut devenir un contrôle obligatoire avant fusion.

Exporter le site statique et vérifier les artefacts

Un fichier .doccarchive convient aux traitements ultérieurs, mais les personnes chargées de la revue ont généralement besoin de fichiers statiques directement consultables. Une fois l’archive trouvée, le site est généré avec la commande de conversion fournie par DocC :

set -euo pipefail

ARCHIVE="$(cat .build/docs/archive-path.txt)"
OUTPUT="$PWD/.build/docs/site"

xcrun docc process-archive transform-for-static-hosting \
  "$ARCHIVE" \
  --output-path "$OUTPUT" \
  --hosting-base-path docs

test -s "$OUTPUT/index.html"
find "$OUTPUT" -type f | sort > .build/docs/site-files.txt

--hosting-base-path doit correspondre au sous-chemin de déploiement final. Si le site est réellement publié à la racine, il ne faut pas reprendre docs tel quel. En cas de divergence, la page d’accueil peut sembler fonctionner lorsqu’elle est ouverte localement, alors que les scripts et les feuilles de style renverront des erreurs après le déploiement.

Il faut au minimum archiver le journal de build, le chemin de l’archive, le site statique et la liste des fichiers. Le journal permet d’identifier précisément les diagnostics, tandis que la liste des fichiers aide à repérer des suppressions massives anormales. Le site statique peut avoir une durée de conservation plus courte, mais les journaux des tâches en échec doivent être conservés jusqu’à la résolution du problème.

Séparer le contrôle des liens externes

Le contrôle des liens externes doit analyser le HTML généré, ne tester que les adresses https autorisées et limiter le nombre de requêtes simultanées. Les expirations de délai et les limitations imposées par les serveurs peuvent faire l’objet de quelques nouvelles tentatives ; seuls les échecs persistants doivent bloquer le contrôle. Les liens contenant des jetons temporaires, des paramètres de requête ou des adresses internes ne doivent figurer ni dans la documentation publique ni dans les journaux de contrôle.

Traiter les échecs courants et établir une checklist de validation

Lorsqu’un symbole existe mais reste introuvable pour DocC, trois causes sont généralement possibles : le symbole n’appartient pas au scheme actuel, son niveau d’accès ne relève pas du périmètre documenté, ou le lien utilise une ancienne signature complète. Il faut commencer par vérifier le target, puis consulter les symboles candidats dans le journal généré, plutôt que de modifier l’orthographe à répétition au hasard.

Lorsqu’un lien d’article ne fonctionne plus, il faut contrôler le nom du fichier, l’identifiant produit à partir du titre et le niveau relatif dans l’arborescence. En cas d’échec du chargement d’une ressource, il convient de vérifier la casse et l’appartenance au target. Le système de fichiers dans le cloud respecte fidèlement les chemins réels. Une casse incorrecte qui ne fonctionne que par hasard dans certains environnements locaux ne doit pas être conservée.

Le contrôle final doit permettre de répondre aux questions suivantes :

• Les versions de Xcode et de Swift ont-elles été consignées ?
• Le workspace était-il propre au démarrage ?
• Les avertissements DocC ont-ils été traités conformément aux règles définies ?
• L’archive attendue a-t-elle été trouvée et a-t-elle été la seule à être traitée ?
• Le point d’entrée du site statique existe-t-il ?
• Le journal de build et la liste des fichiers ont-ils été archivés ?
• Les erreurs de liens externes sont-elles signalées séparément des erreurs de compilation DocC ?

Lorsque toutes ces vérifications sont exécutées par le même script, les modifications de documentation disposent d’un état d’échec aussi reproductible que les modifications de code. Les responsables de la maintenance peuvent retrouver une référence à partir du journal, examiner la structure grâce aux artefacts statiques et comparer clairement les différences de comportement après une mise à niveau de Xcode.

Questions fréquentes