Migrer depuis TypeDoc

Ardo 6 retire l’intégration TypeDoc. La documentation source utilise TypeScript natif pour vérifier les déclarations et OXC pour extraire le Markdown. Cela concerne typedoc, TypeDocConfig, ardo/typedoc, ardo/typedoc/components et les options TypeDoc de l’ancien générateur create-ardo.

Installer les outils natifs

Installez le compilateur et le parseur compatibles dans le projet de documentation :

pnpm add -D typescript@7.1.0-dev.20261011.1 oxc-parser@^0.155.0

Le compilateur est une nightly TypeScript 7.1 épinglée et vérifie aussi les types. L’API native 7.0 ne fournit pas les fonctions requises. Les sites généraux n’ont pas besoin de ces paquets optionnels. Retirez les dépendances TypeDoc et plugins utilisés uniquement par l’ancienne intégration.

Mettre à jour la configuration Ardo

Retirez typedoc de l’ancienne configuration Vite. Ajoutez api à ardo.config.ts avec une configuration TypeScript explicite :

import { defineArdoConfig } from "ardo/config"

export default defineArdoConfig({
  api: {
    entryPoints: ["./src/index.ts"],
    tsconfig: "./tsconfig.api.json",
    out: "api-reference",
    title: "API Reference",
  },
})

Toute option typedoc, même typedoc: false, déclenche une erreur de migration. Retirez-la pour désactiver la génération. api: true utilise src/index.ts et tsconfig.json; une frontière explicite est utile si application de documentation et sources partagent un dossier :

{
  "extends": "./tsconfig.json",
  "files": ["src/index.ts"],
  "include": []
}

Incluez les déclarations ambiantes nécessaires dans files. Ardo émet des déclarations vérifiées et conserve les commentaires en mémoire sans modifier la configuration ni écrire sur disque. Les erreurs initiales bloquent le build. En développement, les dernières pages valides restent disponibles et l’overlay affiche les erreurs ; la génération reprend après correction.

Adapter les personnalisations

L’extracteur respecte @internal et n’étend pas les membres privés ou protégés. Sélectionnez les exports via vos entrées publiques. Revoyez les exclusions et regroupements TypeDoc au lieu de supposer un résultat identique. L’organisation et certains chemins changent : vérifiez les liens après régénération.

Pour plusieurs paquets, configurez un tableau de projets aux sorties distinctes, comme dans Plusieurs paquets. L’installation et la frontière de l’application restent identiques.

Adapter les hôtes programmatiques

Remplacez generateApiDocs d’ardo/typedoc par l’API native ponctuelle :

import { generateNativeDocs } from "ardo/api"

await generateNativeDocs(
  { entryPoints: ["./src/index.ts"], tsconfig: "./tsconfig.api.json" },
  "./app/routes"
)

Pour un watcher personnalisé, réutilisez NativeApiProject, passez les chemins absolus modifiés, créés et supprimés à extract ou generate, puis fermez le projet à l’arrêt. L’intégration Vite gère déjà ce cycle.

Ardo 6 retire create-ardo. Les instructions pour les agents et la documentation API couvrent outils natifs, configuration et exemple. Migrez la configuration Vite personnalisée plutôt que de la remplacer.

Vérifier la migration

Lancez types et build, inspectez les pages et liens API, puis testez une modification source ou JSDoc en développement. Gardez le contenu manuel hors du dossier généré. Les pages Ardo sont mises à jour sur place, les obsolètes supprimées ; les dossiers manuels non marqués sont protégés.

Le compilateur natif peut refuser du code accepté par TypeScript JavaScript. L’extracteur ne couvre pas toutes les fonctions TypeDoc : namespaces, liens sources, TSDoc complet et membres mappés ou conditionnels restent des limites. Une expansion non prise en charge conserve l’expression et produit un diagnostic. Examinez-les pour votre API. Pour différer ce changement, conservez votre version et configuration Ardo précédentes.